Connecting an API channel

How to send text, images, audio, and documents to ChatRex through an API channel and get asynchronous responses to a secure webhook.

The API channel allows you to transfer messages from your own service to ChatRex. ChatRex immediately confirms the receipt of the request, processes the message asynchronously and sends a ready response to the specified HTTPS webhook with an HMAC signature.

Before connecting n

Prepare:

the public HTTPS address of the callback processor without query parameters;
a secret to verify an HMAC signature at least 32 characters long
How to create a unique request_id for each message
stable client_id, whereby messages from one client are combined into a dialogue;
Server storage for access token and callback secret.

If you plan to transfer media files, your service should also be able to send multipart/form-data requests and save the received media_id before sending a message.

The API channel is designed for server integration. Do not call it directly from the browser or mobile application: the access token will become available to the user of the application.

Creation of a channel

In ChatRex, open Integrations.
Press Connect integration.
On the Channels tab, select API and click Connect.
Open the tab Connection installation.
Copy URL for incoming messages.
Copy Access Token and immediately save it in a secure storage of your service.

The token is displayed only before the window closes. If the token is lost, click Reissue token. The current token will stop working immediately, but the channel URL will not change.

After creation, the API channel receives the status Connected and is turned on automatically.

Designation of a botoo channel

Open My Bots and press Change opposite the desired bot.
Go to Channels and Launch.
In Conditions on channels click Add channel.
Select the created API channel.
Set the launch conditions and save the changes.

Without channel assignment, the bot will not handle incoming API requests.

Downloading a media file

Media files are transmitted in two stages: first upload the file to ChatRex, then specify the received media_id in the message.

The download URL is located next to the URL of incoming messages: replace the end /messages with /uploads. Use the same Bearer token API channel.

POST https://api.example.com/api/channel/{CHANNEL_ID}/uploads
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: multipart/form-data

Pass two form fields:

