Skip to content
VocenyaDocs

Chats

Chats on your website widget (channel: web) and on WhatsApp (channel: whatsapp, with the customer's number in contact_address). Reading needs chats:read; replying and closing need chats:write.

WhatsApp only allows free-form replies within 24 hours of the customer's last message: after that a reply is refused with whatsapp_window_closed (reply_window_open tells you beforehand).

Replies you send show in the visitor's widget straight away, from "Team", exactly like a reply typed in the portal inbox. Replying to a chat the AI is answering takes it over (status with_owner), so the AI stops answering. To build a bot or route chats to your own help desk, subscribe a webhook endpoint to chat.message.created and answer with POST /chats/{chat}/messages; skip messages with via_api: true, which are your own.

Endpoints

List chats

GET/chats

Needs the chats:read scope

Your website chats, newest first.

Query parameters

  • statusstringOptional

    Who is answering a website chat right now.

    One ofaiwith_agentwith_ownerclosed
  • sincestring (date-time)Optional

    Chats started at or after this time (ISO 8601).

  • untilstring (date-time)Optional

    Chats started before this time (ISO 8601).

  • per_pageintegerOptional

    How many items per page, 1 to 100.

    Minimum 1 · Maximum 100

  • cursorstring | nullOptional

    The meta.next_cursor (or meta.prev_cursor) of the previous page.

    Up to 1024 characters

Returns

Paginated set of ChatResource

  • dataarray of objectsRequired
  • linksobjectRequired
  • metaobjectRequired

Responses

  • 200Paginated set of ChatResource
  • 401The API key is missing, invalid, expired or revoked.
  • 403The key does not have the chats:read scope.
  • 422Validation error
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl https://vocenya.com/api/public/v1/chats \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
Response 200
{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "channel": "web",
      "contact_address": "string",
      "reply_window_open": true,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handoff_summary": "string",
      "handed_off_at": "2026-10-02T14:03:11+00:00",
      "closed_at": "2026-10-02T14:03:11+00:00",
      "last_message_at": "2026-10-02T14:03:11+00:00",
      "lead_id": 1,
      "messages": [
        {
          "id": 1,
          "livemode": true,
          "sender": "string",
          "role": "visitor",
          "author": "string",
          "body": "string",
          "via_api": true,
          "created_at": "2026-10-02T14:03:11+00:00"
        }
      ],
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}

Get a chat

GET/chats/{chat}

Needs the chats:read scope

One chat with its messages. HIPAA-mode accounts get the chat without messages or handoff summary.

Path parameters

  • chatintegerRequired

    The chat id.

Returns

ChatResource

  • dataobjectRequired

Responses

  • 200ChatResource
  • 401The API key is missing, invalid, expired or revoked.
  • 403The key does not have the chats:read scope.
  • 404No record with that id belongs to your account.
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl https://vocenya.com/api/public/v1/chats/205 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
Response 200
{
  "data": {
    "id": 1,
    "livemode": true,
    "channel": "web",
    "contact_address": "string",
    "reply_window_open": true,
    "status": "ai",
    "page_url": "https://www.example.com/contact",
    "handoff_summary": "string",
    "handed_off_at": "2026-10-02T14:03:11+00:00",
    "closed_at": "2026-10-02T14:03:11+00:00",
    "last_message_at": "2026-10-02T14:03:11+00:00",
    "lead_id": 1,
    "messages": [
      {
        "id": 1,
        "livemode": true,
        "sender": "string",
        "role": "visitor",
        "author": "string",
        "body": "string",
        "via_api": true,
        "created_at": "2026-10-02T14:03:11+00:00"
      }
    ],
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}

Reply in a chat

POST/chats/{chat}/messages

Needs the chats:write scope

Reply in a live chat as your team. The visitor sees it at once, from "Team". A reply to a chat the AI is answering takes it over. Limited to 30 replies a minute per key, on top of the overall limit.

Shell
curl -X POST https://vocenya.com/api/public/v1/chats/205/messages \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Thanks for waiting! We have an opening on Thursday at 3pm."}'

Path parameters

  • chatintegerRequired

    The chat id.

Request body

  • bodystringRequired

    The reply, as plain text. The visitor sees it from "Team".

    Up to 2000 characters

Returns

The message that was sent.

  • dataobjectRequired

Responses

  • 201The message that was sent.
  • 401The API key is missing, invalid, expired or revoked.
  • 403Website live chat is not part of the plan (live_chat_unavailable).
  • 404No record with that id belongs to your account.
  • 409The chat has ended (chat_closed).
  • 422A WhatsApp chat whose 24-hour reply window has closed (whatsapp_window_closed): follow up with an approved template from the inbox.
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl -X POST https://vocenya.com/api/public/v1/chats/205/messages \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Thanks for waiting! We have an opening on Thursday at 3pm. Shall I hold it for you?"
}'
Response 201
{
  "data": {
    "id": 1,
    "livemode": true,
    "chat_id": 205,
    "sender": "string",
    "role": "team",
    "author": "Team",
    "body": "string",
    "via_api": true,
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}

Close a chat

POST/chats/{chat}/close

Needs the chats:write scope

End a chat. The visitor sees that it ended. Closing a chat that already ended changes nothing.

Shell
curl -X POST https://vocenya.com/api/public/v1/chats/205/close \
  -H "Authorization: Bearer $VOCENYA_API_KEY"

Path parameters

  • chatintegerRequired

    The chat id.

Returns

ChatResource

  • dataobjectRequired

Responses

  • 200ChatResource
  • 401The API key is missing, invalid, expired or revoked.
  • 403Website live chat is not part of the plan (live_chat_unavailable).
  • 404No record with that id belongs to your account.
  • 429Too many requests for this key. Wait for the Retry-After seconds.
curl -X POST https://vocenya.com/api/public/v1/chats/205/close \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
Response 200
{
  "data": {
    "id": 1,
    "livemode": true,
    "channel": "web",
    "contact_address": "string",
    "reply_window_open": true,
    "status": "ai",
    "page_url": "https://www.example.com/contact",
    "handoff_summary": "string",
    "handed_off_at": "2026-10-02T14:03:11+00:00",
    "closed_at": "2026-10-02T14:03:11+00:00",
    "last_message_at": "2026-10-02T14:03:11+00:00",
    "lead_id": 1,
    "messages": [
      {
        "id": 1,
        "livemode": true,
        "sender": "string",
        "role": "visitor",
        "author": "string",
        "body": "string",
        "via_api": true,
        "created_at": "2026-10-02T14:03:11+00:00"
      }
    ],
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}