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

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 к новому каналу

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

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

Пример

<?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
]);
// Формируем подпись
$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 аккаунта для вашего канала

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

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

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

Пример


<?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

 

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

 

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

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, 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;
}