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

API online чатов

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

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

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

Пример

<?php
/*
 Пример формирования SHA1 подписи
 */
// Секрет нашего канала, для фомирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Тело запроса
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
        'timestamp' => 1500035254,
        'msgid' => '5968b8c76b84c',
        'conversation_id' => 'c5968b8d25082c',
        'silent' => false,
        'sender' => [
            'id' => 'U1',
            'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
            'name' => 'John',
            'profile' => [
                'phone' => 79151112233,
                'email' => 'email@domain.com',
            ],
            'profile_link' => 'http://example.com',
        ],
        'message' => [
            'type' => 'text',
            'text' => 'Привет! Сколько стоит разработать сайт?'
        ]
    ]
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
print ($signature); // 894a6bfd9141461c177baa06b9504558bbcab686

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

Обновлено 20.11.2019

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

Чтобы подключить аккаунт к каналу чатов, вам необходимо выполнить 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, Уникальный идентификатор аккаунта для работы с сервисом онлайн-чатов.
title

Обновлено 20.11.2019

string Название скопа. Например, номер WhatsApp. P.S в дальнейшем будет разрешено добавлять несколько скопов, например, если у пользователя несколько номеров WhatsApp.
hook_api_version

Обновлено 20.11.2019

string Версия Webhook, который будет отправлен при наступлении события в этом скопе. По умолчанию v1. Доступные значения: v1, v2

Пример



<?php 
/*
Подключение аккаунта amoCRM к новому каналу online чатов
*/
// Секрет нашего канала, для формирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID нашего канала
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Идентификатор аккаунта для сервиса online чатов
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Тело запроса
$body = json_encode([
    'account_id' => $account_id,
    'title' => '+79151112211',
    'hook_api_version' => 'v2'
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://amojo.amocrm.ru/v2/origin/custom/{$channel_id}/connect",
    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;
}

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

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

Параметр Тип Описание
account_id string Идентификатор аккаунта
scope_id string UUID, scope_id аккаунта для вашего канала
title

Обновлено 20.11.2019

string Название скопа
hook_api_version

Обновлено 20.11.2019

string Версия Webhook

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

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

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

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

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

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

URL метода

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

Host: amojo.amocrm.ru

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

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

Пример


<?php 
/*
 Отключение аккаунта amoCRM от канала online чатов
 */
// Секрет нашего канала, для фомирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID нашего канала
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Идентификатор аккаунта для сервиса online чатов
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Тело запроса
$body = json_encode([
    'account_id' =&gt; $account_id
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL =&amp;gt; "https://amojo.amocrm.ru/v2/origin/custom/{$channel_id}/disconnect",
    CURLOPT_RETURNTRANSFER =&amp;gt; true,
    CURLOPT_TIMEOUT =&amp;gt; 30,
    CURLOPT_HTTP_VERSION =&amp;gt; CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST =&amp;gt; "DELETE",
    CURLOPT_POSTFIELDS =&amp;gt; $body,
    CURLOPT_HTTPHEADER =&amp;gt; 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;
}

 

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

 

200 OK

 

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

Обновлено 20.11.2019

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

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

Обновлено 20.11.2019

Параметр Тип Описание
timestamp
require
int Время создания сообщения, unix
msgid
require
string Уникальный идентификатор сообщения
conversation_id
require
string Уникальный идентификатор переписки
conversation_ref_id

Обновлено 20.11.2019

uuid Идентификатор чата на стороне amoCRM. Используется чтобы связать чат на стороне интеграции с чатом amoCRM при первом сообщении, чтобы продолжить переписку. (см. Написать первым)
sender
require
object Отправитель
message
require
object Сообщение
silent bool Флаг silent указывает, будет ли сообщение помечено как новое. Если указано true – вызова нотификации не произойдет, удобно при импорте сообщений

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

Параметр Тип Описание
id
require
string Уникальный идентификатор отправителя
ref_id

Обновлено 20.11.2019

uuid Идентификатор отправителя на стороне amoCRM. Используется чтобы связать получателя на стороне интеграции с профилем контакта amoCRM при первом сообщении, чтобы продолжить переписку. (см. Написать первым)
avatar
require
string URL на аватар. Ссылка должна быть доступна серверам amoCRM
name
require
string Имя отправителя
profile_link Строка Внешняя публичная ссылка на профиль пользователя, если поддерживается
profile object Дополнительная информация о клиенте

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

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

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

Параметр Тип Описание
type require string Тип сообщения. Доступны: text, picture, video, file, sticker, contact, location
text string Текст сообщения.
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 Телефон

Пример

<?php
/*
 Подключение аккаунта amoCRM к новому каналу online чатов
 */
// Секрет нашего канала, для фомирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Scope id для публикации сообщений в аккаунт
$scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Тело запроса
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
        'timestamp' => time(),
        'msgid' => uniqid(),
        'conversation_id' => uniqid('c'),
        'sender' => [
            'id' => 'U1',
            'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
            'name' => 'John',
            'profile' => [
                'phone' => 79151112233,
                'email' => 'email@domain.com',
            ],
            'profile_link' => 'http://example.com',
        ],
        'message' => [
            'type' => 'text',
            'text' => 'Привет! Сколько стоит разработать сайт?'
        ]
    ]
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://amojo.amocrm.ru/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;
}

