Webim Custom Channel 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": {  
       ...
    }
  },
  "text*": String,
  "action*": String,
  "photo*": String,
  "file*": String,
  "location*": {
      "latitude": Float,
      "longtitude": Float,
      "user_location": Boolean
  },
  "secret": String,
  "channel_id": String
}

* Предполагается, что в зависимости от содержания запроса присутствует один из пяти параметров: text, action, photo, file или location. В принципе, все эти поля могут быть NULL, но в таком случае запрос не несёт в себе никакой информации.

Пример тела запроса (отправка текстового сообщения):

{  
  "from": {  
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "text": "Здравствуйте, чем я могу Вам помочь?",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (набор сообщения посетителем):

{  
  "from": {  
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "action": "user-typing",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (отправка изображения посетителем):

{  
  "from": {  
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "photo": "https://webim.ru/new_agent.jpg",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (отправка файла посетителем):

{  
  "from": {  
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "file": "https://webim.ru/agent_handbook.pdf",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (передача локации посетителя):

{  
  "from": {  
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "location": {
      "latitude": 59.954908,
      "longtitude": 30.294030,
      "user_location": true
  },
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

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

{
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "display_name": "Евгений",
    "phone": "+78123855337",
    "email": "support@webim.ru"
}

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

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

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

{
  "result": "ok"
}

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

{
  "error": "код ошибки"
}

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

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

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

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

{  
   "to":{  
      "id": String
   },
   "text*": String,
   "action*": String,
   "photo*": String,
   "file*": String,
   "secret": String,
   "from": {  
      "name": String,
      "id": Int,
      "email": String
   },
   "channel_id": String
}

* Предполагается, что в зависимости от содержания запроса присутствует один из пяти параметров: text, action, photo или file. В принципе, все эти поля могут быть NULL, но в таком случае запрос не несёт в себе никакой информации.

Пример тела запроса (отправка текстового сообщения оператором):

{  
   "to":{  
      "id": "18445032-9358-4c50-91d7-06fe604b76e3"
   },
   "text": "Сейчас уточню информацию по вашему вопросу.",
   "secret": "960c1a9d118a4b86b2e004c9c12c4150",
   "from": {  
      "name": "Евгений",
      "id": 148465,
      "email": "agent@webim.ru"
   },
   "channel_id": "142a171852f34530b4b66f7b0824812c"
}

Пример тела запроса (набор сообщения оператором):

{  
   "to":{  
      "id": "18445032-9358-4c50-91d7-06fe604b76e3"
   },
   "action": "operator-typing",
   "secret": "960c1a9d118a4b86b2e004c9c12c4150",
   "from": {  
      "name": "Евгений",
      "id": 148465,
      "email": "agent@webim.ru"
   },
   "channel_id": "142a171852f34530b4b66f7b0824812c"
}

Пример тела запроса (отправка изображения оператором):

{  
   "to":{  
      "id": "18445032-9358-4c50-91d7-06fe604b76e3"
   },
   "photo": "https://webim.ru/img1234.png",
   "secret": "960c1a9d118a4b86b2e004c9c12c4150",
   "from": {  
      "name": "Евгений",
      "id": 148465,
      "email": "agent@webim.ru"
   },
   "channel_id": "142a171852f34530b4b66f7b0824812c"
}

Пример тела запроса (отправка файла оператором):

{  
   "to":{  
      "id": "18445032-9358-4c50-91d7-06fe604b76e3"
   },
   "file": "https://webim.ru/agent_handbook.pdf",
   "secret": "960c1a9d118a4b86b2e004c9c12c4150",
   "from": {  
      "name": "Евгений",
      "id": 148465,
      "email": "agent@webim.ru"
   },
   "channel_id": "142a171852f34530b4b66f7b0824812c"
}

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

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

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

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