В данном разделе собраны все методы для работы с 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": "af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "ChatIntegration",
  "hook_api_version": "v2"
}

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

Content-Type: application/json

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

Content-Type: application/json

HTTP коды ответа

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

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

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

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

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

Метод

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

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

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

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

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

Content-Type: application/json

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

Content-Type: application/json

HTTP коды ответа

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

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

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

Метод

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

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

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

{
    "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 коды ответа

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

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

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

{
  "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 и они добавятся в режиме импорта, в последнем сообщении указать silent: false, таким образом
у пользователя amoCRM будет только одна нотификация, без лишних беспокойств.

Если интеграция самостоятельно отправляет сообщения клиенту (не от имени менеджера amoCRM, а бота) бота интеграции, то такие сообщения также можно проимпортировать в
amoCRM. Для этого необходимо указать id бота в качестве отправителя. Для каждого канала при регистрации автоматически создается пользователь – бот, который будет отображаться в переписке с именем канала.
Если у вас уже есть канал, но id бота нет, то вы можете узнать его в технической поддержке.

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

Ограничения

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

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

Content-Type: application/json

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

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

• от клиента всем участникам чата (заполняется только поле sender)
  
• от пользователя аккаунта amoCRM клиенту (заполняются поля sender и receiver, заполняется поле sender[ref_id])
  
• от бота интеграции клиенту (заполняются поля sender и receiver, заполняется поле sender[ref_id])

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

{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "event_type": "new_message",
  "payload": {
    "timestamp": 1596470952,
    "msec_timestamp": 1596470952116,
    "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 коды ответа

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

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

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

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