HTTPS интеграция с текстовыми каналами (через API Qolio)

Создание интеграции

Вы можете посмотреть на предварительную настройку организации и создании чата по API в этом видео:

23MB

dealapp-integration-with-chats.mp4

Запрос для создания текстовой коммуникации

После добавления интеграции для текстового канала, вам будет предоставлен:

1. URL путь для создании текстовых коммуникаций. URL путь имеет следующий вид: https://{DEALAPP_API_URL}/api/v1/integrations/{INTEGRATION_ID}/text , где DEALAPP_API_URL адрес установки сервера DealApp, а INTEGRATION_ID сгенерирован сервисом DealApp.

2. Authorization Token, это токен, который должен передаваться в headerах запроса и использоваться для авторизации запроса на URL путь интеграции.

Для регистрации текстовой коммуникации нужно сделать POST запрос следующим образом:

// POST https://api.prod1.dealapp.io/api/v1/integrations/c34f637a-..../text

Зарос должен содержать следующие заголовки (headers): "Content-Type: application/json" и "Authorization: ...". В Authorization заголовке передается значение Authorization Token, которое можно найти на странице настройки интеграции в DealApp.

Вместе с запросом нужно передать JSON документ с данными о текстовой коммуникации. Пример JSON документа для запроса на добавление / обновление объекта текстового взаимодействия:

// {
  "client_id": "375299933332",        // Идентификатор клиента в системе клиента (номер телефона, id или хэш)
  "communication_id": "1911-1498-11",  // Идентификатор текстового взаимодействия
  "communication_type": "chat",        // Тип текстового взаимодействия. Возможные варианты: chat / ticket / email
  "title": "Добрый вечер. Я хочу приобрести холодильник", // Заглавие беседы, если нету - берется из conversation_parts.first.body
  "source": "chat",        // источник чата (telegram, viber и другие)
  "nps": 8,                // Net Promoter Score
  "client_feedback": 1,    // число, отображающее отзыв клиента
  "status": "closed",      // String обозначающий статус (accepted / rejected)
  "direction": "incoming", // incoming / outcoming / local
  "communication_parts": [
    {
      "communication_part_id": "2202737122",
      "author": {
        "type": "client"  // при отсутствии id клиента мы используем client_id из
      },        
      "body": "Добрый вечер. Я хочу приобрести холодильник",
      "created_at": "2020-01-17T08:15:30+03:00"
    },
    {
      "communication_part_id": "2202737122",
      "author": {
        "type": "client"
      },
      "body": "Интересует модель X этого года",
      "created_at": "2020-01-17T08:15:30+03:00",
      "updated_at": "2020-01-17T09:30:28+03:00"
    },
    {
       "communication_part_id": "2202737122",
       "author": {
          "id": "123",       // id оператора (внутренний номер)
          "type": "operator" // возможные значения operator / client
       },
       "body": "Здравствуйте! Спасибо за сообщение, наш отдел продаж обязательно свяжется с вами",
       "content_type": "text/plain",  // text/plain by default, возможные варианты text/html
       "created_at": "2020-01-17T08:15:30+03:00",
       "updated_at": "2020-01-17T08:15:30+03:00"
    }
  ],
  "custom_fields": {
    "reopens_count": 3
  }
}

Описание полей запроса

operator_id	(required) string	Идентификатор оператора, с которым проходил разговор (это могут быть email, SIP номер или ID из ActiveDirectory/LDAP)
uid	string	уникальный внешний идентификатор (который после будет храниться и возвращаться в поле integration_uid)
communication_id	string (chat / ticket / email)	Идентификатор текстового взаимодействия, должен быть уникальным для всех взаимодействий
communication_type	string	Тип текстового взаимодействия. Возможные варианты: chat / ticket / email
title	string	Заглавие беседы, если нету - берется из conversation_parts.first.body
source	string	Поле в котором может храниться название сервиса, через которое проходила текстовая коммуникация (telegram, viber и др.). Возможны любые значения
nps	string	Значение NPS
client_feedback	string	Число, которое ассоциируется с выбором, которое делает клиент для оценки коммуникации
status	string (accepted / rejected / opened / closed)	Статус диалога. String, значения: accepted, rejected, opened, closed
direction	string (incoming / outcoming / local)	Направление коммуникации: incoming / outcoming / local
communication_parts	array	Перечень сообщений в диалоге. Array
communication_parts[].author	string	Описывает с каким пользователем можно связать это сообщение
communication_parts[].author.type	string	Возможные значения client / operator
communication_parts[].author.id	string	id клиента или оператора в зависимости от conversation_parts.author.type. если не указан, используется client_id или operator_id соответственно
communication_parts[].conversation_part_id	string	трекинг ID сообщения в вашей системе
communication_parts[].body	string	Тело сообщения
communication_parts[].content_type	string	Тип содержимого в сообщении (text/plain или text/html), по умолчанию text/plain
communication_parts[].created_at	string	Время создания сообщения
custom_fields (metacontent)	hash (object)	Хэш, в который можно передавать поля, которые не входят в схему запроса
client_id	string	Устаревшая форма передавать id клиента по которому проходит коммуникация
client	hash (object)	Объект с информацией о клиенте, который совершает ком-цию
client.id	string	Идентификатор клиента в системе клиента (номер телефона, id или хэш)
client.company_name	string	Название компании клиента
client.first_name	string	Имя клиента
client.last_name	string	Фамилия клиента
client.email	string	email клиента
client.phone_number	string	номер телефона клиента

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

curl запрос с помощью, которого можно создать чат:

// export INTEGRATION_URL="https://api.prod1.dealapp.io/api/v1/integrations/9e5af994-9d16-4607-8964-86272a452299/text"
export AUTHORIZATION_TOKEN="289a2b91a681031fc576e3c66e155761cef58926a97d201363abd4c3196546318b597a9171aca4ae008be8e7fae5bec6f8de396adec24a"

curl --header "Content-Type: application/json" --request POST --header "Authorization: $AUTHORIZATION_TOKEN" --data @request.json $INTEGRATION_URL