Xe Chat API

Base URL: https://api.xeboki.com/v1/chat

The Xe Chat API gives you programmatic access to customer conversations, messaging, contact management, and agent assignment. Build support automations, sync contact data, trigger outbound messages, and query conversation history — all via REST.

Support automations

Create conversations and send messages programmatically when events happen in your system.

CRM sync

Push customer data into Xe Chat contacts from your own CRM so agents always have full context.

Conversation routing

Assign conversations to agents or teams based on your own routing logic via the update endpoint.

Reporting & exports

Pull conversation history and message logs for compliance, auditing, or analytics.

Inboxes: All conversations belong to an inbox. An inbox represents a channel (email, live chat, WhatsApp, etc.). Retrieve your inbox IDs via GET /v1/chat/inboxes before creating conversations.

Authentication

All requests require a valid API key in the Authorization header. Create and manage keys at account.xeboki.com .

Authorization: Bearer xbk_live_your_key_here

Required scopes

`chat:conversations:read`	List and retrieve conversations
`chat:conversations:write`	Create and update conversations
`chat:messages:read`	Read messages within conversations
`chat:messages:write`	Send messages
`chat:contacts:read`	List and retrieve contacts
`chat:contacts:write`	Create and update contacts
`chat:agents:read`	List agents
`chat:agents:write`	Create and manage agents
`chat:inboxes:read`	List inboxes and channel IDs

Conversations

A conversation is a thread of messages between a contact and one or more agents, in a specific inbox.

GET/v1/chat/conversations

List conversations

Returns conversations for your account. Filter by status, inbox, or assigned agent.

Query parameters

Parameter	Type	Description
`status`	`string`	"open" \| "resolved" \| "pending" \| "snoozed" (default: all).
`inbox_id`	`integer`	Filter by inbox.
`agent_id`	`integer`	Filter by assigned agent.
`page`	`integer`	Page number (default: 1).
`limit`	`integer`	Results per page, max 50 (default: 25).

curl "https://api.xeboki.com/v1/chat/conversations?status=open&page=1" \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "data": [
    {
      "id": 1024,
      "status": "open",
      "inbox_id": 3,
      "contact": { "id": 55, "name": "Alice Smith", "email": "alice@example.com" },
      "assigned_agent": { "id": 7, "name": "Bob Jones" },
      "unread_count": 2,
      "last_activity_at": "2026-03-31T11:45:00Z",
      "created_at": "2026-03-31T10:00:00Z"
    }
  ],
  "total": 84,
  "page": 1,
  "limit": 25
}

POST/v1/chat/conversations

Create a conversation

Create a new conversation on behalf of a contact. Useful for proactive outreach or importing threads from another system.

Request body

Parameter	Type	Description
`inbox_id`required	`integer`	The inbox to create the conversation in.
`contact_id`required	`integer`	The contact this conversation belongs to.
`agent_id`	`integer`	Assign to a specific agent immediately.
`status`	`string`	"open" \| "pending" (default: "open").
`message`	`object`	Optional opening message to send.
`message.content`	`string`	Text content of the opening message.

curl -X POST https://api.xeboki.com/v1/chat/conversations \
  -H "Authorization: Bearer xbk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 3,
    "contact_id": 55,
    "message": {
      "content": "Hi Alice, following up on your recent order."
    }
  }'

Response 201

{
  "id": 1025,
  "status": "open",
  "inbox_id": 3,
  "contact": { "id": 55, "name": "Alice Smith", "email": "alice@example.com" },
  "assigned_agent": null,
  "unread_count": 0,
  "created_at": "2026-03-31T12:00:00Z"
}

GET/v1/chat/conversations/{id}

Get a conversation

Retrieve a single conversation by its ID.

curl https://api.xeboki.com/v1/chat/conversations/1024 \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "id": 1024,
  "status": "open",
  "inbox_id": 3,
  "contact": { "id": 55, "name": "Alice Smith", "email": "alice@example.com" },
  "assigned_agent": { "id": 7, "name": "Bob Jones" },
  "unread_count": 2,
  "last_activity_at": "2026-03-31T11:45:00Z",
  "created_at": "2026-03-31T10:00:00Z"
}

PATCH/v1/chat/conversations/{id}

Update a conversation

Change the status or reassign to a different agent. Only provided fields are changed.

Request body

Parameter	Type	Description
`status`	`string`	"open" \| "resolved" \| "pending" \| "snoozed".
`agent_id`	`integer`	Reassign to a different agent. Pass null to unassign.

curl -X PATCH https://api.xeboki.com/v1/chat/conversations/1024 \
  -H "Authorization: Bearer xbk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

Response 200

{
  "id": 1024,
  "status": "resolved",
  "inbox_id": 3,
  "assigned_agent": { "id": 7, "name": "Bob Jones" },
  "updated_at": "2026-03-31T12:30:00Z"
}

Messages

Messages are the individual exchanges within a conversation.

GET/v1/chat/conversations/{id}/messages

List messages

Returns all messages in a conversation, oldest first.

Query parameters

Parameter	Type	Description
`page`	`integer`	Page number (default: 1).
`limit`	`integer`	Results per page, max 100 (default: 50).

