REST API reference

Conversations

Inbox conversations from every channel, limited to what the token's user sees in the Inbox, and what an agent does there: reply or add an internal note, assign, resolve, reopen, mark as spam, mark read and show a live chat visitor they are typing. Changes behave exactly as in the Inbox: a promoted conversation is replied to, assigned, closed and reopened through its ticket.

Endpoints

GET/api/v1/conversationsList conversations
GET/api/v1/conversations/{conversation}Get a conversation
PATCH/api/v1/conversations/{conversation}Update a conversation
PATCH/api/v1/conversations/{conversation}/metadataSet a conversation's metadata
POST/api/v1/conversations/{conversation}/spamMark a conversation as spam
DELETE/api/v1/conversations/{conversation}/spamMove a conversation out of spam
GET/api/v1/conversations/{conversation}/messagesList a conversation's messages
POST/api/v1/conversations/{conversation}/messagesReply to a conversation
POST/api/v1/conversations/{conversation}/readMark a conversation read
POST/api/v1/conversations/{conversation}/typingShow the visitor you are typing

Every request needs a bearer token: an API key or an OAuth access token. See authentication and scopes.

List conversations

GET/api/v1/conversations

List conversations, newest first unless sorted. Each carries whether the token's user has unread messages on it and a preview of its latest public message.

Scope: conversations:read
Unscoped key: Read-only or read-write

Query parameters

statusstring: open, resolved or abandoned.
channelstring: email, livechat, slack, discord, whatsapp, instagram, telegram, messenger, line, tiktok or ai_agent.
customer_idstring: Customer id.
assigneestring: me (the conversation or its ticket is assigned to the token's user) or unassigned.
unreadboolean: 1 or true: only conversations with messages the token's user has not read.
sortstring: -created_at, -last_message_at (default -created_at). -last_message_at puts the latest activity first.
per_pageinteger: 1-100, default 25.
cursorstring: meta.next_cursor from the previous page.

Request

curl https://zono.support/api/v1/conversations?status=open&channel=livechat&assignee=me&sort=-last_message_at \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Response200 OK

{
    "data": [
        {
            "object": "conversation",
            "id": "01j9x4c5d6e7f8g9h0j1k2m3n4",
            "subject": "Cannot activate my license",
            "status": "open",
            "channel": {
                "id": "01j9x0c1h2a3n4n5e6l7a8b9c0",
                "type": "whatsapp",
                "name": "WhatsApp support"
            },
            "customer": {
                "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
                "name": "Ada Lovelace",
                "email": "[email protected]"
            },
            "assignee": null,
            "ticket": {
                "id": "01j9x2p3q4r5s6t7u8v9w0x1y2",
                "number": 1042
            },
            "spam": false,
            "triage": null,
            "last_message_at": "2026-01-15T09:58:12Z",
            "created_at": "2026-01-15T09:50:01Z",
            "updated_at": "2026-01-15T09:58:12Z",
            "unread": true,
            "handed_off_at": null,
            "last_message": {
                "id": "01j9x4m5s6g7h8j9k0m1n2p3q4",
                "author_type": "customer",
                "author_name": "Ada Lovelace",
                "preview": "My license key says it is already in use on another site.",
                "created_at": "2026-01-15T09:58:12Z"
            }
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://zono.support/api/v1/conversations?cursor=eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
    },
    "meta": {
        "path": "https://zono.support/api/v1/conversations",
        "per_page": 25,
        "next_cursor": "eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
        "prev_cursor": null
    }
}

Get a conversation

GET/api/v1/conversations/{conversation}

One conversation with its channel, customer and ticket.

Scope: conversations:read
Unscoped key: Read-only or read-write

Path parameters

conversationstringRequired: Conversation id.

Request

curl https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4 \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Response200 OK

{
    "object": "conversation",
    "id": "01j9x4c5d6e7f8g9h0j1k2m3n4",
    "subject": "Cannot activate my license",
    "status": "open",
    "channel": {
        "id": "01j9x0c1h2a3n4n5e6l7a8b9c0",
        "type": "whatsapp",
        "name": "WhatsApp support"
    },
    "customer": {
        "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
        "name": "Ada Lovelace",
        "email": "[email protected]"
    },
    "assignee": null,
    "ticket": {
        "id": "01j9x2p3q4r5s6t7u8v9w0x1y2",
        "number": 1042
    },
    "spam": false,
    "triage": null,
    "last_message_at": "2026-01-15T09:58:12Z",
    "created_at": "2026-01-15T09:50:01Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "unread": true,
    "handed_off_at": null,
    "last_message": {
        "id": "01j9x4m5s6g7h8j9k0m1n2p3q4",
        "author_type": "customer",
        "author_name": "Ada Lovelace",
        "preview": "My license key says it is already in use on another site.",
        "created_at": "2026-01-15T09:58:12Z"
    }
}

Update a conversation

PATCH/api/v1/conversations/{conversation}

Assign or unassign, resolve or reopen the conversation. Send at least one field. Resolving a live chat ends it in the visitor's widget (with the rating prompt when CSAT is on); outside live chat a promoted conversation's ticket is closed or reopened with it. Reopening answers 422 when the customer already has another open conversation on the channel.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Body parameters

statusstring: open or resolved.
assignee_idstring|null: A team member, or null to unassign. A promoted conversation is assigned through its ticket.
close_reasonstring|null: With status resolved: resolved, not_resolved or spam, kept on the ticket the conversation closes (as on Update a ticket). Ignored for a conversation that is not a ticket.
close_reason_detailstring|null: With close_reason not_resolved: duplicate, no_reply, out_of_scope.

Request

curl -X PATCH https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4 \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'

Response200 OK

{
    "object": "conversation",
    "id": "01j9x4c5d6e7f8g9h0j1k2m3n4",
    "subject": "Cannot activate my license",
    "status": "open",
    "channel": {
        "id": "01j9x0c1h2a3n4n5e6l7a8b9c0",
        "type": "whatsapp",
        "name": "WhatsApp support"
    },
    "customer": {
        "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
        "name": "Ada Lovelace",
        "email": "[email protected]"
    },
    "assignee": null,
    "ticket": {
        "id": "01j9x2p3q4r5s6t7u8v9w0x1y2",
        "number": 1042
    },
    "spam": false,
    "triage": null,
    "last_message_at": "2026-01-15T09:58:12Z",
    "created_at": "2026-01-15T09:50:01Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "unread": true,
    "handed_off_at": null,
    "last_message": {
        "id": "01j9x4m5s6g7h8j9k0m1n2p3q4",
        "author_type": "customer",
        "author_name": "Ada Lovelace",
        "preview": "My license key says it is already in use on another site.",
        "created_at": "2026-01-15T09:58:12Z"
    }
}

Set a conversation's metadata

PATCH/api/v1/conversations/{conversation}/metadata

Set metadata about the conversation, shown to your team under From your app, and on the ticket if it is promoted. Keys are 1 to 40 lowercase letters, digits and underscores (zono_ is reserved; keys naming passwords, secrets, tokens, cards, CVV, SSN or IBAN are refused). Values are strings of at most 255 characters (ISO dates as strings), numbers or booleans; null deletes the key. At most 30 keys are kept and 4 KB sent per request; the latest write of a key wins. Strings that look like a card number or an IBAN are stored as [removed]. Values written here are marked Signed in the inbox and are never sent to the AI agent.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Body parameters

metadataobjectRequired: Keys and values to set; null removes a key.

Request

curl -X PATCH https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/metadata \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"order_id":"A-1042","cart_total":59.9}}'