Импорт диалогов

SilentImport

Для импорта истории сообщений вам необходимо отправить все сообщения в amoCRM используя метод /v2/origin/custom/score id.

В message вы передаете тело сообщения(текст, изображение, видео и т.д.) и используете параметр silent объекта payload передав ему значение true

“silent:true”- служит для загрузки сообщений в уже существующий чат без push-уведомлений в ЦН, не создает новую сделку в amoCRM.

К примеру:

Переписка в мессенджере

Mikle: Привет, мне нужен велосипед X45.    02.02.2016 14:30
BicycleShop: Хорошо, доставим завтра.     02.02.2016 14:45
Mikle:Спасибо, буду ждать!    02.02.2016 14:50

Mikle: Привет, мне нужен этот же товар завтра!    27.08.2019 17:46

<?php
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
    'timestamp' => time(),
    'msgid' => uniqid(),
    'conversation_id' => "12345671", //связывает сообщения друг с другом в один чат
    'sender' => [
        'id' => '12345678',
        'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
        'name' => 'Mikle',
        'profile' => [
            'phone' => 79151282113,
            'email' => 'mikle @domain.com',
        ],
        'profile_link' => 'http://example.com',
    ],
        'message' => [
            'type' => 'text',
            'text' => 'Привет, мне нужен велосипед  X45'
        ],
        'silent' => true,        
    ]
]);
<?php
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
    'timestamp' => time(),
    'msgid' => uniqid(),
    'conversation_id' => "12345671", //связывает сообщения друг с другом в один чат
    'sender' => [
        'id' => '12345678',
        'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
        'name' => 'Mikle',
        'profile' => [
            'phone' => 79151282113,
            'email' => 'mikle @domain.com',
        ],
        'profile_link' => 'http://example.com',
    ],
        'message' => [
            'type' => 'text',
            'text' => 'Спасибо, буду ждать!'
        ],
        'silent' => true,        
    ]
]);

В интерфейсе amoCRM по-прежнему ничего не происходит Теперь нам приходит новое сообщение от клиента и нам нужно его отправить с уведомлением без параметра silent либо со значение false

<?php
$body = json_encode([
    'event_type' => 'new_message',
    'payload' => [
    'timestamp' => time(),
    'msgid' => uniqid(),
    'conversation_id' => "12345671", //связывает сообщения друг с другом в один чат
    'sender' => [
        'id' => '12345678',
        'avatar' => 'https://www.amocrm.ru/version2/images/logo_bill.png',
        'name' => 'Mikle',
        'profile' => [
            'phone' => 79151282113,
            'email' => 'mikle @domain.com',
        ],
        'profile_link' => 'http://example.com',
    ],
        'message' => [
            'type' => 'text',
            'text' => 'Привет, мне нужен этот же товар завтра!'
        ]     
    ]
]);

И у нас создается неразобранная сделка, и все сообщения отправленные ранее подгружаются.

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

ЦН – Центр Нотификаций, в web-версии располагается в нижнем левом углу экрана, служит для доставки до пользователя важных событий на которые нужно реагировать (входящие звонки, входящие чаты и т.д.). Доставляется не только в WEB, но и как push-уведомления в мобильных приложениях. Просим не злоупотреблять уведомлениями, чтобы пользователь не был вынужден отключить их в своем профиле.
Неразобранное – сделка в системном первом этапе, подробнее можно ознакомиться тут  
Контакт – хранит в себе информацию о клиенте, сделках и диалогах, диалог в нем не отображается.
Сделка — отображает диалог прикрепленный к контакту.

Одна сделка может иметь связь с несколькими контактами, если вы прикрепите несколько контактов к одной сделке, то вы увидите объединение всей истории переписки, а при написании ответа сможете выбрать какому именно контакту отвечать. Если с одним контактом создать несколько сделок, то мы увидим одну историю общения и в одной карточки сделки и в другой. При этом давность показа истории ограничена датой создания сделки, то есть давностью ее timeline.

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

