Assistant API
Send every request from your server with your API token. Every call takes the assistant's ref, shown in the dashboard and sent in every event as assistant.ref. Endpoints are under https://graph.usexara.ai/rest.
Reply to a customer
POST /ChatAssistant/reply
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | The assistant's ref. |
customer_id | number | Yes, unless group_id | customer.id from the event. |
group_id | number | No | group.id from an assistant.mention event, to answer in that group instead. |
text | string | Yes, for text | Up to 4,000 characters. With a photo or video, its caption. |
type | string | No | text (default), image, video, or audio. See Photos, videos and audio. |
reply_to | string | No | A message.id to quote. |
buttons | array | No | Up to 3 reply buttons. See Buttons and lists. |
list | object | No | A list menu. Send buttons or list, not both. |
curl --request POST \
--url 'https://graph.usexara.ai/rest/ChatAssistant/reply' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"ref":"bolt-orders-3f9a1c2e","customer_id":901,"text":"Yes, we deliver to Yaba.","reply_to":"48213"}'
Returns { "message_id": "48214" }.
Text can use WhatsApp formatting: *bold*, _italic_, ~strikethrough~, `code`, and lines starting with - as bullets. Links (https://…) and [label](https://…) open in the app's browser.
Photos, videos and audio
Set type and attach the file, either uploaded as file (multipart, or base64 in JSON) or as a public media_url that Xara downloads.
| Field | Type | Required | Description |
|---|---|---|---|
file | file | One of file or media_url | The photo, video, or audio file. |
media_url | string | One of file or media_url | A public https link to it. Redirects are followed. |
mime_type | string | With file | The file's type, such as image/jpeg. With media_url it is optional and overrides the link's Content-Type. |
text | string | No | A caption for a photo or video. Audio has no caption. |
duration_ms | number | No | The length of a video or audio file, shown on the message. Up to 10 minutes. |
cover, cover_mime_type | file, string | No | A still for a video, shown before it plays. |
type | Formats | Size |
|---|---|---|
image | JPEG, PNG, or WebP | Up to 5 MB |
video | MP4 or MOV | Up to 20 MB |
audio | M4A, AAC, or MP3 (OGG and Opus aren't supported) | Up to 5 MB |
curl --request POST \
--url 'https://graph.usexara.ai/rest/ChatAssistant/reply' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"ref":"bolt-orders-3f9a1c2e","customer_id":901,"type":"image","media_url":"https://example.com/menu.jpg","text":"Today'"'"'s menu"}'
Or upload the file:
curl --request POST \
--url 'https://graph.usexara.ai/rest/ChatAssistant/reply' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form ref=bolt-orders-3f9a1c2e \
--form customer_id=901 \
--form type=audio \
--form mime_type=audio/mpeg \
--form duration_ms=12000 \
--form file=@greeting.mp3
Photos, videos, and audio work in groups too. They can't carry buttons or a list; send those in a text message after.
A file must really be the format its mime_type says: a renamed file is refused. A media_url must be on the public internet, can't include a username or password, and must download within 20 seconds. Each assistant can send up to 30 photos, videos, and audio files a minute; past that the request fails with "You're sending media too quickly". Text replies aren't limited this way.
Buttons and lists
Let the customer answer by tapping, as on WhatsApp. The options show under your message until the customer replies; only your newest message can be answered this way.
Buttons show as chips under the message:
{
"ref": "bolt-orders-3f9a1c2e",
"customer_id": 901,
"text": "Do you want it delivered or will you pick it up?",
"buttons": [
{ "id": "delivery", "title": "Delivery" },
{ "id": "pickup", "title": "Pick up" }
]
}
| Field | Limit |
|---|---|
buttons | 1 to 3, with different ids and titles. |
buttons[].id | Up to 256 characters. |
buttons[].title | Up to 20 characters. |
A list shows a button that opens a menu of rows:
{
"ref": "bolt-orders-3f9a1c2e",
"customer_id": 901,
"text": "What size would you like?",
"list": {
"button": "Choose a size",
"sections": [
{
"title": "Sizes",
"rows": [
{ "id": "small", "title": "Small", "description": "Serves one" },
{ "id": "large", "title": "Large", "description": "Serves two" }
]
}
]
}
}
| Field | Limit |
|---|---|
list.button | The button's label, up to 20 characters. |
list.sections | 1 to 10. Each needs a title (up to 24 characters) when there's more than one. |
rows | Up to 10 across all sections, with different ids. |
rows[].id | Up to 200 characters. |
rows[].title | Up to 24 characters. |
rows[].description | Optional, up to 72 characters. |
The customer's pick arrives as an assistant.message whose text is the option's title, with message.reply holding its id. Buttons and lists only work in a chat with one customer, not in a group or on a payment request.
An answer in a group goes to every member. You can answer a group for 24 hours after it last mentioned the assistant; payment requests and typing only work in a chat with one customer.
Show typing
POST /ChatAssistant/typing with ref and customer_id. The customer sees the assistant typing. Call it again if a reply takes a while.
Request a payment
POST /ChatAssistant/requestPayment
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | The assistant's ref. |
customer_id | number | Yes | customer.id from the event. |
amount | number | Yes | Whole naira, at least 1. |
note | string | No | What it's for, up to 200 characters. |
reply_to | string | No | A message.id to quote. |
Returns message_id and request_id. The customer pays it in the chat with their transaction PIN, and you receive assistant.payment with the same request_id. A request expires after 7 days and can only be paid once.
Post an update
POST /ChatAssistant/postStatus shares an update with everyone who has messaged the assistant. It appears with their contacts' updates.
| Field | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | The assistant's ref. |
type | string | No | text (default), image, or video. |
text | string | For text | The update, or a caption for a photo or video. |
background | string | No | Background colour for a text update. |
file | file | For image, video | A JPEG, PNG, or WebP photo, or an MP4 or MOV video of up to 60 seconds. |
mime_type | string | With file | The file's type, such as image/jpeg. |
duration_ms | number | For video | The video's length. |
cover, cover_mime_type | file, string | No | A still for a video. |
Returns the update, including its id. POST /ChatAssistant/removeStatus with ref and status_id deletes it from customers' phones.
Set the logo and cover
POST /ChatAssistant/logo with ref, an image file, and its mime_type (JPEG, PNG, or WebP, under 2 MB). Send remove=true instead to clear it, so your business logo shows.
POST /ChatAssistant/cover takes the same fields for the wide cover image customers see behind your assistant in the Xara app (under 4 MB, about 1200 × 450). remove=true clears it.
Test the webhook
POST /ChatAssistant/test with ref sends a signed assistant.ping and succeeds if your webhook answers 2xx.
Manage the assistant
These do the same as the buttons in the dashboard.
| Endpoint | Fields | Does |
|---|---|---|
POST /ChatAssistant/update | ref, then any of name, description, branding, webhook_url, category, status | Changes the assistant. category is one of shopping, food, travel, finance, health, learning, entertainment, or services, and is how customers browse in the app. status is active or inactive. Renaming a live assistant sends it back for review. |
POST /ChatAssistant/rotateSecret | ref | Returns a new webhook_secret. The old one stops working at once. |
POST /ChatAssistant/remove | ref | Deletes the assistant. |
GET /ChatAssistant/mine | Lists your assistants with their refs, secrets, and review status. |
Errors
| Status | Meaning |
|---|---|
400 | The assistant is turned off, or a field is missing or too long. |
422 | A submission or change isn't valid, such as a webhook that isn't https or isn't on the public internet. |
403 | The token isn't the business owner's. |
404 | No assistant with that ref belongs to your business, or the customer hasn't messaged it. |