Если у вас еще нет amoCRM
Создать прямо сейчасВсе запросы включают заголовок 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
Обновлено 20.11.2019
Перед использованием этого метода ознакомьтесь:
Чтобы подключить аккаунт к каналу чатов, вам необходимо выполнить POST запрос, передав в теле запрос id подключаемого аккаунта. В ответ вы получите уникальный scope_id аккаунта для этого канала, который будет использоваться в дальнейшем при публикации сообщений.
POST /v2/origin/custom/ <уникальный id канала>/connect
Host: amojo.amocrm.ru
X-Signature: ‹hmac›
Content-Type: application/json
Параметр | Тип | Описание |
---|---|---|
account_id | string | UUID, Уникальный идентификатор аккаунта для работы с сервисом онлайн-чатов. |
title
Обновлено 20.11.2019 |
string | Название скопа. Например, номер WhatsApp. P.S в дальнейшем будет разрешено добавлять несколько скопов, например, если у пользователя несколько номеров WhatsApp. |
hook_api_version
Обновлено 20.11.2019 |
string | Версия Webhook, который будет отправлен при наступлении события в этом скопе. По умолчанию v1. Доступные значения: v1, v2 |
<?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,
'title' => '+79151112211',
'hook_api_version' => 'v2'
]);
// Формируем подпись
$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 аккаунта для вашего канала |
title
Обновлено 20.11.2019 |
string | Название скопа |
hook_api_version
Обновлено 20.11.2019 |
string | Версия Webhook |
{
"account_id": "13fa84f7-6b61-4086-98ed-0a9de19ee15c",
"scope_id": "a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c",
"title": "+79151112233",
"hook_api_version": "v2"
}
Если вы хотите, чтобы аккаунт больше не получал сообщения из вашего канала, вы можете отключить его.
Перед использованием этого метода ознакомьтесь:
Чтобы отключить аккаунт от канала чатов, вам необходимо выполнить DELETE запрос, передав в теле запрос id отключаемого аккаунта. В ответ вы получите 200 ОК
DELETE /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' => $account_id
]);
// Формируем подпись
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL =&gt; "https://amojo.amocrm.ru/v2/origin/custom/{$channel_id}/disconnect",
CURLOPT_RETURNTRANSFER =&gt; true,
CURLOPT_TIMEOUT =&gt; 30,
CURLOPT_HTTP_VERSION =&gt; CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST =&gt; "DELETE",
CURLOPT_POSTFIELDS =&gt; $body,
CURLOPT_HTTPHEADER =&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
Обновлено 20.11.2019
Перед использованием этого метода ознакомьтесь:
POST /v2/origin/custom/score id
Host: amojo.amocrm.ru
X-Signature: ‹hmac›
Content-Type: application/json
Параметр | Тип | Описание |
---|---|---|
event_type | string | Тип события. Доступны: new_message |
payload | object | Детальная информация |
Обновлено 20.11.2019
Параметр | Тип | Описание |
---|---|---|
timestamp require |
int | Время создания сообщения, unix |
msgid require |
string | Уникальный идентификатор сообщения |
conversation_id require |
string | Уникальный идентификатор переписки |
conversation_ref_id
Обновлено 20.11.2019 |
uuid | Идентификатор чата на стороне amoCRM. Используется чтобы связать чат на стороне интеграции с чатом amoCRM при первом сообщении, чтобы продолжить переписку. (см. Написать первым) |
sender require |
object | Отправитель |
message require |
object | Сообщение |
silent | bool | Флаг silent указывает, будет ли сообщение помечено как новое. Если указано true – вызова нотификации не произойдет, удобно при импорте сообщений |
Параметр | Тип | Описание |
---|---|---|
id require |
string | Уникальный идентификатор отправителя |
ref_id
Обновлено 20.11.2019 |
uuid | Идентификатор отправителя на стороне amoCRM. Используется чтобы связать получателя на стороне интеграции с профилем контакта amoCRM при первом сообщении, чтобы продолжить переписку. (см. Написать первым) |
avatar require |
string | URL на аватар. Ссылка должна быть доступна серверам amoCRM |
name require |
string | Имя отправителя |
profile_link | Строка | Внешняя публичная ссылка на профиль пользователя, если поддерживается |
profile | object | Дополнительная информация о клиенте |
Параметр | Тип | Описание |
---|---|---|
phone | string | Телефон, если есть информация. Будет добавлен в соц. профиль контакта |
string, Email | Email, если есть информация. Будет добавлен в соц. профиль контакта |
Параметр | Тип | Описание |
---|---|---|
type require | string | Тип сообщения. Доступны: text, picture, video, file, sticker, contact, location |
text | string | Текст сообщения. |
media | string |
Ссылка на файл. Должна быть доступна серверам amoCRM. Обязателен для типов:
|
location | object | Информация о местоположении. Обязательно для location |
contact | object | Информация по контакту. Обязательно для contact. |
file_name | string |
Название файла. Обязательно для типов:
|
file_size | int, байты |
Размер файла. Обязательно для типов:
|
Параметр | Тип | Описание |
---|---|---|
lon | float | Долгота |
lat | float | Широта |
Параметр | Тип | Описание |
---|---|---|
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;
}
Для импорта истории сообщений вам необходимо отправить все сообщения в 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.
На URL обратного вызова, который вы указали при регистрации канала, будут приходить новые сообщения из интерфейса amoCRM.
Каждый такой запрос содержит JSON объект, описывающий структуру сообщения и заголовок X-Signature, содержащий подпись полезных данных запроса.
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;
}
Новое 20.11.2019
На URL обратного вызова 2.0, который вы указали при регистрации канала, будут приходить новые сообщения из интерфейса amoCRM.
Каждый такой запрос содержит JSON объект, описывающий структуру сообщения и заголовок X-Signature, содержащий подпись полезных данных запроса.
POST <Your webhook url>
X-Signature: ‹hmac›
Content-Type: application/json
Параметр | Тип | Описание |
---|---|---|
account_id | string,uuid | идентификатор аккаунта на стороне amoCRM, в котором произошло событие |
time | int, timestamp | Время отправки хука |
message | MessageEvent | Событие нового сообщения |
Параметр | Тип | Описание |
---|---|---|
receiver | Receiver | Структура получателя |
conversation | Conversation | Структура переписки |
timestamp | int, timestamp | Время написания сообщения |
message | Message | Структура сообщения |
Параметр | Тип | Описание |
---|---|---|
id | string, uuid | Идентификатор получателя на стороне amoCRM |
phone | string | Номер телефона получателя |
client_id | string | Ваш идентификатор получателя. Пустой, если переписка инициирована со стороны amoCRM. |
Параметр | Тип | Описание |
---|---|---|
id | string, uuid | Идентификатор переписки на стороне amoCRM |
client_id | string | Ваш идентификатор переписки. Пустой, если переписка инициирована со стороны amoCRM. |
Параметр | Тип | Описание |
---|---|---|
id | string,uuid | id сообщения на стороне amoCRM |
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 |
Новое 20.11.2019
Для обновления статуса доставки сообщения, необходимо отправить POST запрос на сервер amoCRM.
POST /v2/origin/custom/<scope_id>/<msgid>/delivery_status
X-Signature: ‹hmac›
Content-Type: application/json
Параметр | Тип | Описание |
---|---|---|
msgid | string, uuid | Идентификатор сообщения. Должно совпадать с msgid в URL |
delivery_status | int | Статус доставки. 1 – Доставлено. 2 – Прочитано. –1 – Ошибка |
error_сode | int | Тип ошибки. 901 – Пользователь удалил переписку. 902 – Интеграци отключена на стороне канала. 903 – Внутрення ошибка сервера. 904 – Невозможно создать переписку. Например, пользователь не зарегистрирован в WhatsApp. 905 – Любая другая, видимая пользователю (будет отображаться текст из error |
error | string | Текст ошибки. Будет отображаться пользователю. |
<?php
/*
Подключение аккаунта amoCRM к новому каналу online чатов
*/
// Секрет нашего канала, для формирования подписи
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID нашего канала
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Идентификатор аккаунта для сервиса online чатов
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Scope id для публикации сообщений в аккаунт
$scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Идентификатор сообщения, которому будем менять статус
$message_id = 'fbd27636-0c4b-11ea-8d71-362b9e155667';
// Тело запроса
$body = json_encode([
'msgid' => $message_id,
'delivery_status' => -1,
'error_code' => 902
]);
// Формируем подпись
$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}/{$message_id}/delivery_status",
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;
}
200 OK