API для универсального канала

Описание

Помимо специально разработанных каналов общения, наш сервис также может интегрироваться через универсальный (произвольный) канал с любой системой для передачи сообщений. Это может быть мессенджер (глобальный или Ваш собственный), коммуникатор, чат в социальной сети, SMS и т. д. Данный API позволяет реализовать интеграцию, когда Webim является главным центром маршрутизации, распределения и обработки обращений, а интегрируемая через него вторая система производит первичную обработку обращения и затем передает его Webim среди множества других каналов, подключённых к нам. Требуется лишь, чтобы систему можно было научить передавать нам сообщения на указанный URL в указанном формате и принимать аналогичные сообщения от нас. Так, если Вы представляете крупный банк и у Вас есть другой чат-сервис, Вы можете передавать обращения нам с помощью универсального канала API. Если же ядром маршрутизации и распределения обращений является как раз вторая система, то стоит обратиться к нашим менеджерам, чтобы подыскать решение, подходящее именно Вам.

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

Сам канал настраивается в следующем месте интерфейса: Общие настройки —> Каналы общения —> Произвольный (последний в списке). Здесь нужно задать следующие настройки:

  • Название канала, которое будут видеть операторы.
  • Если у Вас несколько отделов — тот, в который будут поступать обращения через канал.
  • Ваш секретный ключ для шифрования передаваемых данных (Вы придумываете эту строку; она может содержать любые символы).
  • Адрес сервера (Callback URL) — зависит от Вашего канала. Сервер Webim будет отсылать все изменения (новые сообщения от оператора) в заданном формате на этот адрес.

Что же касается нашего секретного ключа и идентификатора канала, то Вам нужно будет передавать их в полях Ваших запросов (см. ниже).

Метод /l/ch

Данный метод даёт доступ к серверу Webim через универсальный канал по URL, который используется внешним сервисом и является конечной точкой канала связи со стороны посетителя. Метод отправляет запросы на сервер Webim при осуществления действий посетителем: при наборе текста, отправке сообщений, файлов и т.д.

Base URL: https://<account-domain>
Итоговый URL: https://<account-domain>/l/ch

Тип запроса: POST
Query-string параметры: не нужны

Content-Type: application/json
Формат тела запроса: JSON
Авторизация: как таковой нет (только через секретный ключ)

Запросы к серверу Webim

В теле запроса должен находиться JSON вида:

{  
  "from": {  
    "id": String,
    "fields": {  
       ...
    }
  },
  type: content,
  "secret": String,
  "channel_id": String
}

Описание параметров

Название параметра Тип Пример Описание
from:id String "c906c924-0727-47e8-8dd0-864f00a24eb6" Канальный идентификатор пользователя.
from:fields Object {
id: "c906c924-0727-47e8-8dd0-864f00a24eb6",
display_name: "Евгений",
phone: "+78123855337",
email: "support@webim.ru"
}
Опциональный параметр. Список поддерживаемых полей можно найти здесь.

Все значения полей должны быть типа String, все поля — опциональные.

action String "user-typing" Описывает действия.
location String "platform" Описывает размещение, если есть.
type String "text" Зависит от типа сообщения:

  • action — для действий, доступно user-typing (пользователь печатает)
  • text — для обычных сообщений: любая строка, в каком виде она написана, так её оператор и получит
  • photo — для фотографий: URL в формате https://somedomain.com/filename.jpg
  • file — для всех остальных файлов: URL в формате https://somedomain.com/filename.doc
content String "Пример сообщения" Содержимое запроса.
secret String "75f4z6pkg2rn42c73149" Сгенерированный на стороне Webim секретный ключ, виден в настройках канала.
channel_id String "4c6bbmm133b513061fru" ID канала, генерируется на стороне Webim, виден в настройках канала.

Возможные ответы

Если неверен секретный ключ, то сервер отдаст код состояния 403.

Если никаких проблем не возникло, сервер отдаст JSON вида:

{
  "result": "ok"
}

Если возникли проблемы, сервер отдаст JSON вида:

{
  "error": "код ошибки"
}
Код ошибки Значение
"wrong-content-type" Неправильный Content-Type.
"channel-not-found" У аккаунта отсутствуют каналы или канал с заданным ID не найден.
"wrong-file-type" Неправильный формат файла, возникает при попытке отправить файл с запрещённым расширением.

Запросы от Webim на Callback URL

