Методы API чатов

В данном разделе собраны все методы для работы с API чатов amoCRM.

Оглавление

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

Все запросы АПИ чатов необходимо производить на домен amojo.amocrm.ru или amojo.amocrm.com для аккаунтов в домене *.amocrm.com

Авторизация

Авторизация в АПИ чатов отличается от основного АПИ аккаунта amoCRM.
Для авторизации в каждом запросе необходимо передавать указанные ниже заголовки

  • Date
  • Content-Type
  • Content-MD5
  • X-Signature

Date
Дата и время формирования запроса, подпись будет действительна 15 минут от даты формирования запроса

Content-Type
На данный момент поддерживается только application/json

Content-MD5
Для тела запроса необходимо рассчитать md5 хеш и в заголовке указывать в нижнем регистре. При этом важно иметь ввиду, что тело запроса обсчитывается как поток байт, без учета окончания json разметки, и если в конце есть “\n” или пробелы они тоже будут учитываться.

Для GET запросов, md5 тоже необходимо рассчитать, даже если ничего не передается в теле запроса (получится md5 от пустой строки)

X-Signature
Формируется строка из название метода (GET/POST) в верхнем регистре и значений (как указаны в запросе без изменений) заголовков путем объединения через “\n”. Значения заголовков идут в определенном порядке. В общем случае если заголовок отсутствует, вместо него указывается пустая строка.
Далее к строке добавляем запрашиваемый путь из url без протокола и домена.

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

Пример:

<?php

$secret = '5a44c5dff55f3c15a4cce8d7c4cc27e207c7e189';
$method = 'POST';
$contentType = 'application/json';
$date = 'Thu, 29 Oct 2020 11:59:55 +0000';
$path = '/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41/connect';

$url = "https://amojo.amocrm.ru" . $path;


$requestBody = '{"account_id":"af9945ff-1490-4cad-807d-945c15d88bec","title":"ScopeTitle","hook_api_version":"v2"}';
$checkSum = md5($requestBody);

$str = implode("\n", [
    strtoupper($method),
    $checkSum,
    $contentType,
    $date,
    $path,
]);

$signature = hash_hmac('sha1', $str, $secret);

$headers = [
    "Date" => $date,
    "Content-Type" => $contentType,
];
$headers['Content-MD5'] = strtolower($checkSum);
$headers['X-Signature'] = strtolower($signature);

$curlHeaders = [];
foreach ($headers as $name => $value) {
    $curlHeaders[] = $name . ": " . $value;
}


echo $method . ' ' . $url . PHP_EOL;
foreach ($curlHeaders as $header) {
    echo $header . PHP_EOL;
}
echo PHP_EOL . $requestBody . PHP_EOL;

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_POSTFIELDS => $requestBody,
    CURLOPT_HTTPHEADER => $curlHeaders,
]);

$response = curl_exec($curl);
$err = curl_error($curl);
$info = curl_getinfo($curl);
curl_close($curl);
if ($err) {
    $result = "cURL Error #:" . $err;
} else {
    echo "Status: " . $info['http_code'] . PHP_EOL;
    echo $response . PHP_EOL;
}

Комментарий для действующих интеграций:
Ранее подпись запроса рассчитывалась по другой схеме, но она не позволяла авторизовывать запросы без тела. Старая схема подписи продолжает действовать для существующих подключений и методов, в которых она использовалась.
Новые методы, опубликованные в этом разделе будут работать только с новой схемой подписи, которая была описана выше и мы рекомендуем обновить используемую подпись в существующих интеграциях.

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

Метод

POST /v2/origin/custom/{channel.id}/connect

Описание

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

Ограничения

Требуется корректная подпись запроса в заголовке X-Signature

Заголовок запроса

Content-Type: application/json

Параметры запроса

Все поля обязательные

Параметр Тип данных Описание
account_id string amojo_id аккаунта
hook_api_version string Версия хука, который будет приходить интеграции при исходящих сообщениях. В настройках канала чата, для указанной версии должен быть прописан адрес хука
title string Отображаемое название канала

