Create Conversation

Open a conversation with a contact in one inbox, optionally sending the first message in the same call. A first message is attributed to the API key's owner and runs the same side effects as the in-app composer, including outbound delivery. When the contact already has a conversation in progress in that inbox, the call is refused with 409 and code: active_conversation_exists, and the blocking conversation is returned so it can be reused; conversations in the contact's other inboxes do not block. Every operation is scoped by the required workspaceId. A workspace-scoped API key that names any other workspace is refused with 403 before any query runs, so a workspace key can only ever reach its own workspace.

POST/api/v1/chat/conversations

Authorization

apiKey
X-API-Key<token>

Your Studio API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Request Body

application/json

Inbox, contact, initial routing, and an optional first message.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://agent-studio.seeyu.ai/api/v1/chat/conversations" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "string",    "inboxId": "string",    "contactId": "string"  }'
{
  "conversation": {
    "id": "conv_01J9M4Q0X6R7",
    "workspaceId": "ws_01J8F2K3N5P7",
    "inboxId": "inb_01J8F2K3N5P8",
    "contactId": "cnt_01J8F2K3N5P9",
    "assigneeId": "usr_01J8F2K3N5PA",
    "teamId": null,
    "status": "open",
    "priority": "high",
    "lastActivityAt": "2026-08-28T14:22:05.000Z",
    "createdAt": "2026-08-27T09:10:44.000Z",
    "contact": {
      "id": "cnt_01J8F2K3N5P9",
      "name": "Ana Ribeiro",
      "email": "ana@example.com",
      "phone": "+5511987654321",
      "avatarUrl": null
    },
    "inbox": {
      "id": "inb_01J8F2K3N5P8",
      "name": "Support — WhatsApp",
      "channelType": "whatsapp"
    },
    "assignee": {
      "id": "usr_01J8F2K3N5PA",
      "name": "Marcos Lima",
      "avatarUrl": null
    },
    "lastMessage": {
      "id": "msg_01J9M4Q0X6RA",
      "content": "Thanks, that fixed it!",
      "messageType": "incoming",
      "createdAt": "2026-08-28T14:22:05.000Z"
    },
    "agentLastSeenAt": "2026-08-28T14:20:00.000Z",
    "additionalAttributes": null,
    "customAttributes": {
      "plan": "pro"
    },
    "unreadCount": 2
  }
}
{
  "error": "Invalid input: expected string, received undefined",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "path": [
        "phone"
      ],
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}
{
  "error": "Unauthorized"
}
{
  "error": "API key is not authorized for this workspace"
}
{
  "error": "This contact already has a conversation in progress",
  "code": "active_conversation_exists",
  "conversation": {
    "id": "conv_01J9Z2K3M4N5P6Q7R8S9T0",
    "inboxId": "inbox_01J9Z2K3M4N5P6Q7R8S9T0",
    "inboxName": "Support",
    "status": "open",
    "teamName": "Tier 1",
    "assigneeId": null,
    "assigneeName": null,
    "aiAgentActive": false
  }
}
{
  "error": "Rate limit exceeded",
  "message": "API rate limit exceeded. Please retry after 2026-09-13T12:00:00.000Z",
  "retryAfter": 1789286400000
}
{
  "error": "Internal server error",
  "requestId": "req_01J9Z2K3M4N5P6Q7R8S9T0"
}
Chat API (v1)GETGet Conversation