Connecting a chat channel

After you received the chat channel credentials, it’s time to connect your amoCRM account to the new channel.

We will need:

  • amoCRM chat service ID for the account. ID acquision process is described below
  • Channel ID and channel secret that you’ve received from the amoCRM 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.amocrm.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.amocrm.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": "nikita.v@team.amocrm.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 amoCRM 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 amoCRM 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 amoCRM 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.

  1. User activates the widget connection window
  2. Enters his credentials for the account on your service
  3. The credentials and account ID are sent to your server. Account ID can be acquired by the widget via the following JS script: AMOCRM.constant(‘account’).amojo_id
  4. Your server validates received credentials and initiates the request to connect the account to the chat channel.

Initiate the conversation

amoCRM 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 amoCRM.

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 amoCRM 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 amoCRM connects the reply to the card you sent an initial message from (Sending messages)