amoCRM
amoCRM chats (amojo): what support has to issue, how to connect an account, the exchange format and the signature.
Support issues the channel #
The service has one channel for every client, and amoCRM support issues it on request (usually 1–3 business days). In return you get the channel code, the channel_id and the signing secret. While there is no channel, the amoCRM section in the dashboard says so plainly and an account cannot be connected.
The channel secret signs the exchange of every connected account at once, so it lives only in the service environment and is never shown in the dashboard.
Connecting an account #
amojo_id is not the usual account id: the usual one is not accepted here, and the error looks like «account not found».
The connection is sent with hook_api_version: v2 and the time window switched off. Without the first there are no detailed events; without the second amoCRM closes the chat after a day of silence, and a manager's reply to an older message does not arrive.
| Step | What |
|---|---|
| 1 | In amoCRM: GET /api/v4/account?with=amojo_id — copy amojo_id |
| 2 | In the dashboard: paste amojo_id and save |
| 3 | We call POST /v2/origin/custom/{channel_id}/connect and store scope_id |
| 4 | Check that the WidgetChat channel appeared in the chat list |
The exchange #
Outbound we send event_type: new_message with msgid, conversation_id, sender and message. amoCRM deduplicates by msgid; we record the attempt before sending, so a retry after a failure does not create a second copy.
The manager's reply arrives as a webhook on /amocrm/hook/{scope_id}. We answer 200 immediately and move the work into a queue: the amoCRM webhook is sent once and is not repeated if receiving fails.
POST /v2/origin/custom/{scope_id}
Date: Fri, 22 Aug 2026 09:15:04 +0000
Content-MD5: 3f9a…
X-Signature: 6b2f…
{"event_type": "new_message",
"payload": {"msgid": "wc-…", "conversation_id": "…", "sender": {"id": "…", "name": "John"},
"message": {"type": "text", "text": "Hello"}}}The signature #
An outbound request is signed with HMAC-SHA1 over a string made of the method, the MD5 of the body, the content type, the date and the path. An inbound webhook is signed with HMAC-SHA1 over the whole body — checked before any work.
Tested against a mock channel: we do not have a live amoCRM channel yet.