Як налаштувати публічний API Binom Ai?

Публічний API Binom Ai дозволяє розробникам інтегрувати Binom у зовнішні застосунки та сервіси. За допомогою API можна створювати чати, надсилати текстові повідомлення та файли, отримувати відповіді Binom, надсилати зворотний зв'язок, а також працювати з додатковими даними, включаючи картки запитань і відповідей та прайс-листи. Нижче наведена технічна документація з вимогами до автентифікації, API-ендпоінтами, прикладами запитів і форматами відповідей.

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.