Online чаты

Функционал онлайн чатов позволяет пользователям amoCRM обмениваться мгновенными сообщениями со своими клиентами. При этом клиенты используют для коммуникации привычный для себя мессенджер.

Как правило, инициировать переписку может только клиент.

API amoCRM позволяет разработчикам интегрировать различные каналы мгновенных сообщений. Для конечного пользователя работа в интерфейсе amo с такими каналами ничем не будет отличаться от уже встроенных в CRM (vk, facebook, telegram и тд).

Разработчик может сделать интеграцию только для своего аккаунта, либо тиражировать решение на всех пользователей amoCRM посредством виджета.

Чтобы приступить к интеграции вам потребуется:

  • Активный аккаунт amoCRM. Можно зарегистрировать триал на сайте https://www.amocrm.ru
  • Открыть публичный endpoint на своем сервере, куда будут приходить уведомления о новых сообщениях из интерфейса amoCRM
  • Доступы к API online чатов. Его необходимо запросить через техническую поддержку amoCRM. Подробнее этот процесс описан тут

Обмен сообщениями

Диаграмма ниже демонстрирует процесс отправки и получения сообщений через аккаунт amoCRM

Бекенд online чатов
[Not supported by viewer]
Ваш сервер
Ваш сервер
Обработка
Обработка
Обработка
Обработка
Бекенд соц. сети, мессенджера и тд
Бекенд соц. сети, мессенджера и тд
Интерфейс amoCRM
[Not supported by viewer]
Новое сообщение
Новое сообщение
Новое сообщение
Новое сообщение
Код ответа
Код ответа
Код ответа
Код ответа
Новое сообщение
Новое сообщение
Код ответа
Код ответа
Новое сообщение
Новое сообщение
Код ответа
Код ответа
Новое сообщение
Новое сообщение
Код ответа
Код ответа
Новое сообщение
Новое сообщение
Код ответа
Код ответа

Регистрация нового канала

Каждый новый канал online чатов требует модерации. Отправьте запрос в техническую поддержку amoCRM для регистрации нового канала online чатов

Вы можете отправить запрос любым удобным вам способом:

  • Почта support@amocrm.ru
  • Наши страницы в соц. сетях
  • Бот в телеграм
  • Через наш промо сайт
  • Прямо из вашнего аккаунта amoCRM

В формате:

  1. Название сервиса, с которым вы планируете интеграцию
  2. Webhook URL, на который будут присылаться сообщения из amoCRM. URL должен быть вида https://domain.com/location/:scope_id. Маркер :scope_id будет динамически подставляться системой. С его помощью вы сможете идентифицировать, из какого аккаунта пришло сообщение.
  3. Список аккаунтов (номер клиента), которым будет разрешена работа с новым каналом.
  4. Email для связи в случае возникновения ошибок.
  5. SVG иконка вашего канала. Иконка должна иметь форму круга либо вписываться в круг. Размер 14х14px
  6. Планируете ли вы тиражировать решение на всех пользователей amoCRM?
    1. Есть ли уже подобное решение в amoCRM?
    2. Если подобное решение есть, в чем уникальность вашего?

В ответ вам будут высланы параметры доступа к API онлайн-чатов.

Срок рассмотрения заявок 1-3 рабочих дня.

Пример параметров доступа

Символьный код канала amo.ext.some_code
ID канала a4490ccc-5d7f-11e7-907b-a6006ad3dba0
Секрет da39a3ee5e6b4b0d3255bfef95601890afd80709
Список аккаунтов, для которых одобрено подключения канала 11223344 (somesubdomain)
11334455 (somesubdomain2)

Получение ID аккаунта для работы с сервисом online чатов

Для работы с сервисом вам необходимо получить уникальный ID аккаунта. Он отличается от номера клиента.

Получить его можно двумя способами:

  • На фронте, с помощью скрипта JS
  • C помощью запроса к API amoCRM

JS

Данный способ может использоваться виджетом. Выполните следующий скрипт:

  1.     AMOCRM.constant('account').amojo_id

Запрос к API