Response200 OK

{
    "object": "conversation",
    "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
    "metadata": {}
}

Mark a conversation as spam

POST/api/v1/conversations/{conversation}/spam

Mark the conversation as spam, as the Inbox does: a promoted conversation through its ticket (see Mark a ticket as spam); a chat that is not a ticket is resolved and needs block. The conversation's spam field turns true.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Body parameters

blockarray: Also block the sender by any of: email, domain (not free email providers), ip (live chat visitors), customer. Types the sender has no value for are skipped and listed in meta.skipped.
include_other_openboolean: Also mark the customer's other open tickets (those you can access) as spam.

Request

curl -X POST https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/spam \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"block":["email","ip"]}'

Response200 OK

{
    "object": "conversation",
    "id": "01j9x4c5d6e7f8g9h0j1k2m3n4",
    "subject": "Cannot activate my license",
    "status": "open",
    "channel": {
        "id": "01j9x0c1h2a3n4n5e6l7a8b9c0",
        "type": "whatsapp",
        "name": "WhatsApp support"
    },
    "customer": {
        "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
        "name": "Ada Lovelace",
        "email": "[email protected]"
    },
    "assignee": null,
    "ticket": {
        "id": "01j9x2p3q4r5s6t7u8v9w0x1y2",
        "number": 1042
    },
    "spam": false,
    "triage": null,
    "last_message_at": "2026-01-15T09:58:12Z",
    "created_at": "2026-01-15T09:50:01Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "unread": true,
    "handed_off_at": null,
    "last_message": {
        "id": "01j9x4m5s6g7h8j9k0m1n2p3q4",
        "author_type": "customer",
        "author_name": "Ada Lovelace",
        "preview": "My license key says it is already in use on another site.",
        "created_at": "2026-01-15T09:58:12Z"
    }
}

Move a conversation out of spam

DELETE/api/v1/conversations/{conversation}/spam

