Разработка чатов

API online чатов

  • Все запросы к API онлайн-чатов должны быть подписаны секретным ключом вашего канала
  • Не использовать серкет в JS. Все запросы с использованием секрета должны выполняться с вашего сервера
  • Параметры передаются в теле запроса в формате JSON
  • API онлайн-чатов имеет строгую типизацию, поэтому в описании параметров отражен ожидаемый тип аргумента. Обратите на это внимание

Формирование подписи sha1

Все запросы включают заголовок X-Signature с подписью SHA1 полезных данных запроса. При создании подписи в качестве ключа используется секрет вашего канала, благодаря чему такая подпись позволяет проверить целостность полезных данных и их происхождение.

Пример

  1. <?php
  2. /*
  3.  Пример формирования SHA1 подписи
  4.  */
  5. // Секрет нашего канала, для фомирования подписи
  6. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
  7. // Тело запроса
  8. $body = json_encode([
  9.     'event_type' => 'new_message',
  10.     'payload' => [
  11.         'timestamp' => 1500035254,
  12.         'msgid' => '5968b8c76b84c',
  13.         'conversation_id' => 'c5968b8d25082c',
  14.         'silent' => false,
  15.         'sender' => [
  16.             'id' => 'U1',
  17.             'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
  18.             'name' => 'John',
  19.             'profile' => [
  20.                 'phone' => 79151112233,
  21.                 'email' => 'email@domain.com',
  22.             ],
  23.             'profile_link' => 'http://example.com',
  24.         ],
  25.         'message' => [
  26.             'type' => 'text',
  27.             'text' => 'Привет! Сколько стоит разработать сайт?'
  28.         ]
  29.     ]
  30. ]);
  31. // Формируем подпись
  32. $signature = hash_hmac('sha1', $body, $secret);
  33. print($signature); // 894a6bfd9141461c177baa06b9504558bbcab686

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

Перед использованием этого метода ознакомьтесь:

Чтобы подключить аккаунт к каналу чатов, вам необходимо выполнить POST запрос, передав в теле запрос id подключаемого аккаунта. В ответ вы получите уникальный scope_id аккаунта для этого канала, который будет использоваться в дальнейшем при публикации сообщений.

URL метода:

POST /v2/origin/custom/ <уникальный id канала>/connect

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

Параметр Тип Описание
account_id string UUID, Уникальный идентификатор аккаунта для работы с сервисом онлайн-чатов.

Пример

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

Параметры ответа

В ответ приходит account scope_id для вашего канала

Параметр Тип Описание
account_id string Идентификатор аккаунта
scope_id string UUID, 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. }

Отключение аккаунта amoCRM от канала

Если вы хотите, чтобы аккаунт больше не получал сообщения из вашего канал, вы можете отключить его.

Перед использованием этого метода ознакомьтесь:

Чтобы отключить аккаунт от канала чатов, вам необходимо выполнить DELETE запрос, передав в теле запрос id отключаемого аккаунта. В ответ вы получите 200 ОК

URL метода

POST /v2/origin/custom/ <уникальный id канала>/disconnect

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

PARAMETER TYPE DESCRIPTION
account_id string UUID, Уникальный идентификатор аккаунта для работы с сервисом онлайн-чатов.

Пример

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

Пример ответа

  1. 200 OK

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

Перед использованием этого метода ознакомьтесь:

URL метода
POST /v2/origin/custom/‹score id›

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

Параметр Тип Описание
event_type string Тип события. Доступны: new_message
payload object Детальная информация

Описание объекта payload

Параметр Тип Описание
timestamp
require
int Время создания сообщения, unix
msgid
require
string Уникальный идентификатор сообщения
conversation_id
require
string Уникальный идентификатор переписки
sender
require
object Отправитель
message
require
object Сообщение
silent
bool Флаг silent указывает, будет ли сообщение помечено как новое. Если указано true - вызова нотификации не произойдет, удобно при импорте сообщений.

Описание объекта sender

Параметр Тип Описание
id
require
string Уникальный идентификатор отправителя
avatar
require
string URL на аватар. Ссылка должна быть доступна серверам amoCRM
name
require
string Имя отправителя
profile_link Строка Внешняя публичная ссылка на профиль пользователя, если поддерживается
profile object Дополнительная информация о клиенте