Необходимо использовать метод /private/api/v2/json/accounts/current

В качестве дополнительного GET параметра передать amojo=Y

  1. <?php
  2. /**
  3.  * Получение id аккаунта для работы с online чатами
  4.  */
  5.  
  6. // Логин пользователя amoCRM
  7. $login = 'user@example.com';
  8.  
  9. // API hash пользователя
  10. $hash = '******************';
  11.  
  12. // Субдомен аккаунта
  13. $subdomain = 'onlinechat';
  14.  
  15. $curl = curl_init();
  16.  
  17.     CURLOPT_URL => "http://{$subdomain}.amocrm.ru/private/api/v2/json/accounts/current?amojo=Y&USER_LOGIN={$login}&USER_HASH={$hash}",
  18.     CURLOPT_RETURNTRANSFER => true,
  19.     CURLOPT_TIMEOUT => 30,
  20.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  21.     CURLOPT_CUSTOMREQUEST => "GET",
  22.     CURLOPT_COOKIEFILE => dirname(__FILE__).'/cookie.txt',
  23.     CURLOPT_COOKIEJAR => dirname(__FILE__).'/cookie.txt',
  24. ));
  25.  
  26. $response = curl_exec($curl);
  27. $err = curl_error($curl);
  28.  
  29. curl_close($curl);
  30.  
  31. $account = json_decode($response, true)['response']['account'];
  32.  
  33. if ($err) {
  34.     echo "cURL Error #:" . $err;
  35. } else {
  36.     echo $account['amojo_id']; // 13fa84f7-6b61-4086-98ed-0a9de19ee15c
  37. }

Подключение аккаунта amoCRM к новому каналу

Вы получили от нас параметры доступа. Самое время подключить ваш аккаунт к новому каналу.

Для этого нам потребуется:

  • Идентификатор аккаунта amoCRM для сервиса online чатов. Как его получить подробно описано ниже
  • Идентификатор канала и секрет, который вы получили в ответном письме от технической поддержки amoCRM

Формируем POST запрос, в котором указываем идентификатор аккаунта для подключения к нашему каналу.

Подписываем запрос с помощью секрета и добавляем подпись в заголовок X-Signature

Пример на PHP

  1. <?php
  2. /**
  3.  * Подключение аккаунта amoCRM к новому каналу online чатов
  4.  */
  5.  
  6. // Секрет нашего канала, для фомирования подписи
  7. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
  8.  
  9. // ID нашего канала
  10. $channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
  11.  
  12. // Идентификатор аккаунта для сервиса online чатов
  13. $account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
  14.  
  15. // Тело запроса
  16. $body = json_encode([
  17.     'account_id' => $account_id
  18. ]);
  19.  
  20. // Формируем подпись
  21. $signature = hash_hmac('sha1', $body, $secret);
  22.  
  23. $curl = curl_init();
  24.  
  25.     CURLOPT_URL => "https://amojo.amocrm.ru/v2/origin/custom/{$channel_id}/connect",
  26.     CURLOPT_RETURNTRANSFER => true,
  27.     CURLOPT_TIMEOUT => 30,
  28.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  29.     CURLOPT_CUSTOMREQUEST => "POST",
  30.     CURLOPT_POSTFIELDS => $body,
  31.     CURLOPT_HTTPHEADER => array(
  32.         "Cache-Control: no-cache",
  33.         "Content-Type: application/json",
  34.         "X-Signature: {$signature}"
  35.     ),
  36. ));
  37.  
  38. $response = curl_exec($curl);
  39. $err = curl_error($curl);
  40.  
  41. curl_close($curl);
  42.  
  43. if ($err) {
  44.     echo "cURL Error #:" . $err;
  45. } else {
  46.     echo $response;
  47. }

В ответ мы получаем id аккаунта и уникальный scope id, который нам понадобится для публикации сообщений в аккаунт

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

Отправка сообщения

Вы можете отправлять сообщения следующих типов: текст, изображение, файл, локация, контакт.

Очень подробно формат данных запроса описана в разделе API Отправка сообщения

