How does the Binom Ai Public API work?
The Binom Ai public API is a way to connect a synthetic employee from BINOMAI.com to your website, app, CRM, or any other system: you send a customer's message through an API request and immediately get back a ready-made reply from the synthetic employee. Developer Documentation
Getting started: creating a chat and sending a message
How do I create a chat?
Send a request:
POST https://prod-api.binomai.com/api/public/chats
In the request body, pass your own chat ID (for example, an order ID or dialog ID from your system) in the chat_id field:
curl https://prod-api.binomai.com/api/public/chats \
-u YOUR_API_KEY: \
-d chat_id="order_12345"
The same value you passed will come back in the response as integration_chat_id – and that's the value you should use in all subsequent requests.
An important nuance about IDs: the response to chat creation includes three different IDs – don't mix them up:
| Field | What it is | Used in later requests? |
|---|---|---|
chat_id – what you passed in the request | Your own ID | – |
integration_chat_id – in the response | The exact same value you passed | Yes, this is the value that goes into the path of every subsequent request, as {chat_id} |
id – in the response | An internal UUID generated by BINOMAI.com | Not used in the public API |
Every chat also comes with two statuses:
state– the dialog's review status:unreviewed,reviewed,awaiting_operator.ai_state– whether the synthetic employee is active in this chat:ai_active(responding automatically) orai_blocked(a live operator has taken over the conversation – via the dashboard, widget, or a connected helpdesk; in this state the customer's messages are still saved, but there will be no automatic reply). This status cannot be switched via the public API.
A chat can come from different channels – reflected in the form field: website (public_chat, widget), Telegram, Instagram, calls (call), API integration (api), and a number of other industry-specific scenarios (lawyer, tutor, interview, etc.).
How do I send a message and get a reply from the synthetic employee?
POST https://prod-api.binomai.com/api/public/chats/{chat_id}/messages
where {chat_id} is the same ID you specified when creating the chat.
curl https://prod-api.binomai.com/api/public/chats/order_12345/messages \
-u YOUR_API_KEY: \
-d content="Hello, could you tell me the delivery price?"
The synthetic employee's reply arrives immediately, in the body of this same request – no need to wait or poll separately.
Besides the reply text (content), the response also includes: role (who the author is – user, assistant, system, or operator), chat_id, your integration_message_id (if you passed one), and message_feedback – if the message already has a rating (see the feedback section below). The contacts field (the interlocutor's contact details) is not returned in a message response – it only appears on the chat itself.
How do I get the entire conversation history?
GET https://prod-api.binomai.com/api/public/chats/{chat_id}/messages
This request returns the whole conversation at once – pagination (page/per) has no effect on message history, no matter how many messages there are.
Authentication
How do I authenticate with the API?
Via HTTP Basic Auth: your API key goes in as the username, the password field is left empty.
Where do I get an API key?
In the BINOMAI.com dashboard: the "Organization Integrations" section → type API.
- To revoke a key – delete the corresponding integration.
- To reissue a key – create a new integration of type API; the old key stops working once the old integration is deleted.
Voice messages and files
Can I send voice messages?
Yes. To do this, pass [AUDIO] as the value of the content field, and attach the audio file itself as a regular file.
How do I attach a file to a message?
There are two ways:
- By link (
file_urls) – you provide the file's URL, and the BINOMAI.com server downloads it itself. - By the ID of an already-uploaded file (
files) – if the file was uploaded beforehand.
You can use either option, or both at once.
Rating replies (feedback)
How can a customer rate the synthetic employee's reply?
POST /api/public/chats/{chat_id}/messages/{id}/feedback
With the parameters state (like, dislike, or remove – to clear a rating) and comment (comment text).
A comment is only required for like and dislike. To clear a previously given rating, no comment is needed – state="remove" is enough on its own.
Limits and errors
How many messages can I send?
- No more than 10 messages per chat within a minute – after that, the chat is temporarily blocked for 10 minutes.
- No more than 100 requests per minute to the public API as a whole (across all chats combined).
What do the error codes mean?
| Code | What happened |
|---|---|
| 401 | Invalid or missing API key |
| 402 | Ran out of available requests to the synthetic employee under your plan |
| 403 | Subscription is not active |
| 404 | Chat or message not found |
| 429 | Rate limit exceeded (see above) |
How do I tell what an error response means?
An authentication error (401 for an invalid key) comes in this format:
{ "status": "error", "message": "Authentication failed" }
All other errors come in this format:
{ "error": "error text" }
Chat lifecycle
What happens if the customer doesn't reply to a message?
If a chat never received a single message from the user, it is automatically deleted after 3 hours.
What if the conversation has already started, but the customer takes a long time to reply?
A chat that already has message history is never deleted automatically – it's kept indefinitely. For very old conversations, we recommend creating a new chat on your end (for example, if the customer returns after a month) – this isn't a strict requirement, just a recommendation for more accurate replies from the synthetic employee, so old context doesn't interfere with the new conversation.
Working with the knowledge base (cards)
What is a "card" in BINOMAI.com?
A card is a saved question-and-answer pair in the knowledge base, formed based on conversations with customers.
GET /api/public/cards
What statuses can a card have?
| Status | Meaning |
|---|---|
waiting | Created, no answer yet |
in_progress | Being processed |
answered | An answer has been given |
submitted | Accepted for processing |
consumed | Ready for use in the knowledge base |
failed | Processing failed |
Working with price lists
How do I get a price list and the items in it?
GET /api/public/price_lists
GET /api/public/price_lists/{id}
The list of items is returned directly inside the response, in the price_items field – there's no need to make a separate request for the items.
⚠️ Pagination (per/page) only works for the full price list index (GET /price_lists) – the request for a single price list by {id} has no navigation parameters.
How do I know if price lists are still being processed?
The response for the price list index includes a parse_in_progress field, which indicates whether price lists are currently being parsed. ⚠️ The exact logic of this field is being confirmed with the developers.
Where do price lists come from?
The source can be an uploaded CSV file, or an external feed (rss, horoshop, and similar) – in that case, the response's url field will contain the feed's address.
What data is stored for each item?
Each item in price_items contains: name (title), brand, category, description, price, a link to the item and its image, a QR code (qr_code_url/qr_link), and key_params – key parameters/keywords that the synthetic employee itself extracts from the item's description during processing, in order to answer questions about that item more precisely.
Do I need a webhook?
No. The public API doesn't require a separate webhook setup – the synthetic employee's reply arrives immediately when the message is sent, with no need to receive notifications through a separate channel.
Integrations with specific platforms
Separate guides for connecting BINOMAI.com to popular systems (Shopify, AmoCRM, Syrve, and others) describe how to map those platforms' entities (orders, deals, dialogs) to BINOMAI.com chats and messages. (Links to these guides will be added as they become available.)
Request paths, field names, error codes, and limits are given exactly as they appear in the API - do not change them when publishing this on the site. The wording of the answers themselves can be adapted to match the site's tone.
Contact
If you have any questions, please contact our support team – support@binomai.com.
