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

Оглавление

• Общие требования
• Авторизация
• Подключение канала чата в аккаунте
• Отключение канала чата в аккаунте
• Создание нового чата
• Отправка или импорт сообщения
• Создание нового чата

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

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

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

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

Метод

GET /v2/origin/custom/{scope_id}/chats/{chat_id}/history

Описание

Метод позволяет получить переписку по чату. Сортировка начиная с последних по дате

Ограничения

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

GET параметры

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

Content-Type: application/json

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

Content-Type: application/json

HTTP коды ответа

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

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

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

        
{
  "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
      }
    }
  ]
}