API online чатов

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

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

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

Пример на PHP:

  1. <?php
  2. /**
  3.  * Пример формирования SHA1 подписи
  4.  */
  5.  
  6. // Секрет нашего канала, для фомирования подписи
  7. $secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
  8.  
  9. // Тело запроса
  10. $body = json_encode([
  11.     'event_type' => 'new_message',
  12.     'payload' => [
  13.         'timestamp' => 1500035254,
  14.         'msgid' => '5968b8c76b84c',
  15.         'conversation_id' => 'c5968b8d25082c',
  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. // Формируем подпись
  34. $signature = hash_hmac('sha1', $body, $secret);
  35.  
  36. print($signature); // 894a6bfd9141461c177baa06b9504558bbcab686

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

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

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

Resource URL

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

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Parameters

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

Пример на 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. }

Response Field Guide

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

PARAMETER TYPE DESCRIPTION
account_id строка Идентификатор аккаунта
scope_id строка UUID, scope_id аккаунта для вашего канала

Response example

  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 ОК

Resource URL

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

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Parameters

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

Пример на 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}/disconnect",
  26.     CURLOPT_RETURNTRANSFER => true,
  27.     CURLOPT_TIMEOUT => 30,
  28.     CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  29.     CURLOPT_CUSTOMREQUEST => "DELETE",
  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. }

Response Example

200 OK

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

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

Resource URL

POST /v2/origin/custom/‹score id›

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Parameters

PARAMETER TYPE DESCRIPTION
event_type строка Тип события. Доступны: new_message
payload Объект Детальная информация

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

PARAMETER TYPE REQUIRED DESCRIPTION
timestamp Целое число Да Время создания сообщения, unix
msgid Строка Да Уникальный идентификатор сообщения
conversation_id Строка Да Уникальный идентификатор переписки
sender Объект Да Отправитель
message Объект Да Сообщение

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

PARAMETER TYPE REQUIRED DESCRIPTION
id Строка Да Уникальный идентификатор отправителя
avatar Строка Да URL на аватар. Ссылка должна быть доступна серверам amoCRM
name Строка Да Имя отправителя
profile_link Строка Нет Внешняя публичная ссылка на профиль пользователя, если поддерживается
profile Объект Нет Дополнительная информация о клиенте

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

PARAMETER TYPE REQUIRED DESCRIPTION
phone целое число Нет Телефон, если есть информация. Будет добавлен в соц. профиль контакта
email строка, Email Нет Email, если есть информация. Будет добавлен в соц. профиль контакта

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

PARAMETER TYPE REQUIRED DESCRIPTION
type Строка Да Уникальный идентификатор отправителя
text Строка Да, для типа text URL на аватар. Ссылка должна быть доступна серверам amoCRM
media Строка Да, для типов:
  • picture,
  • video,
  • file,
  • sticker
Ссылка на файл. Должна быть доступна серверам amoCRM
location Объект Да, для location Информация о местоположении
contact Объект Да, для contact Информация по контакту
file_name Строка Да, для типов:
  • picture,
  • video,
  • file,
Название файла
file_size Целое число, байты Да, для типов:
  • picture,
  • video,
  • file,
Размер файла

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

PARAMETER TYPE DESCRIPTION
lon Число с плавающей точкой Долгота
lat Число с плавающей точкой Широта

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

PARAMETER TYPE DESCRIPTION
name Строка Имя
phone Строка Телефон

Пример на 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. }

Webhook

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

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

Resource URL

POST <Your webhook url>

X-Signature: ‹hmac›

Content-Type: application/json

Parameters

PARAMETER TYPE REQUIRED DESCRIPTION
receiver Строка Да id получателя
conversation_id Строка Да Идентификатор переписки
type Строка Да Типа сообщения. Доступны: text, picture, file
text Строка Да, для типа text Текст сообщения
media Строка Да, для типа picture, file URL на файл
thumbnail Строка Да, для типа picture URL на миниатюру
file_name Строка Да, для типа file Название файла
file_size Целое число Да, для типа file Размер файла в байтах

Пример обработки Webhook на PHP

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