Conversations

We are the system of record for a merchant’s conversations. Your product reads them, replies into them, and decides when a person should take over.

These routes need messages:read and messages:write. They are deliberately not covered by assistants:write — a key issued to edit a prompt should not thereby be able to message a merchant’s customers.

Reading

GET /api/v1/partner/tenants/{ref}/conversations/
GET /api/v1/partner/tenants/{ref}/conversations/{id}/
GET /api/v1/partner/tenants/{ref}/conversations/{id}/messages/?limit=50&after={message_id}

Messages page oldest-first on a stable cursor.

{ "object": "list", "data": [ … ], "has_more": true, "next_cursor": "…" }

limit is 1–100, default 50. A cursor naming nothing in this conversation is a 400, not an empty page — silently returning the first page would make a paging client loop forever.

The message shape

{
  "id": "…",
  "object": "message",
  "conversation": "…",
  "role": "user",
  "type": "text",
  "text": "Do you deliver to Kochi?",
  "created_at": "2026-09-07T10:12:00Z",
  "channel": {
    "name": "whatsapp",
    "message_id": "wamid.HBg…",
    "from": "+919876543210",
    "media": { "mime": "audio/ogg", "transcription": "…" },
    "template": { "name": "order_update" }
  }
}

role has three values and the third one is the point. user is the customer, assistant is the AI, and human is a person — a salesperson replying from the WhatsApp Business App, or your own team through this API.An inbox that renders assistant and human identically is an inbox showing its operator something untrue.

Never present: prompts, retrieval evidence, token counts, internal reply-button ids, or Meta media ids — the last are useless without the merchant’s own access token anyway.

Sending

POST /api/v1/partner/tenants/{ref}/conversations/{id}/messages/send/

{ "type": "text", "text": "Yes — next-day delivery to Kochi.", "reply_to": "wamid.…" }

string

default:"text"

text, template, image, video, audio, document, interactive, location or reaction.

string

A channel.message_id from this thread. WhatsApp draws it as a quoted reply, which is how an answer to a question asked four messages ago stops reading like a non-sequitur.

`type`	Fields
`text`	`text`
`template`	`template_name`, `lang` (default `en_US`), `body_params[]`
`image` `video` `audio` `document`	`link` or `media_id`, `caption`, `filename`
`interactive` `location` `reaction`	`payload` — the Cloud API object

Prefer link over media_id wherever a public URL exists: Meta fetches and caches by URL, so one catalogue photo sent to a thousand customers is fetched once instead of uploaded once and served a thousand times. 201 returns the stored message and the conversation. It is recorded as role: "human" and fires message.sent like any other outbound message.

Two failures to handle

422 outside_customer_service_window

The 24-hour window has closed and this is not a template.

{ "error": {
    "code": "outside_customer_service_window",
    "message": "The 24-hour customer service window is closed. Send an approved template instead.",
    "window": { "open": false, "last_inbound_at": "…", "expires_at": "…" }
} }

Checked before Meta is called, so you get a named condition and a remedy rather than an unmapped provider error. Read window.expires_at off the conversation and show a countdown instead of discovering the limit by failing.

502 channel_rejected

Meta refused the message. Their words are in the body. Common causes: a template that is not approved yet, a number that has been blocked by the recipient, or a media URL Meta could not fetch.

Taking over from the assistant

POST /api/v1/partner/tenants/{ref}/conversations/{id}/handoff/

{ "on": true, "reason": "agent_took_over" }

While a human holds a conversation the assistant stays silent and stops nudging. Send {"on": false} to give it back. Handover is a judgement somebody made, so only somebody releases it. The one exception is credit exhaustion: a conversation paused because the merchant ran out of credits resumes on its own when they top up, provided no human has replied in the meantime.

The merchant’s own staff can do this from their phone. Replying from the WhatsApp Business App takes over automatically, and /human, /ai and /clear pause, release and wipe a thread. Every one of those reaches you as handoff.requested — so your inbox stays correct even when nobody used your UI.

Asking the assistant to answer

POST /api/v1/partner/tenants/{ref}/conversations/{id}/turns/

{ "text": "optional message to inject first", "force": false }

202, and the turn runs asynchronously — the reply arrives as message.sent. Useful for a “draft a reply” button, or to re-run a turn that failed on a provider outage. Refused with 409 human_control while a human holds the conversation, unless you pass force. Without that, your own takeover would be silently undone by your own next call.

What a conversation looks like

{
  "id": "…",
  "object": "conversation",
  "status": "waiting_reply",
  "channel": "whatsapp",
  "agent": "…",
  "turns": 6,
  "contact": { "name": "Priya", "phone": "+919876543210", "lead_id": "…" },
  "human_control": { "on": false, "reason": "", "since": "" },
  "window": { "open": true, "last_inbound_at": "…", "expires_at": "…" },
  "whatsapp_number": "106540352242922",
  "created_at": "…", "updated_at": "…"
}

whatsapp_number is the number this thread is happening on. Replies go out from it automatically — answering from a merchant’s other number would arrive, to the customer, as a message from a stranger.

Get started

Provisioning

Operating

Reading

The message shape

Sending

Two failures to handle

Taking over from the assistant

Asking the assistant to answer

What a conversation looks like

​Reading

​The message shape

​Sending

​Two failures to handle

​Taking over from the assistant

​Asking the assistant to answer

​What a conversation looks like

Reading

The message shape

Sending

Two failures to handle

Taking over from the assistant

Asking the assistant to answer

What a conversation looks like