POST
/v1/agent/conversations/messages
Start Conversation
Send the first message to a customer by **number**, without knowing a conversation id.
The server decides which conversation it lands on, and that is the point of this route: the customer's open thread if they have one, otherwise their last resolved one revived and claimed by this agent, otherwise a new conversation. So a follow-up continues the customer's history instead of starting a second thread beside it. The caller cannot pre-empt that decision, which is why there is no id in the path — and why the reply carries the conversation the server chose. Follow that id; do not keep your own.
The conversation and its first activity are created together on purpose. An outbound send reads the business number off the thread's last messaging activity, so a conversation with no activity could never send one.
Unlike `/conversations/{id}/messages`, both `to` and `cli` are **required** here: there is no existing thread to infer either from.
curl -X POST https://api.{cluster}.{platform}.voiger.io/v1/agent/conversations/messages \
-H "Cookie: sid=$VOIGER_SESSION" \
-H "x-workspace-code: your-workspace-code" \
-H "x-csrf-token: $CSRF_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"to": "+919945923278",
"text": {
"body": "Hello, following up on your enquiry."
},
"cli": {
"id": "6d1f2a3b-4c5d-6e7f-8091-a2b3c4d5e6f7",
"reference_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
"type": "queue"
}
}'
const res = await fetch("https://api.{cluster}.{platform}.voiger.io/v1/agent/conversations/messages", {
method: "POST",
credentials: "include",
headers: { "x-workspace-code": "your-workspace-code" },
headers: { "Content-Type": "application/json", "x-csrf-token": csrf },
body: JSON.stringify({
"type": "text",
"to": "+919945923278",
"text": {
"body": "Hello, following up on your enquiry."
},
"cli": {
"id": "6d1f2a3b-4c5d-6e7f-8091-a2b3c4d5e6f7",
"reference_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
"type": "queue"
}
}),
})
const data = await res.json()
Parameters
x-workspace-code
string
required
in header
x-csrf-token
string
required
in header
type
string
What this activity IS -- the one field a renderer switches on. A message's own kind (`text`, `image`, ...), or `call`, `note`, `event`. Distinct from `channel`, which is the medium it rode: a call is `type: "call"`, `channel: "voice"`. A client must tolerate a value it does not know rather than failing to render the thread.
channel
string | null
The medium. `null` for a lifecycle event, which rode none. Was called `type`; the database column has been `channel` since September and the value `call` became `voice` in October, and this finishes that rename.
event
string
Which lifecycle event this is. Sent only when `type` is `event`.
direction
string
A message or a call. Not sent on a note or a lifecycle event.
status
string
Where this activity has got to. TWO vocabularies, told apart by `type`: a message's delivery state, or a call's state. They are disjoint, so a value is never ambiguous. A call's OUTCOME is `result`, inside `data` -- `status` says where the call is, `result` says how it ended. Not sent on a note or an event.
external_id
string
The provider's own id for this activity -- a WhatsApp `wamid` today. Sent whenever we have one, so a client can reconcile with the provider. Was `provider_message_id`, stored inside `data` and never sent.
actor
any
Who did this. On every activity, whatever its kind — the sender of a message, the customer who wrote in, the agent a call belongs to, whoever caused an event. `system` when routing, a timer or an auto-reply did it.
from
any
The source party. The customer, on an inbound message; who lost the conversation, on an `assigned` or `queue_set` event. Not sent on an outbound message or a call — a call says `caller`/`callee` inside `data`.
to
any
The target party. The customer, on an outbound message; who the conversation went to, on an `assigned` event. Not sent on an inbound message or a call.
cli
any
Our own number. Sent on a message only.
data
any
The body. `type` says which of these it is -- a message, the call object, a note, or whatever a lifecycle event carries beyond its header. `anyOf` rather than `oneOf` because the discriminator is a sibling of `data`, not a field inside it, so a validator cannot pick the branch on its own.
json · 201
{
"conversation": {
"id": "6f1c2a90-4d3b-11ee-be56-0242ac120002",
"status": "open",
"state": "assigned",
"channels": {
"whatsapp": {}
},
"created_at": "2026-09-29T17:22:40.865214Z",
"updated_at": "2026-10-11T08:19:16.910000Z"
},
"activity": {
"id": "f49a462f-20a9-4147-8253-1b019548bddc",
"type": "text",
"channel": "whatsapp",
"created_at": "2026-10-11T08:19:16.910000Z",
"direction": "outbound",
"status": "pending",
"actor": {
"type": "agent",
"reference_id": "6feb3aa5-e6d0-4931-aadd-5edd828bdb95"
},
"to": {
"type": "customer",
"phone": "+919945923278"
},
"cli": {
"id": "c0nnect0-0000-4000-8000-000000000001",
"reference_id": "7b2e1f4a-0c33-4d21-9e88-5a1b2c3d4e5f",
"type": "queue",
"phone": "+971542959591"
},
"data": {
"text": "Hello, following up on your enquiry."
}
}
}