API reference
The endpoints available today, grouped by resource. Each one states the scope it needs.
Paths relative to https://api.xatcrm.com/public/v1
ping
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /ping | Liveness/auth check | Any valid key |
- GET
/pingLiveness/auth check
Scope: Any valid key
me
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /me | Identity of the API key | inboxes:read |
- GET
/meIdentity of the API key
Scope:
inboxes:read
inboxes
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /inboxes | List inboxes | inboxes:read |
| GET | /inboxes/{inboxId}/check-number | Is this phone on WhatsApp? | inboxes:read |
- GET
/inboxesList inboxes
Scope:
inboxes:read - GET
/inboxes/{inboxId}/check-numberIs this phone on WhatsApp?
Scope:
inboxes:read
contacts
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /contacts | List/search contacts | contacts:read |
| POST | /contacts | Create (or find existing) contact | contacts:write |
| GET | /contacts/{id} | Get contact | contacts:read |
| PATCH | /contacts/{id} | Update contact | contacts:write |
| POST | /contacts/{id}/labels | Attach label to contact | labels:write |
- GET
/contactsList/search contacts
Scope:
contacts:read - POST
/contactsCreate (or find existing) contact
Scope:
contacts:write - GET
/contacts/{id}Get contact
Scope:
contacts:read - PATCH
/contacts/{id}Update contact
Scope:
contacts:write - POST
/contacts/{id}/labelsAttach label to contact
Scope:
labels:write
conversations
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /conversations | List conversations | conversations:read |
| POST | /conversations | Create or reuse a conversation | conversations:write |
| GET | /conversations/{id} | Get conversation | conversations:read |
| PATCH | /conversations/{id} | Update status/priority/subject | conversations:write |
| POST | /conversations/{id}/snooze | Snooze/unsnooze | conversations:write |
| PATCH | /conversations/{id}/assignment | Assign agent/team | assignments:write |
| POST | /conversations/{id}/labels | Attach label | labels:write |
| POST | /conversations/{id}/mark-read | Mark conversation read for THIS integration (per API key; not the per-user unread) | conversations:write |
| POST | /conversations/{id}/mark-unread | Mark conversation unread for THIS integration (per API key) | conversations:write |
- GET
/conversationsList conversations
Scope:
conversations:read - POST
/conversationsCreate or reuse a conversation
Scope:
conversations:write - GET
/conversations/{id}Get conversation
Scope:
conversations:read - PATCH
/conversations/{id}Update status/priority/subject
Scope:
conversations:write - POST
/conversations/{id}/snoozeSnooze/unsnooze
Scope:
conversations:write - PATCH
/conversations/{id}/assignmentAssign agent/team
Scope:
assignments:write - POST
/conversations/{id}/labelsAttach label
Scope:
labels:write - POST
/conversations/{id}/mark-readMark conversation read for THIS integration (per API key; not the per-user unread)
Scope:
conversations:write - POST
/conversations/{id}/mark-unreadMark conversation unread for THIS integration (per API key)
Scope:
conversations:write
messages
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /conversations/{id}/messages | List messages | messages:read |
| POST | /conversations/{id}/messages | Send a text message | messages:write |
| POST | /conversations/{id}/messages/media | Send a media message (image/audio/video/document/sticker) | messages:write |
| GET | /messages/{id} | Get a message | messages:read |
- GET
/conversations/{id}/messagesList messages
Scope:
messages:read - POST
/conversations/{id}/messagesSend a text message
Scope:
messages:write - POST
/conversations/{id}/messages/mediaSend a media message (image/audio/video/document/sticker)
Scope:
messages:write - GET
/messages/{id}Get a message
Scope:
messages:read
notes
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /conversations/{id}/notes | List internal notes (read-only) | notes:read |
| POST | /conversations/{id}/notes | Create a PRIVATE internal note (never sent to WhatsApp) | notes:write |
- GET
/conversations/{id}/notesList internal notes (read-only)
Scope:
notes:read - POST
/conversations/{id}/notesCreate a PRIVATE internal note (never sent to WhatsApp)
Scope:
notes:write
attachments
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /attachments/{id}/download | Download an attachment (bytes) | attachments:read |
- GET
/attachments/{id}/downloadDownload an attachment (bytes)
Scope:
attachments:read
labels
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /labels | List labels | labels:read |
- GET
/labelsList labels
Scope:
labels:read
assignees
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /assignees | List assignable agents/teams | assignments:read |
- GET
/assigneesList assignable agents/teams
Scope:
assignments:read
search
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /search | Global search (contacts / conversations / messages with snippets) | Any valid key |
- GET
/searchGlobal search (contacts / conversations / messages with snippets)
Scope: Any valid key
quickreplies
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /quick-replies | List canned replies (read-only) | quickreplies:read |
- GET
/quick-repliesList canned replies (read-only)
Scope:
quickreplies:read
OpenAPI contract
The full specification is served by the API itself, so it always matches the version that is running. You can generate clients from it.