Если у вас еще нет amoCRM
Создать прямо сейчасВ данном разделе собраны все методы для работы с API чатов amoCRM.
Все запросы АПИ чатов необходимо производить на домен amojo.amocrm.ru или amojo.amocrm.com для аккаунтов в домене *.amocrm.com
Авторизация в АПИ чатов отличается от основного АПИ аккаунта amoCRM.
Для авторизации в каждом запросе необходимо передавать указанные ниже заголовки
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
Код ответа | Условие |
---|---|
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": "ChatIntegration",
"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
Код ответа | Условие |
---|---|
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
Код ответа | Условие |
---|---|
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 и они добавятся в режиме импорта, в последнем сообщении указать 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 | string | amojo_id аккаунта |
payload[timestamp] | int | Время сообщения, метка unix |
payload[msec_timestamp] | int | Время сообщения в миллисекундах |
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,
"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
Код ответа | Условие |
---|---|
200 | Cообщение принято для обработки |
403 | Подпись запроса некорректная |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод вернет идентификатор сообщения amojo. Сообщение появится в чате после обработки
Параметр | Тип данных | Описание |
---|---|---|
new_message[msgid] | string | Идентификатор сообщения amojo |
{
"new_message": {
"msgid": "1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc"
}
}
GET /v2/origin/custom/{scope_id}/chats/{chat_id}/history
Метод позволяет получить переписку по чату. Сортировка начиная с последних по дате
Требуется корректная подпись запроса в заголовке X-Signature
Параметр | Тип данных | Описание |
---|---|---|
limit | int | Число сообщений выводимых за 1 запрос. (50 по умолчанию, макс. 200) |
offset | int | Оффсет выборки сообщений |
Content-Type: application/json
Content-Type: application/json
Код ответа | Условие |
---|---|
200 | Запрос содержит список сообщений чата |
404 | Чат не найден |
403 | Подпись запроса некорректная |
400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Метод вернет переданные поля запроса, и scope_id который понадобится для работы сообщениями
Параметр | Тип данных | Описание |
---|---|---|
timestamp | int | Время сообщения, метка unix |
msec_timestamp | int | Время сообщения, в миллисекундах |
messages[0][receiver][id] | string | Идентификатор участника чата amojo |
messages[0][receiver][client_id] | string | Идентификатор участника чата на стороне интеграции, для пользователей amocrm поле отсутствует |
messages[0][receiver][name] | string | Имя участника чата |
messages[0][receiver][avatar] | string | Url на аватарку, если была передана, или пустое поле |
messages[0][receiver][phone] | string | Поле отсутствует, если не передавался профиль |
messages[0][receiver][email] | string | Поле отсутствует, если не передавался профиль |
messages[1][sender][id] | string | Идентификатор участника чата amojo |
messages[1][sender][client_id] | string | Идентификатор участника чата на стороне интеграции, для пользователей amocrm поле отсутствует |
messages[1][sender][name] | string | Имя участника чата |
messages[1][sender][avatar] | string | Url на аватарку, если была передана, или пустое поле |
messages[1][sender][phone] | string | Поле отсутствует, если не передавался профиль |
messages[1][sender][email] | string | Поле отсутствует, если не передавался профиль |
messages[0][message][id] | string | Идентификатор сообщения amojo |
messages[0][message][type] | string | Тип сообщений, может быть одним из списка: text,file,video,picture,voice,audio,sticker |
messages[0][message][text] | string | Для типа text обязательно, для других типов сообщений может быть пустым |
messages[0][message][media] | string | Url на картинку,файл,видео,аудио,голос,стикер. |
messages[0][message][thumbnail] | string | Поле содержит url на предпросмотр, актуально только для типа picture,video |
messages[0][message][file_name] | string | Название файла для url в поле media |
messages[0][message][file_size] | int | Размер данных в байтах поля media |
messages[0][message][client_id] | string | Идентификатор сообщения чата на стороне интеграции, для сообщений, отправленных из amocrm поле отсутствует |
messages[0][message][contact][name] | string | Только для типа contact. Имя контакта. |
messages[0][message][contact][phone] | string | Только для типа contact. Телефон контакта |
messages[0][message][location][lat] | float | Только для типа location. Широта |
messages[0][message][location][lon] | float | Только для типа location. Долгота |
{
"messages": [
{
"timestamp": 1596470953,
"msec_timestamp": 1596470953116,
"sender": {
"id": "d8d9f9c4-9611-4794-a136-a253a13e1bb5",
"name": "Менеджер",
"avatar": "https://www.amocrm.ru/version2/images/d8d9f9c4-9611-4794-a136-a253a13e1bb5.png"
},
"receiver": {
"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"
},
"message": {
"id": "3985523d-78b3-45b7-aeaf-142405bbf1dc",
"client_id": "skm-5f2836a8ca468",
"type": "text",
"text": "Конечно, можете уточнить номер заказа ?",
"media": "",
"thumbnail": "",
"file_name": "",
"file_size": 0
}
},
{
"timestamp": 1596470809,
"msec_timestamp": 1596470809001,
"sender": {
"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"
},
"message": {
"id": "1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc",
"client_id": "5f283618af2c8",
"type": "text",
"text": "Можно ли получить скидку при оплате всего заказа сразу ?",
"media": "",
"thumbnail": "",
"file_name": "",
"file_size": 0
}
}
]
}