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.
Updated on 19.10.26
The Binom AI public API lets you connect the synthetic employee from BINOMAI.com to your website, app, CRM, or other system: you send a customer message through an API request and immediately get a ready-made reply from the synthetic employee. More details for developers
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 a conversation 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"
This same value you passed will be returned in the response as integration_chat_id, and this is the value you must use in all subsequent requests.
Important note about IDs: the response to chat creation returns three different IDs. Do not mix them up:
| Field | What it is | Used in subsequent requests |
|---|---|---|
chat_id: what you passed in the request |
Your own ID | – |
integration_chat_id: in the response |
Exactly the same value you passed | Yes, this exact value is substituted as {chat_id} in the path of all following requests |
id: in the response |
Internal UUID generated by BINOMAI.com | Not used in the public API |
Each chat also comes with two statuses:
state: the review status of the conversation:unreviewed(not reviewed),reviewed(reviewed),awaiting_operator(waiting for an operator).ai_state: whether the synthetic employee is active in this chat:ai_active(replies automatically) orai_blocked(a live operator has taken over the conversation through the dashboard, the widget, or a connected helpdesk; in this state customer messages are still saved, but there will be no automatic reply). This status cannot be switched through the public API.
A chat can come from different channels, which is reflected in the form field: the website (public_chat, widget), Telegram, Instagram, calls (call), API integration (api), and a number of other industry scenarios (tutor, interview, etc.).
How do I send a message and get the synthetic employee's reply?
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. There is no need to wait or poll the API.
In addition to the reply text (content), the response includes: role (the author: user, assistant, system, or operator), chat_id, your integration_message_id (if you passed one), and message_feedback if a rating has already been left for the message (see the feedback section below). The contacts field (the interlocutor's contact details) is not returned in the message response; it is only available on the chat itself.
How do I get the full conversation history?
GET https://prod-api.binomai.com/api/public/chats/{chat_id}/messages
This request returns the entire conversation in full. Pagination (page/per) does not apply to the message history, no matter how many messages there are.
Authorization
How do I authorize in the API?
Via HTTP Basic Auth: your API key is passed as username, and the password field is left empty.
Where do I get an API key?
In your BINOMAI.com personal account: section "Organization integrations" → type API.
- To revoke a key, delete the corresponding integration.
- To reissue a key, create a new integration of type API; the old key will stop working once the old integration is deleted.
Voice messages and files
Can I send voice messages?
Yes. To do so, pass the value [AUDIO] in the content field, and attach the audio file as a regular file.
How do I attach a file to a message?
There are two ways:
- By link (
file_urls): you specify the file URL, and the BINOMAI.com server downloads it itself. - By the ID of an already uploaded file (
files): if the file was uploaded in advance.
You can use either option or both at once.
Rating responses (feedback)
How can a client rate a response from the AI employee?
POST /api/public/chats/{chat_id}/messages/{id}/feedback
With the parameters state (like, dislike, or remove to clear the rating) and comment (comment text).
A comment is required only for like and dislike. To remove a previously given rating, no comment is needed: simply use state="remove".
Limits and errors
How many messages can I send?
- No more than 10 messages per chat per 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 | You have run out of requests to the AI employee available on your plan |
| 403 | Subscription is not active |
| 404 | Chat or message not found |
| 429 | Request limit exceeded (see above) |
How do I know what an error in the response means?
An authentication error (401 with an invalid key) is returned in this format:
{ "status": "error", "message": "Authentication failed" }
All other errors are returned in this format:
{ "error": "error text" }
Chat lifecycle
What happens if the client does not reply to a message?
If not a single message from the user has arrived in the chat, it is automatically deleted after 3 hours.
What if the conversation has already started, but the client does not reply for a long time?
A chat that has had at least one exchange of messages is not deleted automatically: it is stored indefinitely. For very old conversations, we recommend creating a new chat on your side (for example, if the client returns after a month). This is not a mandatory requirement, but a recommendation for more accurate responses from the AI employee, so that old context does not 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 dialogues with clients.
GET /api/public/cards
What statuses can a card have?
| Status | Meaning |
|---|---|
waiting |
Created, no answer yet |
in_progress |
Being processed |
answered |
Answer provided |
submitted |
Accepted for processing |
consumed |
Ready to 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 in the response, in the price_items field. You don't need to make a separate request to get the items.
⚠️ Pagination (per/page) works only for the list of all price lists (GET /price_lists). The request for a single price list by {id} has no pagination parameters.
How do I tell whether price lists are still being processed?
The response to the price list request includes the parse_in_progress field, which shows whether price lists are currently being parsed. ⚠️ The exact logic of this field is being clarified 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 the latter case, the url field in the response is filled with the feed address.
What data is stored for each item?
Each item in price_items contains: name (title), brand, category, description, price, link to the product and to the image, QR code (qr_code_url/qr_link), and key_params: key parameters or keywords that the AI employee extracts from the product description during processing so it can answer questions about that product more accurately.
Do I need a webhook?
No. The public API does not require a separate webhook setup. The AI employee's reply arrives immediately when the message is sent, with no need to receive notifications in a separate way.
Integrations with Specific Platforms
Separate guides on connecting BINOMAI.com to popular systems (Shopify, AmoCRM, Syrve, and others) describe how to link the entities of these platforms (orders, deals, conversations) with chats and messages in BINOMAI.com. (Links to such guides are added as they become ready.)
Request paths, field names, error codes, and limits are given exactly as in the API. They must not be changed when moved to the website. The wording of the responses themselves can be adapted to the website's tone.
Contact
If you have any questions, please contact our support team: support@binomai.com.
How to Connect the API in Your Account
- Open Integrations → the API tab ("API Integration").
- Click "Connect" and confirm.
- "API connected!" and a block "How to use the API:" with the key will appear. "Access to the API applies only to this Binom. Keep the API key secure."
- To disconnect, click "Disconnect API integration".
If the tab shows "Plan restrictions" with "API integration is available on higher-tier plans", see the list of plans on the plans and pricing page.
Other Common Questions
Does the chatbot have an API?
Yes, the public API is connected in Integrations → API.
How do I pass orders and contacts to a CRM?
Ways to connect a CRM: via the API, Horoshop, or the "More integrations" catalog.