Описание объекта profile

Параметр Тип Описание
phone int Телефон, если есть информация. Будет добавлен в соц. профиль контакта
email string, Email Email, если есть информация. Будет добавлен в соц. профиль контакта

Описание объекта message

Параметр Тип Описание
type
require
string Уникальный идентификатор отправителя
text string URL на аватар. Ссылка должна быть доступна серверам amoCRM. Обязателен для типа text.
media string

Ссылка на файл. Должна быть доступна серверам amoCRM. Обязателен для типов:

  • picture,
  • video,
  • file,
  • sticker
location object Информация о местоположении. Обязательно для location
contact object Информация по контакту. Обязательно для contact.
file_name string

Название файла. Обязательно для типов:

  • picture,
  • video,
  • file,
file_size int, байты

Размер файла. Обязательно для типов:

  • picture,
  • video,
  • file,

Описание объекта location

Параметр Тип Описание
lon float Долгота
lat float Широта

Описание объекта contact

Параметр Тип Описание
name string Имя
phone string Телефон

Пример

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

Webhook

На URL обратного вызова, который вы указали при регистрации канала, будут приходить новые сообщения из интерфейса amoCRM.

Каждый такой запрос содержит JSON объект, описывающий структуру сообщения и заголовок X-Signature, содержащий подпись полезных данных запроса.

URL метода
POST <Your webhook url>

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

Параметр Тип Описание
receiver
require
string id получателя
conversation_id
require
string Идентификатор переписки
type
require
string Типа сообщения. Доступны: text, picture, file
text string Текст сообщения. Обязательно
media string URL на файл. Обязательно для типа picture, file
thumbnail string URL на миниатюру. Обязательно для типа picture
file_name string Название файла. Обязательно для типа file
file_size int Размер файла в байтах. Обязательно для типа file

Пример

  1. /*
  2.  Пример обработки webhook
  3.  */
  4. // Пример бизнес логики
  5. function save_text_message($to, $chat_id, $text) {
  6.     // Сохраняем текстовое сообщение
  7. }
  8. function save_picture_message($to, $chat_id, $fid, $description = NULL) {
  9.     // Сохраняем изображение
  10. }
  11. function save_file_message($to, $chat_id, $fid, $filename, $size, $description = NULL) {
  12.     // Сохраняем файл
  13. }
  14. function download_file($url) {
  15.     // сохраняем файл по ссылке на диск, возвращаем идентификатор
  16.     return 0;
  17. }
  18. // Секрет нашего канала, для проверки подписи
  19. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
  20. // Данные запроса
  21. $body_res = stream_get_contents(STDIN);
  22. if (empty($body_res)) {
  23.     throw new RuntimeException('Empty body');
  24. }
  25. // Формируем подпись
  26. $signature = hash_hmac('sha1', $body_res, $secret);
  27. // Проверяем, что это POST запрос
  28. if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
  29.     throw new RuntimeException('Unsupported request');
  30. }
  31. // Проверяем подпись
  32. if ($body_res !== $_SERVER['HTTP_X_SIGNATURE']) {
  33.     throw new RuntimeException('Invalid signature');
  34. }
  35. $message = json_decode($body_res);
  36. if (!$message) {
  37.     throw new RuntimeException('Unsupported body');
  38. }
  39. switch ($message['type']) {
  40.     case 'text':
  41.         save_text_message(
  42.             $message['receiver'],
  43.             $message['conversation_id'],
  44.             $message['text']
  45.         );
  46.         break;
  47.     case 'picture':
  48.         $fid = download_file($message['media']);
  49.         save_picture_message(
  50.             $message['receiver'],
  51.             $message['conversation_id'],
  52.             $fid,
  53.             $message['text']
  54.         );
  55.         break;
  56.     case 'file':
  57.         $fid = download_file($message['media']);
  58.         save_file_message(
  59.             $message['receiver'],
  60.             $message['conversation_id'],
  61.             $fid,
  62.             $message['file_name'],
  63.             $message['file_size'],
  64.             $message['text']
  65.         );
  66.         break;
  67. }