Chat assistants overview
A chat assistant is a contact customers find in the Xara app's assistant directory and chat with like a person. Every message they send goes to your webhook. Your server replies through the assistant API with the same API token you use for the rest of Xara. You write the bot; Xara carries the chat, the customer's identity, and payments.
How an assistant works
- A customer finds your assistant in the app's Assistants tab, adds it, and opens a chat with it.
- They send a message: text, a photo, or a voice note. Xara saves it and POSTs an
assistant.messageevent to your webhook, signed with the assistant's secret. See Webhook events. - Your server replies with
POST /ChatAssistant/reply, quoting the message if you like. You can show a typing indicator first withChatAssistant/typing. - To charge the customer, send a payment request with
ChatAssistant/requestPayment. They pay it from their wallet in the chat, and Xara sends youassistant.paymentwith the request'srequest_id. The money goes to your business.
You can only reply to customers who have messaged the assistant first. Customers can't send stickers, videos, or contact cards to an assistant.
Submit an assistant
- Host a webhook over https on the public internet that accepts JSON POSTs and answers with a
2xxstatus. Xara refuses webhooks onlocalhostor private addresses; to test locally, use a tunnel such as ngrok. - In the business dashboard, open Chat Assistants and select Submit an assistant. Only the business owner can.
- Enter a name, a short description customers see in the directory, and your webhook URL. Optionally add notes for your bot: Xara sends them with every event as
assistant.branding, and customers never see them. - Optionally upload a logo: a PNG, JPEG, or WebP under 2 MB. Without one, customers see your business logo.
Once saved, the card shows the assistant's ref (the id you pass to every API call) and its webhook secret. Select Test webhook to send a signed assistant.ping and check your server answers. A business can have up to 5 assistants.
Review
Our team reviews every assistant. We check that the name and logo don't impersonate another brand, the description says what it does, and the webhook answers. Once approved, the assistant appears in the directory and its status in the dashboard reads Live. If it is rejected, the dashboard shows why; fix it and save to send it for review again. We email your business address when an assistant is approved or rejected.
We can also take down a live assistant that breaks our policies. It stops appearing and customers can't message it until you fix it and it's approved again.
Turn an assistant off
Select Turn off on the assistant's card to stop it without losing its customers. While it's off, customers can't message it, Xara sends no events, and the API refuses replies. Select Turn on to bring it back; it doesn't need another review.
Delete an assistant
Select Delete on the assistant's card. Customers can no longer find or message it, its ref stops working in the API, and it no longer counts toward your 5 assistants. Chats customers already had stay on their phones. This can't be undone.
Keep the secret safe
The webhook secret proves events come from Xara. Keep it on your server, next to your API token. If it leaks, select Replace next to the secret: Xara signs every event after that with the new one, so update your server straight away.