Move the conversation's ticket out of spam. Answers 409 when it is not marked as spam.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Body parameters

remove_blocksboolean: Also lift the blocks that match the sender. Owners and admins only (403 otherwise).

Request

curl -X DELETE https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/spam \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Response200 OK

{
    "object": "conversation",
    "id": "01j9x4c5d6e7f8g9h0j1k2m3n4",
    "subject": "Cannot activate my license",
    "status": "open",
    "channel": {
        "id": "01j9x0c1h2a3n4n5e6l7a8b9c0",
        "type": "whatsapp",
        "name": "WhatsApp support"
    },
    "customer": {
        "id": "01j9x1c2d3e4f5g6h7j8k9m0n1",
        "name": "Ada Lovelace",
        "email": "[email protected]"
    },
    "assignee": null,
    "ticket": {
        "id": "01j9x2p3q4r5s6t7u8v9w0x1y2",
        "number": 1042
    },
    "spam": false,
    "triage": null,
    "last_message_at": "2026-01-15T09:58:12Z",
    "created_at": "2026-01-15T09:50:01Z",
    "updated_at": "2026-01-15T09:58:12Z",
    "unread": true,
    "handed_off_at": null,
    "last_message": {
        "id": "01j9x4m5s6g7h8j9k0m1n2p3q4",
        "author_type": "customer",
        "author_name": "Ada Lovelace",
        "preview": "My license key says it is already in use on another site.",
        "created_at": "2026-01-15T09:58:12Z"
    }
}

List a conversation's messages

GET/api/v1/conversations/{conversation}/messages

The conversation's messages, oldest first unless sorted, internal notes included.

Scope: conversations:read
Unscoped key: Read-only or read-write

Path parameters

conversationstringRequired: Conversation id.

Query parameters

sortstring: created_at (oldest first, default) or -created_at (newest first).
per_pageinteger: 1-100, default 25.
cursorstring: meta.next_cursor from the previous page.

Request

curl https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/messages \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Response200 OK

{
    "data": [
        {
            "object": "message",
            "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
            "conversation_id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
            "body": "body",
            "is_internal": true,
            "source": "source",
            "author": {
                "type": "user",
                "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
                "name": "Billing"
            },
            "author_type": "customer",
            "attachments": [
                {
                    "name": "Billing",
                    "url": "https://zono.support/",
                    "mime_type": "mime_type",
                    "size": 1
                }
            ],
            "created_at": "2026-01-15T10:24:07Z"
        }
    ],
    "links": {
        "first": null,
        "last": null,
        "prev": null,
        "next": "https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/messages?cursor=eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
    },
    "meta": {
        "path": "https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/messages",
        "per_page": 25,
        "next_cursor": "eyJpZCI6IjAxajl4MnAzcTQiLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
        "prev_cursor": null
    }
}

Reply to a conversation

POST/api/v1/conversations/{conversation}/messages

Reply as the token's user, exactly as in the Inbox: the customer gets it on the conversation's channel (live chat: instantly in the widget). A promoted conversation's reply is written on its ticket. Marks the conversation read for the token's user.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Body parameters

bodystringRequired: The reply, up to 10,000 characters; HTML or plain text.
internalboolean: An internal note the customer never sees (default false).

Request

curl -X POST https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/messages \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"body":"Thanks Ada, I have reset your activation."}'

Response201 Created

{
    "object": "message",
    "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
    "conversation_id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
    "body": "body",
    "is_internal": true,
    "source": "source",
    "author": {
        "type": "user",
        "id": "01j9x0a1b2c3d4e5f6g7h8j9k0",
        "name": "Billing"
    },
    "author_type": "customer",
    "attachments": [
        {
            "name": "Billing",
            "url": "https://zono.support/",
            "mime_type": "mime_type",
            "size": 1
        }
    ],
    "created_at": "2026-01-15T10:24:07Z"
}

Mark a conversation read

POST/api/v1/conversations/{conversation}/read

Mark the conversation read for the token's user. Answers 204.

Scope: conversations:read
Unscoped key: Read-only or read-write

Path parameters

conversationstringRequired: Conversation id.

Request

curl -X POST https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/read \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Answers 204 No Content with an empty body.

Show the visitor you are typing

POST/api/v1/conversations/{conversation}/typing

Show the live chat visitor that the token's user is typing; send it every few seconds while they type. Other channels have no typing indicator: nothing happens. Answers 204.

Scope: conversations:write
Unscoped key: Read-write

Path parameters

conversationstringRequired: Conversation id.

Request

curl -X POST https://zono.support/api/v1/conversations/01j9x4c5d6e7f8g9h0j1k2m3n4/typing \
  -H "Authorization: Bearer $ZONO_TOKEN" \
  -H "Accept: application/json"

Answers 204 No Content with an empty body.