RetailCRM
Message Gateway: registering the module, the transport token, channel features and events.
The setup order #
The client key is needed only to register the module: after that the whole exchange uses the transport token the CRM issues itself.
| Step | Where | What |
|---|---|---|
| 1 | CRM | enable the Message Gateway integration |
| 2 | CRM | create an API key allowed to manage integration modules |
| 3 | Dashboard | enter the CRM address and the key, save |
| 4 | — | we register the module, get the transport token and create the channel |
| 5 | CRM | check that the WidgetChat channel appeared in the Chats section |
Channel features #
The channel declares to the CRM what it can do, and the interface adapts. We declare text, files and images with one attachment each, quoting, deletion and the delivered and read statuses. Orders and products are not declared: we cannot do them, and a declared feature would show the operator a button that does nothing.
The exchange #
The event arrives on an address like /retailcrm/hook/{clientId}. Transport events carry no signature, so authenticity rests on the random connection id in the address; it is also matched against the ClientId header.
MG sends an event for our own message too — those are dropped by the originator field, otherwise the reply would reach the visitor twice.
| Direction | Method or event |
|---|---|
| outbound | POST /api/transport/v1/messages, originator: customer |
| outbound | PUT and DELETE /api/transport/v1/messages by our external_id |
| outbound | POST /api/transport/v1/files/upload_by_url for attachments |
| inbound | message_sent: the manager's reply |
| inbound | message_updated, message_deleted: edits |
Limits #
The transport limit is 30 requests per second per token, above which 429 arrives. Such tasks are postponed and retried; edits and deletions are retried freely: they go by our external_id and do not duplicate anything.
Tested on a live RetailCRM (upsoft.retailcrm.ru).