Интеграция по Webhook

Модуль «Переадресация сообщений» (Вебхуки) в AvChat позволяет организовать двусторонний обмен данными между Avito и вашей внешней системой: CRM, Telegram-ботом, внутренним сервисом или конструкторами автоматизации (n8n, Make, Альбато).

Модуль решает две задачи:

1. Исходящие вебхуки: Автоматическая отправка уведомлений о новых входящих и исходящих сообщениях из Avito на ваш URL-адрес.

2. Входящие ответы: Прием текстовых ответов от вашей CRM во входящий API AvChat для последующей мгновенной отправки клиенту в чат Avito.

1. Настройка в личном кабинете AvChat

Настройка вебхуков осуществляется индивидуально для каждого подключенного аккаунта Avito:

1. Перейдите в раздел «Аккаунты».

2. В строке нужного аккаунта откройте меню «⋯» и выберите «Переадресация (вебхуки)».

3. В окне «Настройки переадресации сообщений (Вебхуки)» включите переключатель «Активировать переадресацию» — по умолчанию он выключен, и без него сообщения не отправляются.

4. Заполните форму настройки:

   • «URL-адрес вашего обработчика»: Ссылка на ваш принимающий сервер (например, https://your-crm.ru/api/webhook). Ссылка должна быть публичной (запросы на локальные IP вроде 127.0.0.1 или 192.168.x.x блокируются защитой SSRF).

   • «Авторизация запросов»: Выберите тип авторизации — «Без авторизации» или «Bearer Token (секретный токен в заголовке)». Рекомендуется использовать Bearer Token и сгенерировать сложный секретный ключ (поле «Bearer Token авторизации»), который AvChat будет присылать в заголовке Authorization: Bearer <ваш_токен>.

   • «Фильтрация событий»: Выберите, какие сообщения нужно отправлять (входящие, исходящие, системные, изображения, голосовые) и нужно ли прикреплять сырой payload от Авито (галочки «Пересылать входящие сообщения», «Пересылать исходящие сообщения», «Включая системные сообщения», «Включая изображения», «Включая голосовые сообщения», «Прикреплять raw payload от Авито»).

   • «Режим пересылки исходящих сообщений» (появляется, если отмечена галочка «Пересылать исходящие сообщения»; по умолчанию — «Все исходящие сообщения»):

     • Все исходящие сообщения — отправлять любые исходящие сообщения.

     • Только от менеджеров (без ботов, сценариев и ИИ) (Рекомендуется) — отсекает автоответы чат-ботов и ИИ-ассистентов в AvChat, пересылая только ответы живых людей. Помогает предотвратить зацикливание («эхо»).

     • Только отправленные непосредственно из Авито — отправлять только сообщения, написанные непосредственно на сайте или в приложении Avito.

5. Нажмите «Сохранить настройки».

6. Нажмите кнопку «Тестовая отправка», чтобы проверить доступность вашего сервера. Внизу отобразится HTTP-код и тело ответа вашего сервера.

Если исходящие сообщения вам не нужны (например, CRM должна получать только обращения клиентов), просто снимите галочку «Пересылать исходящие сообщения».

Логи доставки

На вкладке «Логи доставки» того же окна видна история отправок: «Время», «Событие», «Направление» (входящее / исходящее / тест), «Статус» («Успешно», «Повтор», «Ошибка»), число «Попытки» и HTTP-код ответа вашего сервера. Кнопка «Подробнее» показывает детали запроса и ответа, «Обновить» — перезагружает список.

Если доставка начинает давать сбои, на вкладке «Настройки» появится предупреждение «Ошибки доставки вебхука» с числом последовательных ошибок. Если вебхук отключится автоматически, там же будет указана причина и время отключения (по UTC) — см. раздел 5.

2. Исходящие вебхуки (AvChat -> Ваша система)

Когда в диалог поступает новое сообщение, AvChat формирует POST-запрос в формате JSON.

Заголовки HTTP-запроса:

Content-Type: application/json; charset=utf-8
X-AvChat-Event-Id: <уникальный UUID события>
X-AvChat-Timestamp: <timestamp отправки, секунды>
X-AvChat-Idempotency-Key: <уникальный ключ идемпотентности события>
Authorization: Bearer <ваш_секретный_токен> (если включен)

Ключ идемпотентности имеет формат: avito:{account_id}:{chat_id}:{message_id}:{direction}. Используйте его на вашей стороне для дедупликации возможных повторных запросов.

Формат Payload (JSON):

{
  "event": "avito.message.created",
  "version": "1.0",
  "event_id": "f5127cd9-4d8b-4b2a-874b-5ad88df3c9a0",
  "idempotency_key": "avito:24:u2i-chat-12345:msg-7890:incoming",
  "direction": "incoming",
  "message": {
    "id": "msg-7890",
    "local_id": 104593,
    "chat_id": "u2i-chat-12345",
    "chat_type": "u2i",
    "type": "text",
    "text": "Здравствуйте! Сколько стоит доставка?",
    "created_at": "2026-06-07T18:45:00+03:00",
    "author_id": "999888",
    "attachments": []
  },
  "account": {
    "id": 24,
    "name": "ИП Иванов (Авито)",
    "avito_user_id": "123456",
    "account_name": "ИП Иванов (Авито)"
  },
  "interlocutor": {
    "id": "999888",
    "name": "Алексей Петров",
    "url": "https://www.avito.ru/user/public/profile/..."
  },
  "item": {
    "id": "3582019485",
    "title": "Игровой ноутбук RTX 4060",
    "price": "85 000 ₽",
    "url": "https://www.avito.ru/moskva/noutbuki/...",
    "location": "Москва, м. Новослободская"
  }
}

Спецификация полей:

• direction: Направление сообщения (incoming — от покупателя к вам, outgoing — от вас к покупателю).

• message.type: Тип сообщения (text, image, voice).

• message.attachments: Массив вложений.

  • Для изображений содержит ссылки на файл: [{"type": "image", "url": "https://..."}].

  • Для голосовых содержит ID голосового и ссылку на сконвертированный mp4-файл: [{"type": "voice", "voice_id": "...", "transcript": "текст расшифровки", "url": "https://..."}].

• interlocutor: Данные собеседника на Авито (его ID, имя и ссылка на публичный профиль).

• item: Данные объявления, по которому идет переписка (ID, название, цена, ссылка, гео-локация).

• raw_webhook_payload: Исходное сообщение в формате Авито — добавляется, только если отмечена галочка «Прикреплять raw payload от Авито».

• Тестовая отправка приходит с "event": "avito.forwarding.test" и "direction": "test" — не создавайте по ней сделки в CRM.

3. Входящие ответы (Ваша система -> AvChat)

Чтобы отправить ответное сообщение покупателю в чат Авито, ваша система должна отправить HTTP POST запрос на специальный адрес.

URL-адрес запроса:

Адрес генерируется автоматически и содержит уникальный секретный токен inbound_token (формат wh_reply_...):

POST https://backend.avchat.ru/api/webhook/reply/wh_reply_abc123xyz456...

(Точный адрес вы можете скопировать во блоке «Входящий вебхук для ответов в чаты Авито» на вкладке «Настройки» — кнопка копирования справа от адреса)

Заголовки HTTP-запроса:

Content-Type: application/json

Тело запроса (JSON):

{
  "chat_id": "u2i-chat-12345",
  "text": "Здравствуйте! Доставка до СДЭК бесплатная. Отправляем в день заказа."
}

Описание полей:

• chat_id (строка, обязательно): Идентификатор чата Авито, в который нужно отправить сообщение (передается во входящем вебхуке в поле message.chat_id).

• text (строка, обязательно, до 10 000 символов): Текст вашего ответа. Поддерживает переносы строк \n.

Возможные HTTP-ответы:

• 200 OK: Сообщение успешно принято и поставлено в очередь на отправку.

  Код

  {"success": true, "message": "Сообщение успешно поставлено в очередь для отправки."}
  

  Скопировать

• 401 Unauthorized: Неверный или неактивный токен inbound_token.

• 403 Forbidden: У вас на тарифе отключена или не оплачена функция отправки ответов (требуется can_webhook_replay).

• 404 Not Found: Указанный chat_id не принадлежит данному аккаунту Авито (проверьте, что диалог существует).

• 422 Unprocessable Entity: Ошибка валидации данных (отсутствует chat_id или пустое тело сообщения).

• 500 Internal Server Error: Внутренняя ошибка сервера AvChat.

4. Защита от бесконечных циклов («эхо»-петель)

При интеграции с внешними CRM часто возникает проблема:

1. Клиент пишет в Авито.

2. Вебхук отправляет сообщение в CRM.

3. CRM обрабатывает его и отправляет обратно в AvChat.

4. AvChat сохраняет сообщение и снова триггерит вебхук, отправляя его в CRM (бесконечный цикл).

В системе AvChat внедрена автоматическая защита от петель:

• Все сообщения, отправляемые через API ответов (POST /api/webhook/reply/...), получают внутренний системный маркер источника source = 'webhook'.

• При сохранении таких сообщений исходящие вебхуки не запускаются.

• Для дополнительной надежности рекомендуется в настройках вебхука в личном кабинете выставлять фильтр исходящих сообщений в значение «Только от менеджеров».

5. Ограничения и надежность доставки

Защита от SSRF

Запросы отправляются только на публичные IP-адреса. Локальные хосты, петлевые интерфейсы (localhost, 127.0.0.1) и любые приватные подсети класса A, B, C блокируются. Если домен вашего обработчика разрешается в локальный IP, вебхук будет автоматически отключен с соответствующей ошибкой.

Политика повторов (Retries)

Если ваш сервер возвращает код временной ошибки (например, 500 Internal Error, 502 Bad Gateway, 429 Too Many Requests или происходит таймаут соединения):

• Установлен фиксированный таймаут ожидания ответа сервера — 5 секунд.

• AvChat совершит до 3 попыток повторной доставки.

• Попытки осуществляются с возрастающей задержкой (экспоненциальный backoff: 30 сек, 60 сек, 90 сек и т.д.).

• Ошибки с кодами постоянных сбоев (например, 404 Not Found, 401 Unauthorized, 400 Bad Request, 301 Redirect) не повторяются.

Автоматическое отключение (Auto-disable)

Функция автоматического отключения всегда включена для всех вебхуков. Вебхук перейдет в статус «Неактивен» в следующих случаях:

1. Небезопасный URL (SSRF): Отключается мгновенно после 1-й попытки.

2. Постоянная HTTP ошибка (редирект 3xx или код 400, 401, 403, 404, 405, 409, 410, 422): Отключается после 2 ошибок доставки подряд.

3. Сетевой таймаут / Отказ в соединении: Отключается после 5 сбоев подряд.

4. Общий лимит: 10 последовательных ошибок доставки.

5. Высокая частота сбоев: 30 ошибок доставки в течение 10 минут.

При автоотключении владельцу аккаунта мгновенно отправляется подробное HTML-уведомление в Telegram с указанием конкретной причины отключения и адреса сбойного сервера. После устранения неполадок на вашей стороне вы можете снова активировать вебхук в настройках личного кабинета: включите переключатель «Активировать переадресацию» и нажмите «Сохранить настройки».

См. также: Отправить HTTP-запрос на внешний URL — если нужно отправлять данные во внешнюю систему не по каждому сообщению, а по событию в сценарии.