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

Вы получили от нас параметры доступа. Самое время подключить ваш аккаунт к новому каналу.

Для этого нам потребуется:

  • Идентификатор аккаунта amoCRM для сервиса online чатов. Как его получить подробно описано ниже
  • Идентификатор канала и секрет, который вы получили в ответном письме от технической поддержки amoCRM

Формируем POST запрос, в котором указываем идентификатор аккаунта для подключения к нашему каналу.

Подписываем запрос с помощью секрета и добавляем подпись в заголовок X-Signature

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

    POST https://amojo.amocrm.ru/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41/connect
    Date: Mon, 03 Oct 2020 15:11:21 +0000
    Content-Type: application/json
    Content-MD5: a5e8ae04332a6d0aac15f01ad05d40e3
    X-Signature: 85d94e7f21bdd3971c2721ca22793e45a96d0c75

Ответ

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

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

Вы можете отправлять сообщения следующих типов: текст, изображение, файл, локация, контакт.

Очень подробно формат данных запроса описана в разделе API Отправка сообщения

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

  • Scope id, который мы получили при подключении аккаунта к каналу
  • Секрет канала для формирования подписи

Рассмотрим несколько примеров:

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

    POST https://amojo.amocrm.ru/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec
    Date: Mon, 03 Oct 2020 16:06:48 +0000
    Content-Type: application/json
    Content-MD5: 204dc99bcaa899db72954f16de987022
    X-Signature: 6201ab8b5154bfa2af847920f1dfeab74b125489
    {
      "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
      "event_type": "new_message",
      "payload": {
        "timestamp": 1596470808,
        "msgid": "5f283618af2c8",
        "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
        "sender": {
          "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": "https://example.com/profile/example.client"
        },
        "message": {
          "type": "text",
          "text": "Приветствую, хотел бы уточнить пару вопросов по артикулу A13435"
        },
        "silent": true
      }
    }

Ответ

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

В интерфейс amoCRM моментально приходит новый запрос (карточка неразобранного)

Центр нотификаций

Интерфейс воронки

Карточка неразобранного

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

Ответ клиенту

Теперь чат выглядит так

Получение ответа на URL обратного вызова

Как только пользователь amoCRM ответил клиенту, на URL обратного вызова должен прийти POST запрос с данными сообщения.

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

Webhook в формате JSON

    {
      "receiver" : "U1" ,
      "conversation_id" : "c59678affa1db6" ,
      "type" : "text" ,
      "text" : "Привет,  Джон! Для Вас - Бесплатно! Но... есть нюансы." ,
      "media" : "" ,
      "thumbnail" : "" ,
      "file_name" : "" ,
      "file_size" : 0
    }

Разработка виджета

Вы можете предоставить другим пользователям amoCRM возможность подлючить ваш канал к своему аккаунту. Для этого необходимо разработать виджет, с помощью которого пользователь сможет связать свой аккаунт с вашим каналом.

Подробнее о разработке виджета вы можете прочитать в документации по виджетам

Дополнительные требования к виджету

В manifest.json, в объект locations добавить параметр “lead_sources”. После чего ваш виджет отобразится в разделе настройки чатов

  1. Пользователь активирует окно подключения виджета
  2. Вводит логин / пароль от учетной записи вашего сервиса
  3. Отправляет на ваш сервер связку логин/пароль и id своего аккаунта. id аккаунта может быть получен виджетом автоматически через следующий JS скрипт: AMOCRM.constant(‘account’).amojo_id
  4. Ваш сервер валидирует учетные данные и вызывает запрос на подключение нового аккаунта к каналу чатов.

Пример виджета

Скачать

Написать первым

Интерфейс amoCRM позволяет инициировать переписку с клиентом из карточки. Для этого достаточно создать карточку и добавить в нее контакт с номером телефона.

Если ваш канал поддерживает функцию “написать первым”, то он отобразится в выпадающем списке Click-To-Call (см. Регистрация нового канала)

Пользователь выбирает ваш виджет и отправляет сообщение.

 

На URL обратного вызова уйдет Webhook формата 2.0 (см. Webhook 2.0), в котором передаются
идентификаторы чата, получателя и сообщения со стороны amoCRM).

Ваш сервер интеграции должен обработать запрос, и попытаться отправить сообщение получателю. По факту отправки или
невозможности отправить сообщение, интеграция должна отправить запрос в amoCRM на изменение статуса сообщения. (см.
Статус доставки)

Когда клиент ответит на сообщение, в дополнение к стандартным параметрам запроса на отправку сообщения, нужно передать conversation_ref_id и sender.ref_id, полученные ранее из Webhook 2. , чтобы amoCRM связала чат и получателя на своей стороне с вашими. (см. Отправка сообщения)