Agent/Start Conversation
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.

Base URL https://api.{cluster}.{platform}.voiger.io
Request · cURL
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"
       }
     }'

Parameters

x-workspace-code string required in header
x-csrf-token string required in header

Response

conversation
any
activity▾
object
id
string
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.
created_at
string
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.