Пример запроса

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "ChatIntegration",
  "hook_api_version": "v2"
}
        
    

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Канал успешно подключен
404 Канал не существует
403 Подпись запроса некорректная
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод вернет переданные поля запроса, и scope_id который понадобится для работы сообщениями

Параметр Тип данных Описание
account_id string amojo_id аккаунта
hook_api_version string Версия хука, который будет приходить интеграции при исходящих сообщениях. В настройках канала чата, для указанной версии должен быть прописан адрес хука
title string Отображаемое название канала
scope_id string Идентификатор канала для конкретного аккаунта

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

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "scope_id": "f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "Title",
  "hook_api_version": "v2"
}
        
    

Отключение канала чата в аккаунте

Метод

POST /v2/origin/custom/{channel.id}/disconnect

Описание

После отключение канала, перестанут приходить хуки по сообщениям, отправленным в аккаунте по каналу. Так же перестанет выводиться “Написать первым” (по истечению кеша фронта) в карточке сделки

Ограничения

Требуется корректная подпись запроса в заголовке X-Signature

Заголовок запроса

Content-Type: application/json

Параметры запроса

Все поля обязательные

Параметр Тип данных Описание
account_id string amojo_id аккаунта

Пример запроса

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec"
}
        
    

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Канал успешно отключен
404 Канал не существует
403 Подпись запроса некорректная
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод ничего не возвращает

Создание нового чата

Метод

POST /v2/origin/custom/{scope_id}/chats

Описание

Метод позволяет создать чат, до появления первого сообщения. Это может понадобиться если сделка с контактом уже существует и создавать неразобранное не нужно. Чат без сообщений не будет отображаться в аккаунте.

Ограничения

Требуется корректная подпись запроса в заголовке X-Signature

Заголовок запроса

Content-Type: application/json

Параметры запроса

Создаст чат для указанного идентификатора, если для conversaton_id чат уже существует, вернет его id. Массив user обязателен

Параметр Тип данных Описание
conversation_id string Идентификатор чата на стороне интеграции
user[id] string Идентификатор участника чата на стороне интеграции, обязательное поле
user[ref_id] string Идентификатор участника чата на стороне amoCRM, опциональное поле.
user[name] string Имя участника чата, обязательное поле
user[avatar] string Url на аватарку участника чата, необязательное поле. Url должен быть доступен для скачивания
user[profile][phone] string Необязательное поле
user[profile][email] string Необязательное поле
user[profile_link] string Url на профиль участника чата, необящательно поле

Пример запроса

        
{
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "user": {
        "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
        "avatar": "https:/example.com/users/avatar.png",
        "name": "Example Client",
        "profile": {
            "phone": "79151112233",
            "email": "example.client@example.com"
        },
        "profile_link": "http://example.com/profile/example.client"
    }
}

        
    

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Канал успешно подключен
404 Канал не существует
403 Подпись запроса некорректная
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод вернет id чата переданные поля участника чата

Параметр Тип данных Описание
id string Идентификатор чата amojo
user[id] string Идентификатор участника чата amojo
user[client_id] string Идентификатор участника чата на стороне интеграции, для пользователей amocrm поле отсутствует
user[name] string Имя участника чата
user[avatar] string Url на аватарку, если была передана, или пустое поле
user[phone] string Поле отсутствует, если не передавался профиль
user[email] string Поле отсутствует, если не передавался профиль

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

        
{
  "id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
  "user": {
    "id": "86a0caef-41ec-49ac-814b-b27da2cea267",
    "client_id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
    "name": "Example Client",
    "avatar": "https:/example.com/users/avatar.png",
    "phone": "79151112233",
    "email": "example.client@example.com"
  }
}
        
    

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

Метод

POST /v2/origin/custom/{scope_id}

Описание

Метод позволяет передать сообщение от клиента, в этом случае получателя можно не указывать. Также при указании silent: true сообщение от клиента можно проимпортировать без вызова нотификации.

Так же можно проимортировать сообщения от менеджера клиенту, в данном случае получатель обязателен для указания и всегда будет silent флаг выставлен в true.

