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

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

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

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

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

  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

Last updated