Conversations

A conversation is one phone call and everything that came with it: the summary and agreements Ambula extracted, the caller, and the messages, photos, videos and locations the caller sent on WhatsApp. Its id is the call’s id.

Conversation webhooks carry only ids and the names of changed fields, so caller details stay out of your logs. Fetch the conversation for its current state.

List conversations

GET/v1/conversations

Requires the scope conversations:read.

Available from phase 1

Calls and their WhatsApp threads (gesprekken, meldingen), newest first.

Query parameters

statusstring

ringing, active or ended.

created_afterISO 8601

Only records created after this time.

created_beforeISO 8601

Only records created before this time.

updated_afterISO 8601

Only records changed after this time. For a sync, pass your last sync time minus 60 seconds and deduplicate by id.

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/conversations?updated_after=2026-11-09T08:00:00Z" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "c_93kLm0",
      "status": "ended",
      "caller": {
        "phone": "+31612345678",
        "contact_id": null
      },
      "summary": {
        "title": "Kat vast in boom",
        "text": "Melder ziet een kat die al sinds vanochtend vastzit…",
        "animal": "kat"
      },
      "location": {
        "address": "Dorpsstraat 1, Utrecht",
        "latitude": 52.0907,
        "longitude": 5.1214
      },
      "callback": {
        "status": "open",
        "who": "dispatcher",
        "when": "soon"
      },
      "counts": {
        "messages": 3,
        "images": 2,
        "videos": 0,
        "locations": 1
      },
      "started_at": "2026-11-09T08:02:11Z",
      "ended_at": "2026-11-09T08:05:47Z",
      "created_at": "2026-11-09T08:02:11Z",
      "updated_at": "2026-11-09T08:12:30Z"
    }
  ],
  "next_cursor": "WzE3MzEx…"
}

Get a conversation

GET/v1/conversations/{id}

Requires the scope conversations:read.

Available from phase 1

One conversation: its summary, agreements, callback, caller, location and counts of what the caller sent.

Request

curl "https://api.ambula.nl/v1/conversations/c_93kLm0" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "id": "c_93kLm0",
  "status": "ended",
  "caller": {
    "phone": "+31612345678",
    "contact_id": null
  },
  "summary": {
    "title": "Kat vast in boom",
    "text": "Melder ziet een kat die al sinds vanochtend vastzit…",
    "animal": "kat"
  },
  "location": {
    "address": "Dorpsstraat 1, Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214
  },
  "callback": {
    "status": "open",
    "who": "dispatcher",
    "when": "soon"
  },
  "counts": {
    "messages": 3,
    "images": 2,
    "videos": 0,
    "locations": 1
  },
  "started_at": "2026-11-09T08:02:11Z",
  "ended_at": "2026-11-09T08:05:47Z",
  "created_at": "2026-11-09T08:02:11Z",
  "updated_at": "2026-11-09T08:12:30Z"
}

List a conversation's messages

GET/v1/conversations/{id}/messages

Requires the scope conversations:read.

Available from phase 1

The WhatsApp messages in the conversation, oldest first: what the caller sent and the replies.

Query parameters

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/conversations/c_93kLm0/messages" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "m_1",
      "direction": "incoming",
      "text": "Hij zit nog steeds vast",
      "created_at": "2026-11-09T08:07:02Z"
    }
  ],
  "next_cursor": null
}

List a conversation's images or videos

GET/v1/conversations/{id}/images

Requires the scope conversations:read.

Available from phase 1

Photos the caller sent. /videos works the same way. Each url is a signed link valid for 15 minutes; fetch the list again for a new one.

Query parameters

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/conversations/c_93kLm0/images" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "img_1",
      "content_type": "image/jpeg",
      "url": "https://storage.googleapis.com/…",
      "thumbnail_url": "https://api.ambula.nl/v1/media/img_1/thumbnail",
      "expires_at": "2026-11-09T09:15:00Z",
      "created_at": "2026-11-09T08:06:40Z"
    }
  ],
  "next_cursor": null
}