Хуки по сообщениям переданным на данный метод интеграции не отправляются.

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

Ограничения

Требуется корректная подпись запроса в заголовке X-Signature

Заголовок запроса

Content-Type: application/json

Параметры запроса

Метод создаст сообщение и при необходимости сам чат для указанного msgid и conversation_id соответственно. Структура полей receiver и sender идентичная.
Сообщение может быть адресовано:

– от клиента всем участникам чата (заполняется только поле sender)

– от пользователя аккаунта amoCRM клиенту (заполняются поля sender и receiver, заполняется поле sender[ref_id])

Параметр Тип данных Описание
account_id string amojo_id аккаунта
payload[timestamp] int Время сообщения, метка unix
payload[conversation_id] string Идентификатор чата на стороне интеграции
payload[conversation_ref_id] string Идентификатор чата на стороне amoCRM, опциональное поле
payload[silent] bool Должна ли быть нотификация по сообщению в аккаунте amoCRM
payload[sender][id] string Идентификатор участника чата на стороне интеграции, обязательное поле
payload[sender][ref_id] string Идентификатор участника чата на стороне amoCRM, опциональное поле.
payload[sender][name] string Имя участника чата, обязательное поле
payload[sender][avatar] string Url на аватарку участника чата, необязательное поле. Url должен быть доступен для скачивания
payload[sender][profile][phone] string Необязательное поле
payload[sender][profile][email] string Необязательное поле
payload[sender][profile_link] string Url на профиль участника чата, необящательно поле
payload[receiver][id] string Идентификатор участника чата на стороне интеграции, обязательное поле
payload[receiver][ref_id] string Идентификатор участника чата на стороне amoCRM, опциональное поле.
payload[receiver][name] string Имя участника чата, обязательное поле
payload[receiver][avatar] string Url на аватарку участника чата, необязательное поле. Url должен быть доступен для скачивания
payload[receiver][profile][phone] string Необязательное поле
payload[receiver][profile][email] string Необязательное поле
payload[receiver][profile_link] string Url на профиль участника чата, необящательно поле
payload[msgid] string Идентификатор сообщения чата на стороне интеграции
payload[message][type] string Тип сообщений, может быть одним из списка: text,file,video,picture,voice,audio,sticker
payload[message][text] string Для типа text обязательно, для других типов сообщений может быть пустым
payload[message][media] string Url на картинку,файл,видео,аудио,голос,стикер. Ссылка должна быть доступна для скачивания.
payload[message][file_name] string Название файла для url в поле media, поле опционально. Для типа voice игнорируется
payload[message][file_size] int Размер данных в байтах поля media, поле опционально
payload[message][contact][name] string Только для типа contact, обязательное поле. Имя контакта.
payload[message][contact][phone] string Только для типа contact, обязательное поле. Телефон контакта
payload[message][location][lat] float Только для типа location, обязательное поле. Широта
payload[message][location][lon] float Только для типа location, обязательное поле. Долгота

Пример запроса

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "event_type": "new_message",
  "payload": {
    "timestamp": 1596470952,
    "msgid": "skm-5f2836a8ca468",
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "sender": {
      "ref_id": "d8d9f9c4-9611-4794-a136-a253a13e1bb5",
      "name": "Менеджер"
    },
    "receiver": {
      "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
      "avatar": "https:/example.com/users/avatar.png",
      "name": "Example Client",
      "profile": {
          "phone": "79151112233",
          "email": "example.client@example.com"
      },
      "profile_link": "http://example.com/profile/example.client"
    }
    "message": {
      "type": "text",
      "text": "Можем обговорить ваши условия дополнительно, если наше предложение вас устраивает"
    },
    "silent": true
  }
}

        
    

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Cообщение принято для обработки
403 Подпись запроса некорректная
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод вернет идентификатор сообщения amojo. Сообщение появится в чате после обработки

Параметр Тип данных Описание
new_message[msgid] string Идентификатор сообщения amojo

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

        
{
  "new_message": {
    "msgid": "1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc"
  }
}