Для отправки сообщения нам понадобится:

  • Scope id, который мы получили при подключении аккаунта к каналу
  • Секрет канала для формирования подписи

Рассмотрим несколько примеров:

Пример на PHP

  1. <?php
  2.  
  3. /**
  4.  * Подключение аккаунта amoCRM к новому каналу online чатов
  5.  */
  6.  
  7. // Секрет нашего канала, для фомирования подписи
  8. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
  9.  
  10. // Scope id для публикации сообщений в аккаунт
  11. $scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
  12.  
  13. // Тело запроса
  14. $body = json_encode([
  15.     'event_type' => 'new_message',
  16.     'payload' => [
  17.         'timestamp' => time(),
  18.         'msgid' => uniqid(),
  19.         'conversation_id' => uniqid('c'),
  20.         'sender' => [
  21.             'id' => 'U1',
  22.             'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
  23.             'name' => 'John',
  24.             'profile' => [
  25.                 'phone' => 79151112233,
  26.                 'email' => 'email@domain.com',
  27.             ],
  28.             'profile_link' => 'http://example.com',
  29.         ],
  30.         'message' => [
  31.             'type' => 'text',
  32.             'text' => 'Привет! Сколько стоит разработать сайт?'
  33.         ]
  34.     ]
  35. ]);
  36.  
  37. // Формируем подпись
  38. $signature = hash_hmac('sha1', $body, $secret);
  39.  
  40. $curl = curl_init();
  41.  
  42.     CURLOPT_URL => "https://amojo.amocrm.ru/v2/origin/custom/{$scope_id}",
  43.     CURLOPT_RETURNTRANSFER => true,
  44.     CURLOPT_TIMEOUT => 30,
  45.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  46.     CURLOPT_CUSTOMREQUEST => "POST",
  47.     CURLOPT_POSTFIELDS => $body,
  48.     CURLOPT_HTTPHEADER => array(
  49.         "cache-control: no-cache",
  50.         "content-type: application/json",
  51.         "x-signature: {$signature}"
  52.     ),
  53. ));
  54.  
  55. $response = curl_exec($curl);
  56. $err = curl_error($curl);
  57.  
  58. curl_close($curl);
  59.  
  60. if ($err) {
  61.     echo "cURL Error #:" . $err;
  62. } else {
  63.     echo $response;
  64. }

В интерфейс amoCRM моментально приходит новый запрос (карточка неразобранного)

Теперь, любой сотрудник, имеющий доступ к карточке неразобранного, может посмотреть переписку и ответить клиенту.

Получение ответа на URL обратного вызова

Как только пользователь amoCRM ответил клиенту, на URL обратного вызова должен прийти POST запрос с данными сообщения.

JSON

  1. {
  2.   "receiver": "U1",
  3.   "conversation_id": "c59678affa1db6",
  4.   "type": "text",
  5.   "text": "Привет,  Джон! Для Вас - Бесплатно! Но... есть нюансы.",
  6.   "media": "",
  7.   "thumbnail": "",
  8.   "file_name": "",
  9.   "file_size": 0
  10. }

Разработка виджета

Вы можете предоставить другим пользователям amoCRM возможность подлючить ваш канал к своему аккаунту. Для этого необходимо разработать виджет, с помощью которого пользователь сможет связать свой аккаунт с вашим каналом.

Подробнее о разработке виджета вы можете прочитать в документации по виджетам

Дополнительные требования к виджету

  • В manifest.json, в объект locations добавить параметр “lead_sources”. После чего ваш виджет отобразится в разделе настройки чатов

Пример сценария подключения виджета:

  1. Пользователь активирует окно подключения виджета
  2. Вводит логин / пароль от учетной записи вашего сервиса
  3. Отправляет на ваш сервер связку логин/пароль и id своего аккаунта. id аккаунта может быть получен виджетом автоматически через следующий JS скрипт: AMOCRM.constant('account').amojo_id
  4. Ваш сервер валидирует учетные данные и вызывает запрос на подключение нового аккаунта к каналу чатов.

Пример виджета: Скачать