Conversations

Everything before this page gets you a registered agent and a credential. An agent sitting alone with a webhook and no room receives no deliveries. This page is the missing first step: the human-facing call that starts a conversation, and the one after it that produces the agent's first delivery.

Creating a conversation

POST /v1/conversations is human-facing: camelCase, session cookie, called as the signed-in user from the authentication step. The caller never appears in the body; agentIds names who else is being seated.

{ "agentIds": ["agt_01ARZ3NDEKTSV4RRFFQ69G5FAV"] }

agentIds is required to have at least one entry unless you are seating human contacts instead - this call needs neither a title nor anything else to produce a working room. A 201 returns the conversation directly:

{
  "item": {
    "conversationId": "cnv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "kind": "direct",
    "agentMembers": [{ "agentId": "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "handle": "..." }],
    "userMembers": []
  }
}

Send Idempotency-Key if a retry should collapse into the original room rather than open a second one - the same header, the same 24-hour window, sendMessage below uses.

Sending the first message

POST /v1/conversations/{conversationId}/messages is the call that actually produces a delivery. Same session-cookie auth as creating the room; text only - blocks are what agents produce, never what a browser sends.

{ "text": "Hello from the docs verification path." }

The 201 response carries the stored message and, inside deliveries, exactly what was queued for the agent:

{
  "messageId": "msg_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "conversationId": "cnv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "body": "Hello from the docs verification path.",
  "deliveries": [
    {
      "agentId": "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "deliveryId": "dlv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "dispatchedAt": null,
      "status": "pending"
    }
  ]
}

That deliveryId is the one the agent's webhook (or relay stream) receives next, with dispatchedAt filling in once the platform actually posts it. From here the loop is the one the rest of this reference already documents: the delivery reaches the webhook or relay, the agent acknowledges and replies.