Capabilities

The online chats functionality allows amoCRM users to exchange messages with their clients while the clients use the messenger they are used to for the communication.

Generally, the conversation can only be initiated by the client.

amoCRM API allows developers to integrate various channels for messaging. For the end-user their work with such channels in the amoCRM inteface will not differ from the already implemented channels (WhatsApp, Facebook, Telegram, etc).

A developer can create an integration for personal use on their account or distribute it for all amoCRM accounts by creating a widget.

To begin the development, you’ll need:

  • An active amoCRM account. You can register a free trial at https://www.amocrm.com
  • A public endpoint on your server where you’ll receive webhooks for messages sent from the amoCRM interface
  • Access to the Chats API. It has to be requested via the amoCRM technical support. This process is described in detail here

Message exchange

The diagram below showcases the process of sending and receiving messages via the amoCRM account

Registering a new channel

You can send the registration inquiry any convenient way:

  • Via Facebook
  • Telegram bot
  • amoCRM website
  • Support chat from your amoCRM account

In the following format:

  1. The name of the service you are planning to integrate. The name of the service should consist of latin symbols and should not begin with a digit.
    The name of the service will be displayed with the SVG icon of your channel under the name of the contact created via this channel.
  2. Webhook URL to receive messages sent from amoCRM to. URL should be of the following format: https://domain.com/location/:scope_id.
    The :scope_id marker will be dynamically substituted by the system. You can use it to identify the account the message came from.
  3. The list of amoCRM accounts (client IDs) to be allowed to work with the channel.
  4. Do you need the “initiate conversation” feature enabled?
  5. Email for communication in case of errors.
  6. SVG icon of your channel. The icon should be the shape of a circle or fit into a circle. Size 14x14px
  7. Integration ID that will be working with Chats API
  8. Do you plan to distribute your solution for all amoCRM users?

    1. Is there already a similar solution in amoCRM?
    2. If there is such a solution, what is unique about yours?

You will receive the Chats API access credentials in the response to your application.

Applications are reviewed within 1-3 business days.

Example of access credentials

Parameter Description
Chat channel code amo.ext.some_code
Channel ID a4490ccc-5d7f-11e7-907b-a6006ad3dba0
Channel secret da39a3ee5e6b4b0d3255bfef95601890afd80709
The list of accounts that can connect to the channel 11223344 (somesubdomain)
11334455 (somesubdomain2)

Acquiring the amoCRM chat service ID for the account

To work with the chat service you need to acquire a unique account ID. It is different from the client ID.

It can be acquired in two ways:

  • From the front-end with the JS script
  • Using the request to the amoCRM API

Javascript

This option can be used by the widget. You need to execute the following script:

Example:

AMOCRM.constant('account').amojo_id

API request

The following method should be used: /api/v4/account?with=amojo_id

Example:

<?php
/**
 * Acquiring the the amoCRM chat service ID for the account
 */

// composer require amocrm/amocrm-api-library

require __DIR__ . '/vendor/autoload.php';

$clientId = 'dbcb764d-b02d-4a3b-bc4d-25e1d80fdcad';
$clientSecret = 'BbL70GJrKcBlg8cag9VaXKxrzUnxiaPOG4XU3Sc6ddFj9GxOStKryI4wOK4g9kjo';
$redirectUri = 'https://example.com/sample-integration';
$baseDomain = 'onlinechat.amocrm.com';
$code = <<<EOF
def50200189...<integration's authorization code>...159f568
EOF;

$apiClient = new \AmoCRM\Client\AmoCRMApiClient($clientId, $clientSecret, $redirectUri);
$apiClient->setAccountBaseDomain($baseDomain);
try {
    $accessToken = $apiClient->getOAuthClient()->getAccessTokenByCode($code);

    $apiClient->setAccessToken($accessToken);

    $account = $apiClient->account()->getCurrent([\AmoCRM\Models\AccountModel::AMOJO_ID]);
    echo "amojoId: " . $account->getAmojoId() . PHP_EOL;
} catch (Exception $e) {
    die((string)$e);
}

Example:

amojoId: 52a350c1-b0e1-4e38-ab2e-125e5f046dfa