How does the Binom Ai Public API work?

Binom Ai Public API allows developers to integrate a Binom into external applications and services. Using the API, you can create chat sessions, send text messages and files, receive Binom responses, submit feedback, and work with additional data such as Q&A cards and price lists. Below is the technical documentation with authentication requirements, endpoints, request examples, and response formats.

Authentication

All requests use Basic Auth.

Use your API Key as the username. No password is required.

Example:

curl -u YOUR_API_KEY: https://prod-api.binomai.com/...

Step 1: Create a Chat

POST https://prod-api.binomai.com/api/public/chats

Creates a new chat session with the AI.

Request (ChatRequest)

{
  "integration_chat_id": "your_internal_id" // optional
}

Response (Chat)

{
  "id": "uuid",
  "form": "public_chat | widget | helpcrunch | api",
  "integration_chat_id": "your_internal_id",
  "created_at": "2024-12-31T23:59:59Z"
}

Note: Chats inactive for over 3 days will be deleted automatically.

Step 2: Send a Message

POST https://prod-api.binomai.com/api/public/chats/{chat_id}/messages

Sends a message to a chat. Supports both text and files.

Request (MessageRequest)

{
  "content": "Hello!",
  "integration_message_id": "your_msg_id",
  "file_urls": ["https://example.com/audio.mp3"]
}

Note: For audio files, use "[AUDIO]" in the content field.

Response (Message)

{
  "id": "uuid",
  "content": "Hello!",
  "role": "user | assistant | system | operator",
  "files": [ ... ],
  "message_feedback": { ... },
  "created_at": "..."
}

Step 3: Get Chat Messages

GET https://prod-api.binomai.com/api/public/chats/{chat_id}/messages

Returns a list of messages in the specified chat.

Response (MessageList)

{
  "data": [ ... ],
  "meta": {
    "total": 3,
    "run_in_progress": true
  }
}

Note: If run_in_progress is true, wait 5 seconds before polling again.

Step 4: Leave Feedback

POST https://prod-api.binomai.com/api/public/chats/{chat_id}/messages/{message_id}/feedback

Allows a user to submit feedback for a specific message.

Request (MessageFeedbackRequest)

{
  "state": "like | dislike | remove",
  "comment": "Great response!"
}

Response (MessageFeedback)

{
  "id": "uuid",
  "state": "like",
  "comment": "Great response!",
  "created_at": "..."
}

Step 5 (Optional): Webhook

You may set up a webhook to receive AI responses via POST requests.

Optional Endpoints

List Chats

GET https://prod-api.binomai.com/api/public/chats

Use per and page query parameters to paginate the list.

List Cards

GET https://prod-api.binomai.com/api/public/cards

Returns a list of Q&A cards.

List Price Lists

GET https://prod-api.binomai.com/api/public/price_lists

Returns a list of uploaded price lists.

Get a Specific Price List

GET https://prod-api.binomai.com/api/public/price_lists/{price_list_id}

Fetches a specific price list by its ID.

Message Object Schema (Simplified)

{
  "id": "uuid",
  "content": "string",
  "role": "user | assistant | system | operator",
  "files": [
    {
      "id": "string",
      "signed_id": "string",
      "content_type": "string",
      "url": "string",
      "thumb": "string",
      "transcription": "string"
    }
  ],
  "message_feedback": {
    "id": "string",
    "state": "like | dislike",
    "comment": "string",
    "created_at": "date-time"
  },
  "created_at": "date-time"
}

Contact

If you have any questions, please contact our support team – support@binomai.com.