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 | WidgetChat | registers the module, gets the transport token and creates the channel by itself |
| 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. What works: text, files and images with one attachment per message, and edits and deletions of the visitor's message. Quoting and the delivered and read statuses are in the channel declaration, but the connector does not pass them to the CRM. 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: received and skipped, an edit of the reply in the CRM does not reach the visitor |
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 real RetailCRM, not only on a mock Message Gateway.