List a conversation's locations

GET/v1/conversations/{id}/locations

Requires the scope conversations:read.

Available from phase 1

Locations the caller shared on WhatsApp, and the one geocoded from the call.

Request

curl "https://api.ambula.nl/v1/conversations/c_93kLm0/locations" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "loc_1",
      "source": "whatsapp",
      "latitude": 52.0907,
      "longitude": 5.1214,
      "address": null,
      "created_at": "2026-11-09T08:06:10Z"
    }
  ],
  "next_cursor": null
}

Get the call recording

GET/v1/conversations/{id}/recording

Requires the scope recordings:read.

Available from phase 2

A short-lived link to the call recording. Each request issues a new one.

Request

curl "https://api.ambula.nl/v1/conversations/c_93kLm0/recording" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "url": "https://…",
  "content_type": "audio/mpeg",
  "expires_at": "2026-11-09T09:15:00Z"
}

Update a conversation

PATCH/v1/conversations/{id}

Requires the scope conversations:write.

Available from phase 2

Change what a dispatcher can change: the title and summary shown, notes, the location hint, archiving, and the callback's status. Send If-Match with the ETag from your last read.

Body

titlestring

Shown instead of the generated title.

notesstring[]

Dispatcher notes.

location_hintstring

Where on the address the animal is, for example "achter het hek".

archivedboolean

Archive or restore the conversation.

callback_statusstring

done or dismissed.

Request

curl -X PATCH "https://api.ambula.nl/v1/conversations/c_93kLm0" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "If-Match: \"1731141150\"" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

Response · 200

{
  "id": "c_93kLm0",
  "status": "ended",
  "caller": {
    "phone": "+31612345678",
    "contact_id": null
  },
  "summary": {
    "title": "Kat vast in boom",
    "text": "Melder ziet een kat die al sinds vanochtend vastzit…",
    "animal": "kat"
  },
  "location": {
    "address": "Dorpsstraat 1, Utrecht",
    "latitude": 52.0907,
    "longitude": 5.1214
  },
  "callback": {
    "status": "open",
    "who": "dispatcher",
    "when": "soon"
  },
  "counts": {
    "messages": 3,
    "images": 2,
    "videos": 0,
    "locations": 1
  },
  "started_at": "2026-11-09T08:02:11Z",
  "ended_at": "2026-11-09T08:05:47Z",
  "created_at": "2026-11-09T08:02:11Z",
  "updated_at": "2026-11-09T09:02:00Z",
  "archived": true
}

Reply on WhatsApp

POST/v1/conversations/{id}/messages

Requires the scope messages:send.

Available from phase 4

Send the caller a WhatsApp message. Only within 24 hours of the caller's last message, and only when the company allows replies.

Side effect. Sends a WhatsApp message to the caller.

Body

textstringrequired

The message, up to 4,096 characters.

Request

curl -X POST "https://api.ambula.nl/v1/conversations/c_93kLm0/messages" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…" \
  -H "Content-Type: application/json" \
  -d '{"text":"De ambulance is onderweg."}'

Response · 201

{
  "id": "m_2",
  "direction": "outgoing",
  "text": "De ambulance is onderweg.",
  "created_at": "2026-11-09T08:30:00Z"
}

Create a conversation

POST/v1/conversations

Requires the scope conversations:write.

Available from phase 4

Body

callerobjectrequired

phone and, optionally, name.

descriptionstringrequired

What was reported.

locationobject

address, latitude and longitude.

Request

curl -X POST "https://api.ambula.nl/v1/conversations" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…" \
  -H "Content-Type: application/json" \
  -d '{"caller":{"phone":"+31612345678"},"description":"Gewonde reiger in de berm"}'

Response · 201

{
  "id": "c_44Hn2",
  "status": "ended",
  "source": "api",
  "created_at": "2026-11-09T10:00:00Z"
}