Field	Destination
`upload_id`	Unique external download identifier: up to 100 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:` and `-`.
`file`	Binary content of the file.

Example from curl:

curl --request POST \
  --url "https://api.example.com/api/channel/{CHANNEL_ID}/uploads" \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --form "upload_id=order-42-photo" \
  --form "file=@./photo.png"

A successful download returns HTTP 201:

{
  "status": "uploaded",
  "upload_id": "order-42-photo",
  "media_id": "11111111-1111-4111-8111-111111111111",
  "type": "image",
  "name": "photo.png",
  "mime_type": "image/png",
  "size": 184203,
  "expires_at": "2026-08-12T15:00:00+00:00"
}

Supported formats:

Type	Formats
Images	JPEG, PNG, WEBP, GIF
Audio	MP3, OGG, WAV, M4A, WEBM
Documents	PDF, DOC, DOCX, XLS, XLSX, TXT, CSV

The API channel does not accept video and archives. ChatRex defines the actual MIME file type and correlates it with the file extension. By default, the maximum size of one file is 25 MiB.

Unattached download is stored for 24 hours. Before the expiration date, reloading the same file with the same upload_id will return the previous media_id. If the content is different, ChatRex will return HTTP 409 with upload_id_conflict - use the new upload_id.

Sending a message

Send the POST request to the copied URL for incoming messages. Pass the token in the Authorization header using the Bearer and JSON scheme in the query body.

POST {CHANNEL_URL}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "request_id": "req-20260808-0001",
  "client_id": "customer-12345",
  "message": "What is the delivery price?",
  "attachments": [
    {
      "media_id": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "additional_info": "Order 00042, priority customer",
  "callback_url": "https://example.com/webhooks/chatrex",
  "callback_secret": "replace-with-a-random-secret-at-least-32-characters"
}

The attachments and additional_info fields are optional. The message field cannot be transmitted unless there is at least one attachment. The remaining fields are mandatory:

Field	Destination
`request_id`	Unique request identifier. Do not use the same value for different messages.
`client_id`	Customer ID in an external service. Transmit the same value to continue the dialogue with that client.
`message`	The text of the message is up to 10,000 characters long. It may be absent if `attachments` is filled.
`attachments`	An ordered array of objects with previously obtained `media_id`.
`additional_info`	Additional context for processing a current message: a string of up to 10,000 characters or `null`.
`callback_url`	A public HTTPS webhook without query parameters to which ChatRex will send the result.
`callback_secret`	A secret at least 32 characters long for checking HMAC callback signature.

A successful response to an incoming request confirms only the reception of the message. The bot will receive a separate request for callback_url.

Media file processing

In one message, you can transfer no more than three attachments: a maximum of one image, one audio and one document. The total size of investments should not exceed 80 MiB.

ChatRex uses attachments in the same processing as message text and additional_info:

the image is transmitted to the image recognition circuit;
audio is decrypted and transcription is taken into account when generating a response.
The document is transmitted to the model as file entry.

The message can only consist of an attachment. For example:

{
  "request_id": "req-20260808-0002",
  "client_id": "customer-12345",
  "attachments": [
    {
      "media_id": "11111111-1111-4111-8111-111111111111"
    }
  ],
  "callback_url": "https://example.com/webhooks/chatrex",
  "callback_secret": "replace-with-a-random-secret-at-least-32-characters"
}

Each media_id can be assigned to only one incoming request. Resending a completely identical request with the same request_id is safe and will return the existing receipt. For another message, download the file with the new upload_id and use the new media_id.

Investments are part of the idempotent request. If you change the composition or order of attachments and keep the previous request_id, ChatRex returns HTTP 409 with the code request_id_conflict.

Mistakes in working with media

If the error occurs, ChatRex returns the JSON code to the error.code field. Basic codes:

HTTP	Code	What to check
`422`	`media_upload_required`, `invalid_upload_request`	The correct `upload_id` and `file` are present in the download request.
`422`	`file_type_not_allowed`, `file_too_large`	The format is supported, the MIME type corresponds to the extension, the size does not exceed the limit.
`422`	`message_or_attachment_required`	The message contains a text or at least one attachment.
`422`	`too_many_files`, `duplicate_media_type`, `total_media_size_exceeded`	Restrictions on the number, types and total size of investments are met.
`404`	`media_not_found`	`media_id` received in the same API channel and the file still exists.
`409`	`upload_id_conflict`, `media_already_claimed`	New `upload_id` and `media_id` are used for other content or message.
`410`	`media_expired`	The file is not expired; download it again if necessary.
`500` or `503`	`media_storage_failed`, `media_claim_failed`	Repeat the operation later; if the error persists, contact technical support.

Additional context `additional_info`

Use additional_info if, along with the message, you need to transfer information from your system to the bot, such as order status, customer category or selected tariff.

ChatRex adds a non-empty value to the additional system context of ongoing processing marked Additional information. The meaning is:

not added to the text of the message of the client;
Does not return to callback;
is not used to select a bot and verify the launch conditions;
It is not automatically transferred to the next API request.

If context is needed when processing the next message, retransmit it. Do not place passwords, tokens, payment details and other secrets in additional_info: the content of the field is transmitted to the model when generating a response.

additional_info is part of the idempotent request. Repeating with the same request_id data does not create a new message. If you change additional_info or another field, saving the previous request_id, ChatRex will return HTTP 409 with the code request_id_conflict. For a modified request, create a new request_id.

Callback processing

The callback handler shall:

Receive HTTPS requests from ChatRex
Check the HMAC signature with callback_secret prior to data processing;
compare the result with the original query by request_id;
retain the response or transmit it to the client only after successful verification of the signature;
Return successful HTTP status after receiving the result.

Do not record the token, callback secret and the full content of requests to public logs. Limit access to logs and keep secrets separate from source code.

Verification

Assign an API channel to the test bot.
Send a request with a new request_id and a test client_id.
Make sure that ChatRex has accepted the request.
Check for callback at the specified HTTPS address.
Make sure that the HMAC signature is validated and the answer is request_id.
Check the dialog in Chats and HistoryChatRex.
Send a second message with the same client_id and a new request_id to check the dialogue continues.
To check the media, download the test file, transfer it media_id to attachments and make sure the answer takes into account the contents of the file.

If the request is not processed

Check it out.

Whether the current token and the Authorization: Bearer header are used;
Whether a request is sent to the URL of the desired API channel;
Whether all mandatory fields are filled;
Whether message or at least one object is transferred to attachments
Whether additional_info is a string not exceeding 10,000 characters in length or a value null
Whether each media_id is received via endpoint /uploads of that particular API channel
24 hours have elapsed since the unfixed file was downloaded;
Whether media_id was previously used in another request
Are the restrictions exceeded: one file of each type, up to three attachments, up to 25 MiB per file and up to 80 MiB in total;
Whether the file extension matches its actual MIME type and whether the format is supported
Is request_id unique?
Does callback_url start with https:// and does not contain query parameters?
Whether callback_secret contains at least 32 characters
whether a callback is available from the Internet and accepts incoming requests;
Is the channel assigned to the bot and is the launch conditions suitable?
Integration and subscription are active.

If the token may have landed in a log, repository, or client application, immediately re-release it and update the secret in your server storage.