Webim Custom Channel API

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

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

Обычно диалог начинает посетитель, у которого возник вопрос. Однако при определённых обстоятельствах оператор может сам инициировать диалог. В частности, это возможно, если до этого оператор уже общался с посетителем. В таком случае, если предыдущий чат был закрыт, диалог отобразится среди прочих в Истории диалогов. Найдя диалог в списке, оператор сможет начать новый чат, воспользовавшись кнопкой Начать чат.

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

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

Метод для оповещения сервера Webim об осуществлении действий со стороны посетителя: при наборе текста, отправке сообщений, файлов и т. д.

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

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

Content-Type: application/json
Формат тела запроса: 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.

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

В теле запроса находится объект данных в формате 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, все остальные коды считаются ошибкой.

1. Запрос для отправки простого сообщения, без дополнительных полей в запросе. В данном примере оператору покажется простое текстовое сообщение "Hello". Поскольку имя клиента не указано в fields, то будет использоваться имя посетителя по умолчанию.

       {
         "from": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "text": "Hello",
         "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

2. Запрос для отправки простого сообщения, с дополнительными полями посетителя в запросе. В данном примере оператору покажется простое текстовое сообщение "Hello". Поскольку имя клиента указано в fields, то посетителю будет установлено имя "Иван", также проставится его email.

       {
         "from": {
           "id": "c906c924072747e88dd0864f00a24eb6",
           "fields": {
               "name": "Иван",
               "email": "ivan.n@webim.com"
           }
         },
         "text": "Hello with email.",
         "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

3. Запрос для отправки изображения. Webim скачает файл по указанной ссылке, проверит его и передаст его оператору в чат.

       {
         "from": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "photo": "https://cuu.su/m12.jpg",
         "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

4. Запрос для отправки файла. Аналогично отправке изображения.

       {
         "from": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "file": "https://cuu.su/agreement.doc",
         "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

5. Запрос для действия пользователя.

       {
         "from": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "action": "user-typing",
         "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

1. Запрос с простым сообщением.

       {
         "to": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "text": "Hello from operator.",
         "secret": "5fb4f4401b0f4cc0b442ffd0915feb79",
         "from": {
           "name": "Ivan N.",
           "id": 125654,
           "email": "ivan.n@webim.ru"
         },
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

2. Запрос с изображением.

       {
         "to": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "photo": "https://webim.ru/wp-content/uploads/2020/03/image.jpg",
         "secret": "5fb4f4401b0f4cc0b442ffd0915feb79",
         "from": {
           "name": "Ivan N",
           "id": 125478,
           "email": "ivan.n@webim.ru"
         },
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

3. Запрос с файлом.

       {
         "to": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "file": "https://webim.ru/l/v/download/159f6150b78843209f867d/file.doc",
         "secret": "5fb4f4401b0f4cc0b442ffd0915feb79",
         "from": {
           "name": "Ivan N.",
           "id": 126587,
           "email": "ivan.n@webim.ru"
         },
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }
       

4. Запрос с действием оператора.

       {
         "to": {
           "id": "c906c924072747e88dd0864f00a24eb6"
         },
         "action": "operator-typing",
         "value": True,
         "secret": "5fb4f4401b0f4cc0b442ffd0915feb79",
         "from": {
           "name": "Ivan N.",
           "id": 125458,
           "email": "ivan.n@webim.ru"
         },
         "channel_id": "142a171852f34530b4b66f7b0824812c"
       }