API reference

Your server uses the API to talk to an agent: it creates a chat for a customer, sends their messages and reads the agent's replies. It can also upload files, fill in the forms the agent asks for and pass the chat to your team.

Every request goes to https://turboagent.app/v1/channels/{channelKey}, where channelKey is the data-deployment value in the code to add to your website, with the agent's chat key in Authorization: Bearer ck_…. Call the API only from your server, so the key never reaches a customer's device. Requests with an Origin header, which browsers send, are refused.

Requests that change something take an Idempotency-Key header. If no answer comes back, send the same request with the same key: you get the first result, and nothing happens twice.

Errors are JSON, such as {"error":{"code":"rate_limited","message":"Too many requests. Try again shortly.","requestId":"rq_3f1c9a7e5b2d4c6a","retryAfterSeconds":2}}. Act on code; message may change. Successful responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. After a 429, wait Retry-After seconds, then send the same request again.

Limit
Message text	4,000 UTF-16 code units, the length JavaScript gives a string
Files	JPEG, PNG, GIF, WebP, PDF or plain text, up to 4 MiB each
Files in a chat	4 a message, 40 a chat and 80 MiB a chat
Unsent files	Deleted after a day
JSON body	32 KiB, or 2 MiB to submit a collection
Collection answers	20 a submission, 2,000 UTF-16 code units each
Messages a page	Up to 50, 20 if you don't say
Idempotency-Key	Kept 30 days to create a chat, and as long as the chat for the rest

The same reference as an OpenAPI 3.1 document: openapi.json.

Create a chat

POST /v1/channels/{channelKey}/chats

Starts a chat. Sending the same Idempotency-Key again returns the same chat, as it is now.

Headers

Name	Description
`Idempotency-Key`	8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.

Body (application/json)

Field	Description
`userId`	string. Optional. Your own ID for the customer: 8–128 letters, digits or . _ : -. It belongs to this channel and is not a sign-in.
`locale`	string. Optional. A BCP 47 language tag. Chats default to en.

{
  "userId": "shopper_123",
  "locale": "en"
}

Response 201, or 200 when the same Idempotency-Key is sent again

Field	Description
`item`	Chat. A chat between a customer and the channel's agent.

Example

{
  "item": {
    "id": "4b13b730-69d4-441c-8aee-42de75fef073",
    "channelKey": "dep_example123",
    "userId": "shopper_123",
    "mode": "agent",
    "teammate": null,
    "createdAt": "2026-10-12T09:00:00.000Z",
    "updatedAt": "2026-10-12T09:00:00.000Z",
    "resolvedAt": null,
    "historyComplete": true,
    "handoff": null
  }
}

Errors, besides those every operation can return

400: invalid_json, invalid_request
409: idempotency_conflict, idempotency_key_expired
410: idempotency_resource_gone
413: payload_too_large
415: unsupported_media_type
429: chat_limit_reached, capacity_limited

Get a chat

GET /v1/channels/{channelKey}/chats/{chatId}

Reads a chat: who is answering it and whether it is waiting for your team.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Response 200

Field	Description
`item`	Chat. A chat between a customer and the channel's agent.

Example

{
  "item": {
    "id": "4b13b730-69d4-441c-8aee-42de75fef073",
    "channelKey": "dep_example123",
    "userId": "shopper_123",
    "mode": "teammate",
    "teammate": {
      "name": "Alex"
    },
    "createdAt": "2026-10-12T09:00:00.000Z",
    "updatedAt": "2026-10-12T09:04:00.000Z",
    "resolvedAt": null,
    "historyComplete": true,
    "handoff": {
      "status": "claimed",
      "requestedAt": "2026-10-12T09:02:00.000Z",
      "requiresEmail": false,
      "nextAvailableAt": null,
      "timezone": "Europe/London"
    }
  }
}

Errors, besides those every operation can return

404: chat_not_found

Send a message

POST /v1/channels/{channelKey}/chats/{chatId}/messages

Sends the customer's message and returns the agent's reply. While the chat is with your team, the reply is null.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Headers

Name	Description
`Idempotency-Key`	8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.

Body (application/json)

Text, files or both. Text alone must contain more than spaces.

Field	Description
`text`	string. Optional. The customer's message. At most 4,000 UTF-16 code units.
`fileIds`	array of string. Optional. 1–4 uploaded files to send with the message.

{
  "text": "When are you open?"
}