Пример

/*
 Пример обработки webhook
 */
// Пример бизнес логики
function save_text_message($to, $chat_id, $text)
{
    // Сохраняем текстовое сообщение
}

function save_picture_message($to, $chat_id, $fid, $description = NULL)
{
    // Сохраняем изображение
}

function save_file_message($to, $chat_id, $fid, $filename, $size, $description = NULL)
{
    // Сохраняем файл
}

function download_file($url)
{
    // сохраняем файл по ссылке на диск, возвращаем идентификатор
    return 0;
}

// Секрет нашего канала, для проверки подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Данные запроса
$body_res = stream_get_contents(STDIN);
if (empty ($body_res)) {
    throw new RuntimeException('Empty body');
}
// Формируем подпись
$signature = hash_hmac('sha1', $body_res, $secret);
// Проверяем, что это POST запрос
if ($_SERVER ['REQUEST_METHOD'] !== 'POST') {
    throw new RuntimeException('Unsupported request');
}
// Проверяем подпись
if ($signature !== $_SERVER ['HTTP_X_SIGNATURE']) {
    throw new RuntimeException('Invalid signature');
}
$message = json_decode($body_res);
if (!$message) {
    throw new RuntimeException('Unsupported body');
}
switch ($message ['type']) {
    case 'text' :
        save_text_message(
            $message ['receiver'],
            $message ['conversation_id'],
            $message ['text']
        );
        break;
    case 'picture' :
        $fid = download_file($message ['media']);
        save_picture_message(
            $message ['receiver'],
            $message ['conversation_id'],
            $fid,
            $message ['text']
        );
        break;
    case 'file' :
        $fid = download_file($message ['media']);
        save_file_message(
            $message ['receiver'],
            $message ['conversation_id'],
            $fid,
            $message ['file_name'],
            $message ['file_size'],
            $message ['text']
        );
        break;
}

Webhook 2.0

Новое 20.11.2019

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

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

URL метода

POST <Your webhook url>

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

Параметр Тип Описание
account_id string,uuid идентификатор аккаунта на стороне amoCRM, в котором произошло событие
time int, timestamp Время отправки хука
message MessageEvent Событие нового сообщения

 

MessageEvent

Параметр Тип Описание
receiver Receiver Структура получателя
conversation Conversation Структура переписки
timestamp int, timestamp Время написания сообщения
message Message Структура сообщения

 

Receiver

Параметр Тип Описание
id string, uuid Идентификатор получателя на стороне amoCRM
phone string Номер телефона получателя
client_id string Ваш идентификатор получателя. Пустой, если переписка инициирована со стороны amoCRM.

 

Conversation

Параметр Тип Описание
id string, uuid Идентификатор переписки на стороне amoCRM
client_id string Ваш идентификатор переписки. Пустой, если переписка инициирована со стороны amoCRM.

 

Message

Параметр Тип Описание
id string,uuid id сообщения на стороне amoCRM
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

 

Статус доставки сообщения

Новое 20.11.2019

Для обновления статуса доставки сообщения, необходимо отправить POST запрос на сервер amoCRM.

URL метода

POST /v2/origin/custom/<scope_id>/<msgid>/delivery_status

X-Signature: ‹hmac›

Content-Type: application/json

Параметры

Параметр Тип Описание
msgid string, uuid Идентификатор сообщения. Должно совпадать с msgid в URL
delivery_status int Статус доставки. 1 – Доставлено. 2 – Прочитано. 1 – Ошибка
error_сode int Тип ошибки. 901 – Пользователь удалил переписку. 902 – Интеграци отключена на стороне канала. 903 – Внутрення ошибка сервера. 904 – Невозможно создать переписку. Например, пользователь не зарегистрирован в WhatsApp. 905 – Любая другая, видимая пользователю (будет отображаться текст из error
error string Текст ошибки. Будет отображаться пользователю.

Пример

<?php
/*
Подключение аккаунта amoCRM к новому каналу online чатов
*/
// Секрет нашего канала, для формирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID нашего канала
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Идентификатор аккаунта для сервиса online чатов
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';

// Идентификатор сообщения, которому будем менять статус
$message_id = 'fbd27636-0c4b-11ea-8d71-362b9e155667';
// Тело запроса
$body = json_encode([
    'msgid' => $message_id,
    'delivery_status' => -1,
    'error_code' => 902
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://amojo.amocrm.ru/v2/origin/custom/{$channel_id}/{$message_id}/delivery_status",
    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;
}

Ответ

200 OK