Connecting a chat channel
After you received the chat channel credentials, it’s time to connect your Kommo account to the new channel.
We will need:
- Kommo chat service ID for the account. ID acquision process is described below
- Channel ID and channel secret that you’ve received from the Kommo support team
To connect to the channel, we form a POST request using the chat service ID.
Request is then signed with the channel secret, and the signature is added to the X-Signature header
Request example
POST https://amojo.kommo.com/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41/connect
Date: Mon, 03 Oct 2020 15:11:21 +0000
Content-Type: application/json
Content-MD5: a5e8ae04332a6d0aac15f01ad05d40e3
X-Signature: 85d94e7f21bdd3971c2721ca22793e45a96d0c75
Response
{
"account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
"scope_id": "f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec",
"title": "ChatIntegration",
"hook_api_version": "v2"
}
Message sending
You can send messages of the following types: text, image, file, location, contact.
The request structure is explained in detail here: Message sending
To send a message we need:
- Scope id acquired upon connecting the account to the chat channel
- Channel secret to form an X-Signature
Let’s review some examples:
Request example
POST https://amojo.kommo.com/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec
Date: Mon, 03 Oct 2020 16:06:48 +0000
Content-Type: application/json
Content-MD5: 204dc99bcaa899db72954f16de987022
X-Signature: 6201ab8b5154bfa2af847920f1dfeab74b125489
{
"account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
"event_type": "new_message",
"payload": {
"timestamp": 1596470808,
"msgid": "5f283618af2c8",
"conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
"sender": {
"id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
"avatar": "https:/example.com/users/avatar.png",
"name": "Example Client",
"profile": {
"phone": "14157428548",
"email": "sam@example.com"
},
"profile_link": "https://example.com/profile/example.client"
},
"message": {
"type": "text",
"text": "Hey, how's it going?"
},
"silent": true
}
}
Response
{"new_message":{"msgid":"1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc"}}
In Kommo interface you immediately receive a new Incoming lead
Notification Centre
Leads Pipeline
Incoming Lead
Any user who has access to the Incoming Lead card can view the feed and respond to the client.
Responding to the client
Receiving a response to the callback URL
Once an Kommo user responds to the client, the POST request with the message data is sent to the callback URL.
Request example
Webhook in the JSON format
{
"account_id": "b15c014f-eb7b-4073-bcad-6b62370a40ef",
"time": 1607683516,
"message": {
"receiver": {
"id": "626c1420-40bd-4645-a4ff-2227e93d80f1",
"phone": "14157428548",
"email": "",
"client_id": "U5fd34c4adf644"
},
"sender": {
"id": "80c39c49-a278-4b9c-b556-8f88f389f30b"
},
"conversation": {
"id": "844ccfc9-90a1-4340-917f-71c7866e6966",
"client_id": "c5fd34c4adf643"
},
"timestamp": 1607683516,
"message": {
"id": "e058df65-36ca-444f-9e9b-66371053f0bf",
"type": "text",
"text": "Hey, doing great! What about you?",
"media": "",
"thumbnail": "",
"file_name": "",
"file_size": 0
}
}
}
Developing a widget
You can give other Kommo users an option to connect your chat channel to their account. To do that, you need to develop a widget that will allow a user to connect the account to the chat channel.
More details about the development of the widget can be found in the widgets documentation
Additional requirements for the widget
To make your widget appear in the lead sources section, the parameter “lead_sources” should be added to the manifest.json file, “locations” object.
- User activates the widget connection window
- Enters his credentials for the account on your service
- The credentials and account ID are sent to your server. Account ID can be acquired by the widget via the following JS script: APP.constant(‘account’).amojo_id
- Your server validates received credentials and initiates the request to connect the account to the chat channel.
Initiate the conversation
Kommo interface allows to initiate the conversation with the client from the lead card. All it takes is to create a lead card and add a contact with the phone number.
If the “initiate conversation” is enabled for your channel, it will appear in the Click-To-Call menu (Registering a new channel)
User selects your widget and sends a message.
The Webhook v2.0 will be sent to the callback URL (Webhook 2.0) containing chat, recipient, and message IDs from Kommo.
Your integration server should process the request and attempt to send the message to the recipient.
Based on the sending attempt success or in case of an error the integration should send a request to Kommo to change the message status. (Delivery status)
When the client replies, you need to pass the conversation_ref_id and sender.ref_id parameters acquired earlier from the Webhook v2.0 in addition to standard request parameters
so Kommo connects the reply to the card you sent an initial message from (Sending messages)