Response 201, or 200 when the same Idempotency-Key is sent again

Field	Description
`item`	MessageTurn. A message sent, its reply and the chat afterwards.

Example: answered

{
  "item": {
    "message": {
      "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "visitor",
      "text": "When are you open?",
      "createdAt": "2026-10-12T09:00:01.000Z",
      "author": null,
      "files": [],
      "citations": [],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    "reply": {
      "id": "8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "agent",
      "text": "We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.",
      "createdAt": "2026-10-12T09:00:03.000Z",
      "author": null,
      "files": [],
      "citations": [
        {
          "title": "Opening times",
          "url": "https://shop.example/pages/opening-times",
          "updatedAt": "2026-10-01T08:00:00.000Z"
        }
      ],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    "chat": {
      "id": "4b13b730-69d4-441c-8aee-42de75fef073",
      "channelKey": "dep_example123",
      "userId": "shopper_123",
      "mode": "agent",
      "teammate": null,
      "createdAt": "2026-10-12T09:00:00.000Z",
      "updatedAt": "2026-10-12T09:00:03.000Z",
      "resolvedAt": null,
      "historyComplete": true,
      "handoff": null
    }
  }
}

Example: waiting

{
  "item": {
    "message": {
      "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "visitor",
      "text": "Is anyone there?",
      "createdAt": "2026-10-12T19:30:00.000Z",
      "author": null,
      "files": [],
      "citations": [],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    "reply": null,
    "chat": {
      "id": "4b13b730-69d4-441c-8aee-42de75fef073",
      "channelKey": "dep_example123",
      "userId": "shopper_123",
      "mode": "waiting",
      "teammate": null,
      "createdAt": "2026-10-12T09:00:00.000Z",
      "updatedAt": "2026-10-12T19:30:00.000Z",
      "resolvedAt": null,
      "historyComplete": true,
      "handoff": {
        "status": "waiting",
        "requestedAt": "2026-10-12T19:28:00.000Z",
        "requiresEmail": true,
        "nextAvailableAt": "2026-10-13T08:00:00.000Z",
        "timezone": "Europe/London"
      }
    }
  }
}

With Accept: text/event-stream, the reply streams as it is written. See Streaming.

Errors, besides those every operation can return

400: invalid_json, invalid_request, unsupported_resume
404: chat_not_found, file_not_found
406: unsupported_accept
409: idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, operation_interrupted, operation_superseded, file_not_ready
413: payload_too_large
415: unsupported_media_type
429: chat_limit_reached
503: service_unavailable

List messages

GET /v1/channels/{channelKey}/chats/{chatId}/messages

Lists a chat's messages, oldest first.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Query

Name	Description
`limit`	Optional. How many messages to return, 1–50. Defaults to 20.
`cursor`	Optional. nextCursor from the previous page.

Response 200

Field	Description
`items`	array of Message.
`nextCursor`	string or null. Null on the last page.

Example

{
  "items": [
    {
      "id": "29a1fb72-55e2-44c6-bf21-a21f8e25fbc1",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "visitor",
      "text": "When are you open?",
      "createdAt": "2026-10-12T09:00:01.000Z",
      "author": null,
      "files": [],
      "citations": [],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    {
      "id": "8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "agent",
      "text": "We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.",
      "createdAt": "2026-10-12T09:00:03.000Z",
      "author": null,
      "files": [],
      "citations": [
        {
          "title": "Opening times",
          "url": "https://shop.example/pages/opening-times",
          "updatedAt": "2026-10-01T08:00:00.000Z"
        }
      ],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    {
      "id": "c5d0a8e2-7f14-4b9a-a3e6-1d2c9b8f7e60",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "visitor",
      "text": "Have you got a helmet for a 4-year-old?",
      "createdAt": "2026-10-12T09:00:20.000Z",
      "author": null,
      "files": [],
      "citations": [],
      "products": [],
      "orders": [],
      "choices": [],
      "collection": null,
      "handoffOffer": null
    },
    {
      "id": "e1b7f3a9-2c6d-4e80-9f5a-6b3d1c0a8e24",
      "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
      "role": "agent",
      "text": "This one fits heads from 48 to 52 cm, which suits most 4-year-olds.",
      "createdAt": "2026-10-12T09:00:23.000Z",
      "author": null,
      "files": [],
      "citations": [],
      "products": [
        {
          "id": "kids-helmet-48-52",
          "title": "Kids' cycle helmet, 48–52 cm",
          "brand": "Trailcraft",
          "imageUrl": "https://shop.example/images/kids-helmet.jpg",
          "productUrl": "https://shop.example/products/kids-helmet",
          "inStock": true,
          "clickAndCollectOnly": false,
          "price": {
            "amount": 29.99,
            "currency": "GBP",
            "was": 34.99,
            "from": false
          }
        }
      ],
      "orders": [],
      "choices": ["Show me other sizes", "Talk to the team"],
      "collection": null,
      "handoffOffer": null
    }
  ],
  "nextCursor": null
}

Errors, besides those every operation can return

400: invalid_request, invalid_cursor
404: chat_not_found
410: cursor_expired

Upload a file

POST /v1/channels/{channelKey}/chats/{chatId}/files

Uploads a file to send with a message. Unsent files are deleted after a day.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Headers

Name	Description
`Idempotency-Key`	8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.

Body (multipart/form-data)

Field	Description
`file`	file. One JPEG, PNG, GIF, WebP, PDF or plain text file, up to 4 MiB.

Response 201, or 200 when the same Idempotency-Key is sent again

Field	Description
`item`	File. A file uploaded to a chat.

Example

{
  "item": {
    "id": "file_7Qx2mLr9Kd",
    "chatId": "4b13b730-69d4-441c-8aee-42de75fef073",
    "filename": "receipt.pdf",
    "mediaType": "application/pdf",
    "byteSize": 48213,
    "createdAt": "2026-10-12T09:02:00.000Z",
    "expiresAt": "2026-10-13T09:02:00.000Z"
  }
}

Errors, besides those every operation can return

400: invalid_request
404: chat_not_found
409: idempotency_conflict, chat_closed, file_not_ready, file_limit_reached, file_storage_limit
413: payload_too_large
415: unsupported_media_type, unsupported_file

Download a file

GET /v1/channels/{channelKey}/chats/{chatId}/files/{fileId}

Downloads a file sent in the chat.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.
`fileId`	The file's ID, from Upload a file or a message's files.

Response 200: the file's bytes, with its own Content-Type.

Errors, besides those every operation can return

404: chat_not_found, file_not_found
409: file_not_ready

Get the collection

GET /v1/channels/{channelKey}/chats/{chatId}/collection

Reads the details collected in the chat and any form the agent is asking for.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Response 200

Field	Description
`item`	Collection. The details collected in a chat.

Example

{
  "item": {
    "version": 3,
    "fields": [
      {
        "id": "field_name",
        "label": "Your name",
        "description": "",
        "type": "text",
        "choices": []
      },
      {
        "id": "field_email",
        "label": "Email",
        "description": "So the team can reply if you leave.",
        "type": "email",
        "choices": []
      }
    ],
    "values": [
      {
        "fieldId": "field_name",
        "value": "Sam Taylor",
        "status": "accepted",
        "actor": "visitor",
        "updatedAt": "2026-10-12T09:01:10.000Z"
      }
    ],
    "request": {
      "id": "form_example123",
      "collectionId": "collection_contact",
      "purpose": "So the team can get back to you.",
      "fields": [
        {
          "fieldId": "field_name",
          "required": true
        },
        {
          "fieldId": "field_email",
          "required": true
        }
      ],
      "complete": false,
      "canSkip": false,
      "canCancel": true
    },
    "missing": ["field_email"],
    "pendingAction": "handoff",
    "error": null
  }
}

Errors, besides those every operation can return

404: chat_not_found

Submit the collection

POST /v1/channels/{channelKey}/chats/{chatId}/collection

Saves, skips or cancels the form the agent is asking for.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Headers

Name	Description
`Idempotency-Key`	8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.

Body (application/json)

Field	Description
`collectionRequestId`	string or null. request.id from the collection you read, or null if it had no request.
`expectedVersion`	integer. The collection's version when you read it.
`action`	string. One of `save`, `skip`, `cancel`.
`values`	object. Optional. Answers by field ID.
`fieldIds`	array of string. Optional. Optional fields the customer skipped. At most 20.

{
  "collectionRequestId": "form_example123",
  "expectedVersion": 3,
  "action": "save",
  "values": {
    "field_email": "shopper@example.test"
  }
}

Response 200

Field	Description
`item`	Collection. The details collected in a chat.

Example

{
  "item": {
    "version": 4,
    "fields": [
      {
        "id": "field_name",
        "label": "Your name",
        "description": "",
        "type": "text",
        "choices": []
      },
      {
        "id": "field_email",
        "label": "Email",
        "description": "So the team can reply if you leave.",
        "type": "email",
        "choices": []
      }
    ],
    "values": [
      {
        "fieldId": "field_name",
        "value": "Sam Taylor",
        "status": "accepted",
        "actor": "visitor",
        "updatedAt": "2026-10-12T09:01:10.000Z"
      },
      {
        "fieldId": "field_email",
        "value": "sam@example.test",
        "status": "accepted",
        "actor": "visitor",
        "updatedAt": "2026-10-12T09:01:30.000Z"
      }
    ],
    "request": {
      "id": "form_example123",
      "collectionId": "collection_contact",
      "purpose": "So the team can get back to you.",
      "fields": [
        {
          "fieldId": "field_name",
          "required": true
        },
        {
          "fieldId": "field_email",
          "required": true
        }
      ],
      "complete": true,
      "canSkip": false,
      "canCancel": true
    },
    "missing": [],
    "pendingAction": "handoff",
    "error": null
  }
}

Errors, besides those every operation can return

400: invalid_json, invalid_request, invalid_submission
404: chat_not_found
409: idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, version_conflict
413: payload_too_large
415: unsupported_media_type
429: chat_limit_reached
503: service_unavailable

Pass the chat to your team

POST /v1/channels/{channelKey}/chats/{chatId}/handoff

Passes the chat to your team, accepting the agent's latest offer.

Path

Name	Description
`chatId`	The chat's ID, from Create a chat.

Headers

Name	Description
`Idempotency-Key`	8–128 letters, digits or . _ : -, a UUID recommended. Repeat it to retry the same request safely.

Body (application/json)

Field	Description
`confirmationId`	string. From the message's handoffOffer.
`email`	string. Optional. An email address.
`locale`	string. Optional. A BCP 47 language tag. Chats default to en.

{
  "confirmationId": "confirm_example123",
  "email": "shopper@example.test",
  "locale": "en-GB"
}

Response 201, or 200 when the same Idempotency-Key is sent again

Field	Description
`item`	Chat. A chat between a customer and the channel's agent.

Example

{
  "item": {
    "id": "4b13b730-69d4-441c-8aee-42de75fef073",
    "channelKey": "dep_example123",
    "userId": "shopper_123",
    "mode": "waiting",
    "teammate": null,
    "createdAt": "2026-10-12T09:00:00.000Z",
    "updatedAt": "2026-10-12T19:28:00.000Z",
    "resolvedAt": null,
    "historyComplete": true,
    "handoff": {
      "status": "waiting",
      "requestedAt": "2026-10-12T19:28:00.000Z",
      "requiresEmail": true,
      "nextAvailableAt": "2026-10-13T08:00:00.000Z",
      "timezone": "Europe/London"
    }
  }
}

Errors, besides those every operation can return

400: invalid_json, invalid_request
404: chat_not_found
409: idempotency_conflict, turn_in_progress, operation_capacity_reached, chat_closed, confirmation_required, collection_incomplete
413: payload_too_large
415: unsupported_media_type
429: chat_limit_reached
503: service_unavailable

Streaming

Send Accept: text/event-stream with Send a message to get the reply as it is written. The stream is a series of events:

Event	Data
`start`	`chatId`, `requestId`, `messageId` and `replyId` (null while the chat is with your team)
`delta`	`text`: the next part of the reply
`done`	The same JSON as a response without streaming. Ends the stream.
`error`	An error, as JSON. Ends the stream.

The deltas add up to the reply's text in done. When the agent ends by asking the customer a question, done has the question as the reply's text, in place of what was streamed.

A comment line is sent every 15 seconds to keep the connection open. Streams can't be resumed: a Last-Event-ID header is refused. If a stream ends without done or error, the result is unknown. Send the request again with the same Idempotency-Key, or list the messages.

event: start
data: {"chatId":"4b13b730-69d4-441c-8aee-42de75fef073","requestId":"rq_3f1c9a7e5b2d4c6a","messageId":"29a1fb72-55e2-44c6-bf21-a21f8e25fbc1","replyId":"8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d"}

event: delta
data: {"text":"We're open 9am to 5:30pm Monday to Saturday, "}

event: delta
data: {"text":"and 10am to 4pm on Sunday."}

event: done
data: {"item":{"message":{"id":"29a1fb72-55e2-44c6-bf21-a21f8e25fbc1","chatId":"4b13b730-69d4-441c-8aee-42de75fef073","role":"visitor","text":"When are you open?","createdAt":"2026-10-12T09:00:01.000Z","author":null,"files":[],"citations":[],"products":[],"orders":[],"choices":[],"collection":null,"handoffOffer":null},"reply":{"id":"8f0e2d6c-3b1a-4f5e-9c7d-2a6b4e8f1c3d","chatId":"4b13b730-69d4-441c-8aee-42de75fef073","role":"agent","text":"We're open 9am to 5:30pm Monday to Saturday, and 10am to 4pm on Sunday.","createdAt":"2026-10-12T09:00:03.000Z","author":null,"files":[],"citations":[{"title":"Opening times","url":"https://shop.example/pages/opening-times","updatedAt":"2026-10-01T08:00:00.000Z"}],"products":[],"orders":[],"choices":[],"collection":null,"handoffOffer":null},"chat":{"id":"4b13b730-69d4-441c-8aee-42de75fef073","channelKey":"dep_example123","userId":"shopper_123","mode":"agent","teammate":null,"createdAt":"2026-10-12T09:00:00.000Z","updatedAt":"2026-10-12T09:00:03.000Z","resolvedAt":null,"historyComplete":true,"handoff":null}}}

Objects

Chat

A chat between a customer and the channel's agent.

Field	Description
`id`	string. The chat's ID. Keep it to send messages to the chat.
`channelKey`	string. The channel's address. It's under Channel address on the agent's Chat key screen, and is the data-deployment value in the code you add to your website.
`userId`	string. The customer's ID in this channel: your userId, one your website signed for the widget, or a random one for a guest. 1–128 letters, digits or . _ : @ -. It is not a sign-in.
`mode`	string. agent: the agent answers. waiting: waiting for your team. teammate: a teammate is answering. resolved: closed.
`teammate`	object or null. The teammate answering, while one is.
`teammate.name`	string. The teammate's name.
`createdAt`	string (time). When the chat started.
`updatedAt`	string (time). When the chat last changed.
`resolvedAt`	string (time) or null. When the chat was resolved.
`historyComplete`	boolean. False when older messages are no longer kept.
`handoff`	object or null. The latest request to pass the chat to your team; null if there isn't one.
`handoff.status`	string. waiting: no teammate has it yet. claimed: a teammate has it. resolved: your team closed it. failed: it didn't reach your team.
`handoff.requestedAt`	string (time). When the customer asked for your team.
`handoff.requiresEmail`	boolean. True when your team will reply by email, so the customer's email is needed.
`handoff.nextAvailableAt`	string (time) or null. When your team is next available; null when they are available now.
`handoff.timezone`	string or null. Your team's support hours time zone.

Collection

The details collected in a chat.

Field	Description
`version`	integer. Send it back as expectedVersion when you submit.
`fields`	array of Field. Every field the chat's answers refer to.
`values`	array of object. The answers so far.
`values[].fieldId`	string. 1–128 letters, digits, underscores or hyphens, as your workspace set it.
`values[].value`	string or null.
`values[].status`	string. Only an accepted value is an answer. One of `accepted`, `declined`, `unknown`, `disputed`.
`values[].actor`	string. Who gave it: the customer (visitor) or a teammate. One of `visitor`, `teammate`.
`values[].updatedAt`	string (time). A UTC time with milliseconds.
`request`	object or null. The form the agent is asking the customer to fill in, if any.
`request.id`	string. Send it as collectionRequestId when you submit.
`request.collectionId`	string. 1–128 letters, digits, underscores or hyphens, as your workspace set it.
`request.purpose`	string. Why the agent is asking.
`request.fields`	array of object.
`request.fields[].fieldId`	string. 1–128 letters, digits, underscores or hyphens, as your workspace set it.
`request.fields[].required`	boolean.
`request.complete`	boolean. True once every required field is answered.
`request.canSkip`	boolean. Whether the customer may skip the form.
`request.canCancel`	boolean. Whether the customer may cancel the form.
`missing`	array of string. Required fields still unanswered.
`pendingAction`	string or null. handoff when the answers are for passing the chat to your team.
`error`	string or null. Why the last submission wasn't saved, if it wasn't.

Error

Why a request failed.

Field	Description
`error`	object.
`error.code`	string. What went wrong. Act on this.
`error.message`	string. What went wrong, in words. It may change.
`error.requestId`	string. Also sent as X-Request-Id. Quote it when you ask us about a request.
`error.field`	string. A JSON pointer to the request field at fault.
`error.retryAfterSeconds`	integer. Seconds to wait before trying again.

Field

A detail the agent can ask for.

Field	Description
`id`	string. 1–128 letters, digits, underscores or hyphens, as your workspace set it.
`label`	string. What the customer is asked.
`description`	string. More about what to enter, if anything.
`type`	string. One of `text`, `email`, `choice`.
`choices`	array of object. A choice field's options. Its answer is the chosen option's id.
`choices[].id`	string. 1–128 letters, digits, underscores or hyphens, as your workspace set it.
`choices[].label`	string.

File

A file uploaded to a chat.

Field	Description
`id`	string. The file's ID. Send it in a message's fileIds.
`chatId`	string. The chat's ID.
`filename`	string. The file's name when it was uploaded.
`mediaType`	string. The file's type.
`byteSize`	integer. The file's size in bytes.
`createdAt`	string (time). When the file was uploaded.
`expiresAt`	string (time) or null. When an unsent file is deleted; null once it is sent with a message.

HandoffOffer

An offer to pass the chat to your team. Accept it with Pass the chat to your team.

Field	Description
`confirmationId`	string. Send it to Pass the chat to your team to accept the offer.
`requiresEmail`	boolean. True when your team will reply by email, so the customer's email is needed.
`nextAvailableAt`	string (time) or null. When your team is next available; null when they are available now.
`timezone`	string or null. Your team's support hours time zone.

Message

One message in a chat.

Field	Description
`id`	string. The message's ID.
`chatId`	string. The chat's ID.
`role`	string. Who sent it: the customer (visitor), the agent, a teammate, or system for a notice. One of `visitor`, `agent`, `teammate`, `system`.
`text`	string. The message, as plain text.
`createdAt`	string (time) or null. Null for some older messages.
`author`	object or null. The teammate who sent it, for a teammate's message.
`author.name`	string. The teammate's name.
`files`	array of File. Files sent with the message.
`citations`	array of object. Where the agent's answer came from, such as pages of your website. At most 20.
`citations[].title`	string. The source's title.
`citations[].url`	string or null. The source's address, if it has one.
`citations[].updatedAt`	string (time) or null. When it last changed, if known.
`products`	array of Product. Products the agent showed. At most 3.
`orders`	array of Order. Orders the agent looked up. At most 10.
`choices`	array of string. Replies the customer can pick. Send one as the next message's text.
`collection`	Collection or null. The collection when the message asks the customer to fill in a form.
`handoffOffer`	HandoffOffer or null. The agent's offer to pass the chat to your team, if it made one.

MessageTurn

A message sent, its reply and the chat afterwards.

Field	Description
`message`	Message. One message in a chat.
`reply`	Message or null. The agent's reply, or null while the chat is with your team.
`chat`	Chat. A chat between a customer and the channel's agent.

Order

An order the agent looked up.

Field	Description
`reference`	string. How the customer knows it.
`kind`	string. online: a website order. workshop: a repair or service job. order: a customer order placed in a shop.
`status`	string. Your shop's own wording.
`complete`	boolean. Closed in your shop's system: finished and handed over.
`placedLabel`	string or null. When it was placed, as a label.
`dueLabel`	string or null. When it is due, as a label.
`servicedItem`	string or null. The item being repaired or serviced.
`items`	array of object.
`items[].description`	string. What the item is.
`items[].quantity`	number.
`items[].arrived`	boolean or null. Whether an item ordered in has arrived; null when unknown.
`store`	object or null. The shop that has it, if it's in one.
`store.name`	string.
`store.phone`	string or null.

Product

A product the agent showed.

Field	Description
`id`	string. The product's ID in your catalogue.
`title`	string.
`brand`	string or null.
`imageUrl`	string or null. A picture of the product.
`productUrl`	string or null. The product's page on your website.
`inStock`	boolean or null. Null when stock is unknown.
`clickAndCollectOnly`	boolean. True when it can only be collected from a shop, not delivered.
`price`	object or null. Null when the price is unknown.
`price.amount`	number. In the currency's main unit.
`price.currency`	string. An ISO 4217 code.
`price.was`	number or null. The price before a sale.
`price.from`	boolean. True when amount is the lowest of several prices.

Errors

Every error has a code to act on, a message, and the requestId also sent as X-Request-Id. Some add field, the request field at fault, or retryAfterSeconds. Every operation can return invalid_id, invalid_api_key, origin_not_allowed, channel_disabled, workspace_suspended, rate_limited and internal_error. Each operation lists the others it can return.

Code	What to do
`invalid_json` (400)	Send a JSON object with Content-Type: application/json.
`invalid_request` (400)	Fix the field named in error.field, then send it again.
`invalid_id` (400)	Use the ID exactly as the API returned it.
`invalid_cursor` (400)	Send nextCursor exactly as the last page returned it, or start without one.
`invalid_submission` (400)	Read the collection again, fix the answers and submit.
`unsupported_resume` (400)	Send the message again with the same Idempotency-Key, or list the messages.
`invalid_api_key` (401)	Send Authorization: Bearer and the agent's chat key, from Advanced in its settings.
`origin_not_allowed` (403)	Call the API from your server, which keeps the key secret.
`channel_disabled` (403)	Publish the agent again.
`workspace_suspended` (403)	Contact us to restore it.
`not_found` (404)	Check the method and path against the API reference.
`chat_not_found` (404)	Use a chat ID this channel created. Deleted chats are gone.
`file_not_found` (404)	Use a file ID uploaded to this chat.
`method_not_allowed` (405)	Use a method the Allow header lists.
`unsupported_accept` (406)	Accept application/json or, to stream a reply, text/event-stream.
`unsupported_media_type` (415)	Send application/json, or multipart/form-data to upload a file.
`unsupported_file` (415)	Upload a JPEG, PNG, GIF, WebP, PDF or plain text file.
`idempotency_conflict` (409)	Use a new key for a new request.
`idempotency_key_expired` (409)	Read the resource to see what happened, then use a new key.
`turn_in_progress` (409)	Wait for the reply, then send again.
`operation_interrupted` (409)	List the messages to see what happened before sending anything new.
`operation_superseded` (409)	Read the chat, then decide whether to send a new request.
`operation_capacity_reached` (409)	Start a new chat.
`chat_closed` (409)	Start a new chat.
`version_conflict` (409)	Read the collection again, keep the customer's answers and submit with its version.
`file_not_ready` (409)	Upload it again with the same Idempotency-Key.
`file_limit_reached` (409)	Start a new chat to send more.
`file_storage_limit` (409)	Send a smaller file or start a new chat.
`confirmation_required` (409)	List the messages for the latest handoffOffer and use its confirmationId.
`collection_incomplete` (409)	Fill in the fields listed in missing, then submit.
`cursor_expired` (410)	Start listing again without a cursor.
`idempotency_resource_gone` (410)	Use a new key to start a new chat.
`payload_too_large` (413)	Send at most 32 KiB of JSON, or a file up to 4 MiB.
`rate_limited` (429)	Wait for Retry-After seconds, then send the same request again.
`capacity_limited` (429)	Wait for Retry-After seconds, then try again.
`chat_limit_reached` (429)	Wait for Retry-After seconds or add chats to the plan.
`internal_error` (500)	Send the same request again with the same Idempotency-Key.
`service_unavailable` (503)	Wait for Retry-After seconds, then send the same request again.

Create a chatCopy Anchor Link

Get a chatCopy Anchor Link

Send a messageCopy Anchor Link

List messagesCopy Anchor Link

Upload a fileCopy Anchor Link

Download a fileCopy Anchor Link

Get the collectionCopy Anchor Link

Submit the collectionCopy Anchor Link

Pass the chat to your teamCopy Anchor Link

StreamingCopy Anchor Link

ObjectsCopy Anchor Link

ChatCopy Anchor Link

CollectionCopy Anchor Link

ErrorCopy Anchor Link

FieldCopy Anchor Link

FileCopy Anchor Link

HandoffOfferCopy Anchor Link

MessageCopy Anchor Link

MessageTurnCopy Anchor Link

OrderCopy Anchor Link

ProductCopy Anchor Link

ErrorsCopy Anchor Link

On this page

Create a chat

Get a chat

Send a message

List messages

Upload a file

Download a file

Get the collection

Submit the collection

Pass the chat to your team

Streaming

Objects

Chat

Collection

Error

Field

File

HandoffOffer

Message

MessageTurn

Order

Product

Errors