Chat assistants

Assistant API

Reply, show typing, request payments, and post updates as a chat assistant.

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

FieldTypeRequiredDescription
refstringYesThe assistant's ref.
customer_idnumberYes, unless group_idcustomer.id from the event.
group_idnumberNogroup.id from an assistant.mention event, to answer in that group instead.
textstringYes, for textUp to 4,000 characters. With a photo or video, its caption.
typestringNotext (default), image, video, or audio. See Photos, videos and audio.
reply_tostringNoA message.id to quote.
buttonsarrayNoUp to 3 reply buttons. See Buttons and lists.
listobjectNoA 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.

FieldTypeRequiredDescription
filefileOne of file or media_urlThe photo, video, or audio file.
media_urlstringOne of file or media_urlA public https link to it. Redirects are followed.
mime_typestringWith fileThe file's type, such as image/jpeg. With media_url it is optional and overrides the link's Content-Type.
textstringNoA caption for a photo or video. Audio has no caption.
duration_msnumberNoThe length of a video or audio file, shown on the message. Up to 10 minutes.
cover, cover_mime_typefile, stringNoA still for a video, shown before it plays.
typeFormatsSize
imageJPEG, PNG, or WebPUp to 5 MB
videoMP4 or MOVUp to 20 MB
audioM4A, 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" }
  ]
}
FieldLimit
buttons1 to 3, with different ids and titles.
buttons[].idUp to 256 characters.
buttons[].titleUp 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" }
        ]
      }
    ]
  }
}
FieldLimit
list.buttonThe button's label, up to 20 characters.
list.sections1 to 10. Each needs a title (up to 24 characters) when there's more than one.
rowsUp to 10 across all sections, with different ids.
rows[].idUp to 200 characters.
rows[].titleUp to 24 characters.
rows[].descriptionOptional, 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

FieldTypeRequiredDescription
refstringYesThe assistant's ref.
customer_idnumberYescustomer.id from the event.
amountnumberYesWhole naira, at least 1.
notestringNoWhat it's for, up to 200 characters.
reply_tostringNoA 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.

FieldTypeRequiredDescription
refstringYesThe assistant's ref.
typestringNotext (default), image, or video.
textstringFor textThe update, or a caption for a photo or video.
backgroundstringNoBackground colour for a text update.
filefileFor image, videoA JPEG, PNG, or WebP photo, or an MP4 or MOV video of up to 60 seconds.
mime_typestringWith fileThe file's type, such as image/jpeg.
duration_msnumberFor videoThe video's length.
cover, cover_mime_typefile, stringNoA 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.

EndpointFieldsDoes
POST /ChatAssistant/updateref, then any of name, description, branding, webhook_url, category, statusChanges 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/rotateSecretrefReturns a new webhook_secret. The old one stops working at once.
POST /ChatAssistant/removerefDeletes the assistant.
GET /ChatAssistant/mineLists your assistants with their refs, secrets, and review status.

Errors

StatusMeaning
400The assistant is turned off, or a field is missing or too long.
422A submission or change isn't valid, such as a webhook that isn't https or isn't on the public internet.
403The token isn't the business owner's.
404No assistant with that ref belongs to your business, or the customer hasn't messaged it.
Copyright © 2026