# Webim Custom Channel API

**Webim Custom Channel API** связывает **Webim** с Вашей системой обмена сообщениями. Система передаёт сообщения посетителя на `POST /l/ch` и принимает события **Webim** на адрес сервера канала.

Канал создаётся по [инструкции «Кастомный канал»](https://webim.ru/kb/11.0/channels/other-channels/custom.html). В запросах к **Webim** передаются **Идентификатор канала** и **Наш секретный ключ**. В запросах **Webim** на Ваш сервер передаётся **Ваш секретный ключ**.

## Запрос посетителя

**Webim** принимает сообщения посетителя методом `POST` на `https://<домен-аккаунта>/l/ch`. Параметры в query string не используются.

Заголовок `Content-Type` должен быть равен строке `application/json`, без параметров. Проверка выполняется до разбора тела. Значение `application/json; charset=utf-8` и любой другой тип получают ответ `wrong-content-type`.

### Состав тела

В теле — один JSON-объект. Обязательны `from`, `secret` и `channel_id`.

Ровно одно из полей `text`, `action`, `photo`, `file`, `location` должно быть передано и не быть `null`. Два таких поля в одном запросе, пустая строка и отсутствие всех пяти полей не проходят проверку.

`is_voice` к этому списку не относится. Значение `true` допустимо только вместе с `file`. Значения `false` и `null` без `file` по этому условию запрос не отклоняют.

### Параметры

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `from.id` | Строка, до 64 символов | Да | Идентификатор посетителя на стороне Вашего канала. **Webim** хранит его как идентификатор посетителя в канале. |
| `from.fields` | Объект | Нет | Дополнительные данные посетителя. Состав — в таблице ниже. Объект можно не передавать. |
| `text` | Непустая строка | Одно из пяти | Текст сообщения. Пробелы по краям удаляются. Ограничения длины у этого поля нет. Текст может быть обработан как ответ на опрос или как выбор отдела, а не как отдельное сообщение оператору. |
| `action` | Непустая строка | Одно из пяти | Событие посетителя. Обрабатывается значение `user-typing`. |
| `photo` | URL | Одно из пяти | Адрес изображения. **Webim** скачивает файл по этому адресу. |
| `file` | URL | Одно из пяти | Адрес файла, который не передаётся как изображение. |
| `is_voice` | Логическое значение | Нет | `true` помечает `file` как голосовое сообщение. Запрос отклоняется, только если `is_voice` истинно, а `file` нет. `false` и `null` без `file` по этому условию не отклоняются. Без поля и при `null` рядом с `file` файл обычный. |
| `location.latitude` | Число | Да, если есть `location` | Широта. Сообщение с геолокацией создаётся при значении от −90 до 90. |
| `location.longitude` | Число | Да, если есть `location` | Долгота. Сообщение с геолокацией создаётся при значении от −180 до 180. |
| `location.user_location` | Логическое значение | Да, если есть `location` | Признак того, что координаты принадлежат самому посетителю. Поле обязательно для проверки запроса и в текст геолокации не входит. |
| `secret` | Непустая строка, до 64 символов | Да | **Наш секретный ключ** из формы канала. |
| `channel_id` | Строка, до 36 символов | Да | **Идентификатор канала**. Это UUID канала. |

`channel_id` длиннее 36 символов не проходит проверку тела. Строка подходящей длины, которая не является UUID, и неизвестный канал дают `channel-not-found`. В запросах **Webim** к Вашему серверу идентификатор приходит в каноническом виде с дефисами. На входе принимается и такая форма, и 32 шестнадцатеричных символа без дефисов.

### Поля посетителя

`from.fields` читает только перечисленные ключи. Остальные ключи, включая прежнее поле `name`, не вызывают ошибку и не используются. Имя посетителя задаёт `display_name`.

| Ключ | Описание |
| --- | --- |
| `display_name` | Имя посетителя в диалоге. Если в первом сообщении ключа нет, **Webim** подставляет имя посетителя по умолчанию. |
| `phone` | Телефон. Строка без отдельной проверки формата. |
| `email` | Адрес электронной почты. Неверный адрес отклоняет весь запрос. |
| `id` | Непустая строка до 64 символов. Сохраняется как поле `id` в данных посетителя, переданных каналом. По непустому значению **Webim** считает посетителя авторизованным. |
| `client_side_session_id` | Строка до 64 символов. Сохраняется в данных посетителя. Другого действия в этом API у ключа нет. |

Значения — строки. `null` у отдельного ключа проходит проверку. `display_name: null` сбрасывает текущее имя; если после этого пусты и имя посетителя, и его имя в канале, **Webim** записывает имя посетителя по умолчанию. Сам объект `from.fields` при отсутствии не передавайте как `null`: опустите поле.

### Набор текста посетителем

`action` со значением `user-typing` сообщает, что посетитель набирает сообщение. Другие значения `action` не обрабатываются как отдельные события.

При включённой настройке [`TRACK_VISITOR_TYPING`](https://webim.ru/kb/11.0/settings/constance/workspace.html#typing) **Webim** показывает набор оператору. По умолчанию настройка включена. Повторные события `user-typing` одного посетителя в одном канале объединяются: в пределах интервала [`CHANNEL_WEBHOOK_TYPING_THROTTLE_INTERVAL`](https://webim.ru/kb/11.0/settings/constance/workspace.html#typing) передаётся последнее событие. По умолчанию интервал — одна секунда.

При выключенной `TRACK_VISITOR_TYPING` запрос `user-typing` тоже получает `result: ok`, но индикатор набора не ставится.

### Пример: текст

```bash
curl --request POST \
  --url 'https://chat.example.local/l/ch' \
  --header 'Content-Type: application/json' \
  --data '{"from":{"id":"visitor-1001","fields":{"display_name":"Евгений","phone":"+78120000000","email":"visitor@example.local"}},"text":"Здравствуйте","secret":"demo-server-secret","channel_id":"142a1718-52f3-4530-b4b6-6f7b0824812c"}'
```

Тот же JSON:

```json
{
  "from": {
    "id": "visitor-1001",
    "fields": {
      "display_name": "Евгений",
      "phone": "+78120000000",
      "email": "visitor@example.local"
    }
  },
  "text": "Здравствуйте",
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

### Пример: файл и голосовое сообщение

Обычный файл передаётся полем `file`. Голосовое сообщение — тот же `file` и `"is_voice": true`. Изображение передаётся в поле `photo`; признак `is_voice` к нему не добавляется.

```json
{
  "from": {
    "id": "visitor-1001"
  },
  "file": "https://files.example.local/voice.mp3",
  "is_voice": true,
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

### Пример: геолокация

```json
{
  "from": {
    "id": "visitor-1001"
  },
  "location": {
    "latitude": 59.954908,
    "longitude": 30.29403,
    "user_location": true
  },
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

Координаты вне диапазонов из таблицы выше не становятся сообщением посетителя. Если к моменту их обработки есть активный диалог (в том числе созданный этим запросом), Webim может добавить в него служебное сообщение о некорректных координатах. Ответ HTTP при этом остаётся успешным.

### Пример: набор текста

```json
{
  "from": {
    "id": "visitor-1001"
  },
  "action": "user-typing",
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

## Ответы на запрос посетителя

Успешный приём:

```json
{
  "result": "ok"
}
```

Ошибки обработчика канала имеют вид:

```json
{
  "error": "код"
}
```

| Условие | HTTP | Тело |
| --- | --- | --- |
| Запрос принят | 200 | `{"result": "ok"}` |
| `Content-Type` не равен `application/json` | 200 | `{"error": "wrong-content-type"}` |
| Корректный JSON-объект не прошёл проверку полей | 200 | `{"error": "internal-error"}` |
| `secret` не совпал с **Нашим секретным ключом** | 403 | `{"error": "unauthorized"}` |
| Канал не найден или `channel_id` не является UUID | 404 | `{"error": "channel-not-found"}` |
| Тело не является синтаксически верным JSON | 400 | Ответ общего обработчика разбора, не код `error` из этой таблицы |

`result: ok` означает, что запрос поставлен в обработку. Для файла это происходит до окончания скачивания: ошибка скачивания в этот HTTP-ответ не попадает.

Повторный входящий `text` может создать в диалоге ещё одно сообщение с тем же текстом.

Посетитель, которому запрещено писать, при корректном запросе тоже получает `result: ok`. Его сообщение в диалог не добавляется. Не чаще одного раза в сутки **Webim** отправляет на адрес сервера текст о блокировке, без объекта `from`. Русский текст ресурса: «Извините, Вам недоступна возможность начинать диалог.» Язык берётся из диалога, а если диалога нет — из языка аккаунта по умолчанию.

## Файлы от посетителя

`photo` и `file` — адрес, который скачивает сервер **Webim**. Адрес должен быть доступен этому серверу. Дополнительные HTTP-заголовки для скачивания API не передаёт. Имя файла берётся из последнего сегмента URL. Если в адресе есть query string, его параметры могут попасть в имя файла.

Перед скачиванием файлов по ссылкам из `photo` и `file` **Webim** проверяет адрес. Адреса внутренней сети по умолчанию запрещены; отдельные хосты можно разрешить через [`SSRF_ALLOWED_HOSTS`](https://webim.ru/kb/11.0/settings/env/general.html#ip). Loopback-адреса и адреса метаданных облачных платформ запрещены всегда.

Ответ `result: ok` приходит до окончания скачивания. Если скачать файл не удалось, в HTTP-ответе ошибки нет: сообщение в диалоге остаётся с ошибкой файла.

На загружаемые файлы действуют ограничения по размеру (`MAX_VISITOR_UPLOAD_FILE_SIZE`, по умолчанию 10 МБ), расширениям (`ALLOWED_UPLOAD_FILE_TYPES`) и MIME-типам (`ALLOWED_UPLOAD_FILE_CONTENT_TYPES`). Значения и списки допустимых типов приведены в [настройках файлов](https://webim.ru/kb/11.0/settings/constance/files-notifications.html#files). Размер дополнительно ограничивается [`NGINX_UPLOAD_SIZE`](https://webim.ru/kb/11.0/settings/env/files.html#limits). MIME-тип определяется по ответу файлового сервера или содержимому файла.

Ожидание отдачи файла ограничено [`HTTP_FILE_DOWNLOAD_TIMEOUT`](https://webim.ru/kb/11.0/channels/common/http-request-timeouts.html).

## Запросы Webim на адрес сервера

**Webim** отправляет `POST` с телом JSON на **Адрес сервера** из формы канала и не добавляет к этому адресу собственные query-параметры. `Content-Type` запроса — `application/json`.

В каждом запросе есть:

| Параметр | Тип | Описание |
| --- | --- | --- |
| `to.id` | Строка | `from.id` посетителя, которому адресовано событие. |
| `secret` | Строка | **Ваш секретный ключ**. |
| `channel_id` | Строка | UUID канала в каноническом виде, с дефисами. |

Объект `from` есть только когда у события есть автор-оператор. Тогда в нём три поля: `name` (имя и фамилия), `id` (числовой идентификатор оператора) и `email` (адрес оператора, в том числе пустая строка, если адрес не задан). У опроса, текста о блокировке, выбора отдела и информирования автора нет, и объекта `from` в запросе нет. У набора текста `from` есть, когда у активного диалога назначен оператор.

### Что приходит в теле

| Событие | Дополнительные поля |
| --- | --- |
| Текст оператора | `text` |
| Изображение, тип содержимого начинается с `image/` | `photo` — URL скачивания |
| Другой файл | `file` — URL скачивания |
| Голосовое сообщение оператора | `file` и `"is_voice": true` |
| Оператор набирает текст | `action` = `operator-typing`, `value` — `true` или `false` |
| Вопрос или завершение опроса | `text` и `action` = `survey` |

Клавиатура, выбор отдела и текст информирования приходят как `text`: пункты меню пронумерованы и разделены переводом строки. В тексте опроса варианты разделены `<br>`. У необязательного вопроса к тексту добавляется подсказка, что вопрос можно пропустить. Запрос контактных данных передаётся обычным `text`. Превью информирования может передаваться текстовой ссылкой.

Служебные сообщения канала уходят как `text`, если в канале включена отправка информационных сообщений. По умолчанию она выключена.

Отдельного callback о закрытии диалога, изменении сообщения и удалении сообщения нет.

URL вложения имеет вид `https://<домен-аккаунта>/l/c/download/<guid>/<имя-файла>?expires=<unix-время>&hash=<подпись>`. Ссылка с параметром `expires` действует ограниченное время.

Длина исходящего `text` этим запросом не обрезается. Для рассылок в кастомный канал и для поля максимальной длины в состоянии диалога посетителя канал сообщает 4096 символов.

Цитата оператора в этот JSON не входит.

### Пример: текст оператора

```json
{
  "to": {
    "id": "visitor-1001"
  },
  "text": "Сейчас уточню информацию.",
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

### Пример: голосовое сообщение оператора

```json
{
  "to": {
    "id": "visitor-1001"
  },
  "file": "https://chat.example.local/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/voice.mp3?expires=1893456000&hash=demo",
  "is_voice": true,
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

Изображение приходит с ключом `photo` и без `is_voice`. Обычный файл приходит с ключом `file` и без `is_voice`.

### Пример: набор текста оператором

```json
{
  "to": {
    "id": "visitor-1001"
  },
  "action": "operator-typing",
  "value": true,
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

`value: false` означает, что оператор перестал набирать текст.

### Пример: опрос

```json
{
  "to": {
    "id": "visitor-1001"
  },
  "text": "Оцените консультацию<br><br>1. Отлично<br>2. Хорошо",
  "action": "survey",
  "secret": "demo-client-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}
```

Ответ посетителя на такой текст передаётся обычным входящим `text`. **Webim** сопоставляет его с текущим вопросом опроса или с номером отдела, если посетителю предложен выбор отдела.

## Ответ Вашего сервера

Успешная доставка — HTTP 200. Любой другой код **Webim** считает ошибкой доставки.

Повторная отправка выполняется, если Ваш сервер не ответил за [`HTTP_WEBHOOK_TIMEOUT`](https://webim.ru/kb/11.0/settings/constance/general.html#http-timeouts) (по умолчанию 5 секунд), не принял соединение или вернул код `5xx`. Тогда тот же callback может прийти ещё раз. Паузы задаёт [`CHANNEL_OUTBOUND_RETRY_DELAYS_SECONDS`](https://webim.ru/kb/11.0/settings/env/integrations.html#http): по умолчанию три повтора через 1, 3 и 10 секунд. Подробности — в разделе [Тайм-ауты HTTP-запросов каналов](https://webim.ru/kb/11.0/channels/common/http-request-timeouts.html).

Ответ `4xx` и ответ с перенаправлением повторно не отправляются. По умолчанию адрес сервера, указывающий на внутреннюю сеть, отклоняется при сохранении канала и при отправке. Отдельные внутренние хосты можно разрешить через [`SSRF_ALLOWED_HOSTS`](https://webim.ru/kb/11.0/settings/env/general.html#ip). Loopback и адреса метаданных облачных платформ запрещены всегда. Отклонённая SSRF-проверкой отправка не повторяется.

---

Источник: https://webim.ru/kb/11.0/api/custom-channel.html