Сервер Webim шлёт POST запрос на указанный в настройках Callback URL.
Запросы могут отправляться при совершении действий операторами и при других событиях на стороне Webim:

  • создание чата;
  • назначение оператора;
  • отправка сообщения оператором;
  • отправка файлов оператором;
  • набор текста оператором;
  • снятие оператора с чата;
  • завершение чата;
  • запрос оценки оператора.

В теле запроса находится JSON вида:

{  
   "to":{  
      "id": String
   },
   type: content,
   "secret": String,
   "from": {  
      "name": String,
      "id": Int,
      "email": String
   },
   "channel_id": String
}

Описание параметров

Название параметра Тип Пример Описание
to:id String "18445032-9358-4c50-91d7-06fe604b76e3" Канальный идентификатор пользователя.
type String "text" Зависит от типа сообщения:

  • action — operator-typing (оператор печатает)
  • text — любая строка
  • file, photo — URL в нашем стандартном формате
action String "operator-typing" Описывает действия.
location String "platform" Описывает размещение, если есть.
content String "Пример сообщения" Содержимое запроса.
secret String "justakey" Секретный ключ клиента, задаётся в настройках канала.
from:name String "Иван Петров" Имя оператора.
from:id Int 148465 ID оператора в системе Webim. Определить его можно двумя путями:

  • Запросить список операторов через API.
  • Открыть профиль этого оператора и скопировать его id в системе — число в конце URL-адреса открытой страницы. К примеру, если профиль оператора находится по адресу https://test.webim.ru/operator/operator.php?operatorid=123456, то нужно взять именно число 123456.
from:email String "operator@mail.ru" Электронная почта оператора.
channel_id String "4c6bbmm133b513061fru" ID канала, генерируется на стороне Webim, виден в настройках канала.

Остальные параметры аналогичны входящим запросам.

Возможные ответы

Сервер Webim ожидает получить в ответ 200 OK, все остальные коды считаются ошибкой.

Примеры запросов к серверу Webim

  1. Запрос для отправки простого сообщения, без дополнительных полей в запросе. В данном примере оператору покажется простое текстовое сообщение "Hello". Поскольку имя клиента не указано в fields, то будет использоваться имя посетителя по умолчанию.
    {
      "from": {
        "id": "userid"
      },
      "text": "Hello",
      "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  2. Запрос для отправки простого сообщения, с дополнительными полями посетителя в запросе. В данном примере оператору покажется простое текстовое сообщение "Hello". Поскольку имя клиента указано в fields, то посетителю будет установлено имя "Иван", также проставится его email.
    {
      "from": {
        "id": "userid",
        "fields": {
            "name": "Иван",
            "email": "email@example.com"
        }
      },
      "text": "Hello with email.",
      "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  3. Запрос для отправки изображения. Webim скачает файл по указанной ссылке, проверит его и передаст его оператору в чат.
    {
      "from": {
        "id": "userid"
      },
      "photo": "https://cuu.su/m12/",
      "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  4. Запрос для отправки файла. Аналогично отправке изображения.
    {
      "from": {
        "id": "userid"
      },
      "file": "https://cuu.su/m12/",
      "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  5. Запрос для действия пользователя.
    {
      "from": {
        "id": "userid"
      },
      "action": "user-typing",
      "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    

Примеры запросов от Webim на Callback URL

  1. Запрос с простым сообщением.
    {  
      "to": {  
        "id": "userid"
      },
      "text": "Hello from operator.",
      "secret": "5fb4f4401b0f4cc0b442ffd0915feb79",
      "from": {  
        "name": "operatorname",
        "id": 1,
        "email": "operator@webim.ru"
      },
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  2. Запрос с изображением.
    {  
      "to": {  
        "id": "userid"
      },
      "photo": "https://cuu.su/m12/",
      "secret": 5fb4f4401b0f4cc0b442ffd0915feb79,
      "from": {  
        "name": "operatorname",
        "id": 1,
        "email": "operator@webim.ru"
      },
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  3. Запрос с файлом.
    {  
      "to": {  
        "id": "userid"
      },
      "file": "https://webim.ru/l/v/download/159f6150b78843209f867d/file.doc",
      "secret": 5fb4f4401b0f4cc0b442ffd0915feb79,
      "from": {  
        "name": "operatorname",
        "id": 1,
        "email": "operator@webim.ru"
      },
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }
    
  4. Запрос с действием оператора.
    {  
      "to": {  
        "id": "userid"
      },
      "action": "operator-typing",
      "secret": 5fb4f4401b0f4cc0b442ffd0915feb79,
      "from": {  
        "name": "operatorname",
        "id": 1,
        "email": "operator@webim.ru"
      },
      "channel_id": "142a171852f34530b4b66f7b0824812c"
    }