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

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 Сообщение
    slient 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 Телефон

    Пример

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

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