ONLINE CHATS

The functionality of online chat allows amoCRM users to exchange instant messages with their customers. At the same time, clients use the messenger for their communication.

As a rule, only the client can initiate correspondence.

The amoCRM API allows developers to integrate various instant messaging channels. For the end user, the work in the amo interface with such channels will not be different from the already built-in CRM (vk, facebook, telegram and so on).

The developer can make the integration only for his account, or replicate the solution to all amoCRM users via a widget.

To get started, you will need:

• Active account amoCRM. You can register a trial at https://www.amocrm.com

• Open a public endpoint on your server, where notifications of new messages from the amoCRM interface will arrive

• Access to the API of online chats. It must be requested through the technical support of amoCRM. This process is described in more detail here

Message exchange

The diagram below shows the process of sending and receiving messages through the amoCRM account

Register a new channel

Each new online chat channel requires moderation. Send an inquiry to amoCRM technical support for registering a new channel of online chats

You can send the request in any convenient way:

• Email us

• Write to us in Facebook chats

In the format:

1. The name of the service with which you plan to integrate

2. Webhook URL, to which messages from amoCRM will be sent. The URL must be of the form https://domain.com/location/:scope_id. Marker :scope_id will be dynamically substituted by the system. With it, you will be able to identify from which account the message came.

3. The list of accounts (customer number) that will be allowed to work with the new channel.

4. Email for communication in case of errors.

5. SVG icon of your channel. The icon should have the shape of a circle or fit into a circle. Size 14x14px

6. Do you plan to replicate the solution to all amoCRM users?

   1. Is there already a similar solution in amoCRM?

   2. If there is such a solution, what is unique about yours?

In the answer you will be sent the parameters of access to the API of online chats.

The period for consideration of applications is 1-3 working days.

Example of access parameters

Obtaining an account ID for working with the online chat service

To work with the service you need to get a unique account ID. It is different from the customer number.

You can receive it in two ways:

• On the front, using the JS script

• Using the amoCRM API request

JS

This method can be used by the widget. Run the following script:

Example:

AMOCRM.constant('account').amojo_id

For example, in the browser console:

/private/api/v2/json/accounts/current

As an extra GET parameter pass amojo=Y

Example:

/*
 Getting the ID of the account to start working with chats
 */
// Login of the amoCRM user
$login = 'user@example.com';
// API hash of the user
$hash = '******************';
// Subdomain of the account
$subdomain = 'onlinechat';
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://{$subdomain}.amocrm.com/private/api/v2/json/accounts/current?amojo=Y&USER_LOGIN=
{$login}&USER_HASH={$hash}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_COOKIEFILE => dirname(__FILE__).'/cookie.txt',
    CURLOPT_COOKIEJAR => dirname(__FILE__).'/cookie.txt',
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
$account = json_decode($response, true)['response']['account'];
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $account['amojo_id']; // 13fa84f7-6b61-4086-98ed-0a9de19ee15c
}

Connecting amoCRM to a new channel

You have access to us from us. It’s time to connect your account to a new channel.

For this we need:

• The account ID of amoCRM for the online chat service. How to obtain it is described in detail below

• The channel ID and secret that you received in the response letter from the technical support amoCRM

We create a POST request, which specifies the account ID to connect to our channel.

We sign the request with a secret and add a signature to the X-Signature header

PHP example

In response, we get the account id and unique scope id, which we need to publish messages to the account

Response example:

{
  "account_id": "13fa84f7-6b61-4086-98ed-0a9de19ee15c",
  "scope_id": "a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c"
}

Sending a message

You can send messages of the following types: text, image, file, location, contact.

The format of the request data is described in detail in the API Send message

To send a message we need:

• Scope id, which we received when connecting the account to the channel

• The secret of the channel for the formation of a signature

Let’s consider some examples:

Example

/*
 Connect to the amoCRM account to the new channel of online chats
 */
// Secret for our channel, to form a signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Scope id for publishing messages in the account
$scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Body of the request
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
        'timestamp' => time(),
        'msgid' => uniqid(),
        'conversation_id' => uniqid('c'),
        'sender' => [
            'id' => 'U1',
            'avatar' => 'https://www.amocrm.com/version2/images/logo_bill.png',
            'name' => 'John',
            'profile' => [
                'phone' => 79151112233,
                'email' => 'email@domain.com',
            ],
            'profile_link' => 'http://example.com',
        ],
        'message' => [
            'type' => 'text',
            'text' => 'This one?'
        ]
    ]
]);
// Forming the signature
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://amojo.amocrm.com/v2/origin/custom/{$scope_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => array(
        "cache-control: no-cache",
        "content-type: application/json",
        "x-signature: {$signature}"
    ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response;
}

The amoCRM interface instantly receives a new request (an Incoming Lead)

Notification Center

Interface of the pipeline

The card with the incoming lead:

Any employee who has access to the incoming lead card can look at the correspondence and respond to the client.

Receiving a response to a callback URL

Once the amoCRM user has responded to the client, a POST request with the message data must arrive at the callback URL.

Webhook in the JSON format

{
  "receiver": "U1",
  "conversation_id": "c59678affa1db6",
  "type": "text",
  "text": "Yes, of course. This is just what I was looking for",
  "media": "",
  "thumbnail": "",
  "file_name": "",
  "file_size": 0
}

Widget Development

You can give other amoCRM users the option to add your channel to your account. To do this, you need to develop a widget, through which the user will be able to link your account with your channel.

More details about the development of the widget can be found in the documentation for widgets

Additional requirements for the widget

In manifest.json, add the “lead_sources” parameter to the locations object. After that, your widget will be displayed in the chat settings section

Example of a widget connection script:

1. The user activates the widget’s connection window

2. Enter login / password from your service account

3. Sends a login / password and id of its account to your server. The account id can be obtained by the widget automatically through the following JS script: AMOCRM.constant (‘account’). amojo_id

4. Your server validates credentials and prompts you to connect a new account to the chat channel.