curl "https://api.xeboki.com/v1/chat/conversations/1024/messages" \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "data": [
    {
      "id": 2001,
      "conversation_id": 1024,
      "type": "incoming",
      "content": "Hi, I have a question about my order.",
      "sender": { "type": "contact", "id": 55, "name": "Alice Smith" },
      "created_at": "2026-03-31T10:05:00Z"
    },
    {
      "id": 2002,
      "conversation_id": 1024,
      "type": "outgoing",
      "content": "Hi Alice! I'd be happy to help. What is your order number?",
      "sender": { "type": "agent", "id": 7, "name": "Bob Jones" },
      "created_at": "2026-03-31T10:08:00Z"
    }
  ],
  "total": 2
}

POST/v1/chat/conversations/{id}/messages

Send a message

Send an outgoing message in a conversation. Delivered to the contact via the inbox channel.

Request body

Parameter	Type	Description
`content`required	`string`	Text content of the message.
`private`	`boolean`	Set true to send a private note (visible to agents only, not the contact).
`agent_id`	`integer`	Send as a specific agent. Defaults to the key owner.

curl -X POST https://api.xeboki.com/v1/chat/conversations/1024/messages \
  -H "Authorization: Bearer xbk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Your order #1234 has shipped! Tracking: XY9876543." }'

Response 201

{
  "id": 2003,
  "conversation_id": 1024,
  "type": "outgoing",
  "content": "Your order #1234 has shipped! Tracking: XY9876543.",
  "private": false,
  "sender": { "type": "agent", "id": 7, "name": "Bob Jones" },
  "created_at": "2026-03-31T12:10:00Z"
}

Contacts

Contacts represent the customers or end-users who initiate or participate in conversations.

GET/v1/chat/contacts

List contacts

Query parameters

Parameter	Type	Description
`q`	`string`	Search by name, email, or phone.
`page`	`integer`	Page number (default: 1).
`limit`	`integer`	Results per page, max 100 (default: 25).

curl "https://api.xeboki.com/v1/chat/contacts?q=alice" \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "data": [
    {
      "id": 55,
      "name": "Alice Smith",
      "email": "alice@example.com",
      "phone": "+1 555 000 1234",
      "conversation_count": 3,
      "created_at": "2026-01-15T09:00:00Z"
    }
  ],
  "total": 1
}

POST/v1/chat/contacts

Create a contact

Request body

Parameter	Type	Description
`name`required	`string`	Full name of the contact.
`email`	`string`	Email address. Must be unique.
`phone`	`string`	Phone number in E.164 format.

curl -X POST https://api.xeboki.com/v1/chat/contacts \
  -H "Authorization: Bearer xbk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alice Smith", "email": "alice@example.com" }'

Response 201

{
  "id": 56,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "phone": null,
  "conversation_count": 0,
  "created_at": "2026-03-31T12:00:00Z"
}

GET/v1/chat/contacts/{id}

Get a contact

curl https://api.xeboki.com/v1/chat/contacts/55 \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "id": 55,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "phone": "+1 555 000 1234",
  "conversation_count": 3,
  "created_at": "2026-01-15T09:00:00Z"
}

Agents

Agents are the support team members who handle conversations.

GET/v1/chat/agents

List agents

curl https://api.xeboki.com/v1/chat/agents \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "data": [
    {
      "id": 7,
      "name": "Bob Jones",
      "email": "bob@yourcompany.com",
      "role": "agent",
      "availability": "online"
    }
  ],
  "total": 5
}

POST/v1/chat/agents

Create an agent

Request body

Parameter	Type	Description
`name`required	`string`	Full name of the agent.
`email`required	`string`	Email address. Used to sign in to the Xe Chat console.
`role`	`string`	"agent" \| "administrator" (default: "agent").

curl -X POST https://api.xeboki.com/v1/chat/agents \
  -H "Authorization: Bearer xbk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Carol White", "email": "carol@yourcompany.com", "role": "agent" }'

Response 201

{
  "id": 8,
  "name": "Carol White",
  "email": "carol@yourcompany.com",
  "role": "agent",
  "availability": "offline"
}

Inboxes

Inboxes represent the channels your team uses to communicate (live chat widget, email, WhatsApp, etc.). Inboxes are created in the Xe Chat console — use this endpoint to list them and retrieve their IDs for use in conversation creation.

GET/v1/chat/inboxes

List inboxes

curl https://api.xeboki.com/v1/chat/inboxes \
  -H "Authorization: Bearer xbk_live_your_key_here"

Response 200

{
  "data": [
    {
      "id": 3,
      "name": "Website Live Chat",
      "channel_type": "live_chat",
      "is_enabled": true
    },
    {
      "id": 4,
      "name": "Support Email",
      "channel_type": "email",
      "is_enabled": true
    }
  ]
}

Error codes

Code	Error	Cause
400	Bad Request	Missing required field or invalid value.
401	Unauthorized	Missing or expired API key.
403	Forbidden	API key lacks the required scope.
404	Not Found	Conversation, contact, or agent ID not found.
409	Conflict	Contact with this email already exists.
422	Validation Error	inbox_id or contact_id does not exist in your account.
429	Too Many Requests	Rate limit exceeded. Check your plan limits.
500	Internal Server Error	Contact support with your request ID.