Chat

Chat tools act as the client speaking with an agent. To manage owners, status, tags, or send messages from the business side, use the Conversations and Messages tools.

See the complete contract in the Chat API . REST failures are returned as MCP execution errors; see MCP Errors .

Tool	REST endpoint	Annotations
`list_chats`	`GET /v1/chat`	read-only, idempotent
`get_chat`	`GET /v1/chat/{id}`	read-only, idempotent
`send_chat_message`	`POST /v1/chat`	write, non-destructive

`list_chats`

Lists every chat with source: "api_chat" from authorized workspaces, without filtering by the user who created it.

Field	Type	Default	Description
`clientId`	`string`	—	Filter by attributed client.
`agentId`	`string`	—	Filter by principal agent.
`limit`	`1-200`	`50`	Maximum results.
`offset`	`≥ 0`	`0`	Pagination offset.

Each result includes the full Conversations summary without messages: id, conversationId, clientId, agentId, canSendDirectMessage, workspaceId, channelId, contactName, phoneNumber, topic, platform, source, status, operation, messageCount, owners, tags, creationDate, and lastUpdate. canSendDirectMessage is always true for these internal chats.

`get_chat`

Retrieves a chat's state and normalized message history.

Field	Type	Required	Description
`id`	`string`	yes	Unique, canonical document ID.

As a deprecated fallback, id also accepts the chat_* conversationId. The flat response includes the full summary above plus messages; access requires an authorized workspace and source: "api_chat".

`send_chat_message`

Starts or continues an immediate or scheduled conversation with an agent.

Field	Type	Required	Description
`message`	`string`	yes¹	Client text.
`attachments`	`object[]`	yes¹	Up to 10 image/file URLs, each smaller than 20 MB.
`conversationId`	`string`	when continuing	Existing `chat_*`.
`agentId`	`string`	when creating	Initial agent; while continuing it can switch responders.
`additionalInstructions`	`string`	no	Instructions applied only to this turn.
`client`	object	no	Attributed client; when omitted on creation, uses the API-key user.
`delay`	`integer`	no	Delay from `3000` to `86400000` ms. Cannot be combined with `scheduleAt`.
`scheduleAt`	`string`	no	Future ISO 8601 date, up to 1 year ahead. Cannot be combined with `delay`.

¹ Send message, attachments, or both. Each attachment requires url and mimeType; filename is optional.

A closed conversation is automatically reactivated when another message is sent. Without conversationId, every call creates a new thread with another chat_<uuid>, even for the same client. clientId never substitutes for conversationId.

{
  "name": "send_chat_message",
  "arguments": {
    "agentId": "agent_123",
    "message": "Help me review my policy",
    "attachments": [
      {
        "url": "https://cdn.example.com/policy.pdf",
        "mimeType": "application/pdf",
        "filename": "policy.pdf"
      }
    ],
    "client": {
      "email": "ana@example.com",
      "customFields": {
        "policy_number": "GNP-123"
      }
    }
  }
}

To schedule the turn:

{
  "name": "send_chat_message",
  "arguments": {
    "agentId": "agent_123",
    "message": "Prepare a summary before the meeting",
    "scheduleAt": "2026-08-01T15:00:00-06:00"
  }
}

attachments, client, and additionalInstructions can also be included in a scheduled turn.

Immediate response

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "client_123",
  "agentId": "agent_123",
  "status": "completed",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [],
  "reactivated": false,
  "agentChanged": false,
  "timestamp": "2026-07-20T18:30:00.000Z"
}

Scheduled response

With delay or scheduleAt, the tool creates a fire-and-forget Cloud Task and returns the HTTP 202 result:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "client_123",
  "agentId": "agent_123",
  "status": "scheduled",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [],
  "schedule": {
    "taskId": "task_01JTASK23456789",
    "scheduleAt": "2026-08-01T21:00:00.000Z"
  },
  "timestamp": "2026-07-20T18:30:00.000Z"
}

schedule.scheduleAt is always normalized to UTC. When scheduling with delay, schedule also includes delayMs.

The result does not include an agent response. After scheduleAt, call get_chat with id. The id is preassigned, but the document may return 404 until the task runs.

A new conversation may not appear until the task runs.

Previous Tool catalog Next Messages