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

Только на тарифе "Бизнес"

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

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

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

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

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

Перейдите в раздел «Аккаунты».
В строке нужного аккаунта нажмите на иконку шестеренки и выберите «Переадресация (вебхуки)».
Заполните форму настройки:
- URL-адрес: Ссылка на ваш принимающий сервер (например, https://your-crm.ru/api/webhook). Ссылка должна быть публичной (запросы на локальные IP вроде 127.0.0.1 или 192.168.x.x блокируются защитой SSRF).
- Авторизация: Выберите тип авторизации. Рекомендуется использовать Bearer Token и сгенерировать сложный секретный ключ, который AvChat будет присылать в заголовке Authorization: Bearer <ваш_токен>.
- Фильтрация событий: Выберите, какие сообщения нужно отправлять (входящие, исходящие, системные, изображения, голосовые) и нужно ли прикреплять сырой payload от Авито.
- Режим пересылки исходящих:
  - Все сообщения — отправлять любые исходящие сообщения.
  - Только от менеджеров (Рекомендуется) — отсекает автоответы чат-ботов и ИИ-ассистентов в AvChat, пересылая только ответы живых людей. Помогает предотвратить зацикливание («эхо»).
  - Только написанные из Авито — отправлять только сообщения, написанные непосредственно на сайте или в приложении Avito.
Нажмите «Сохранить настройки».
Нажмите кнопку «Тестовая отправка», чтобы проверить доступность вашего сервера. Внизу отобразится HTTP-код и тело ответа вашего сервера.

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, название, цена, ссылка, гео-локация).

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 часто возникает проблема:

Клиент пишет в Авито.
Вебхук отправляет сообщение в CRM.
CRM обрабатывает его и отправляет обратно в AvChat.
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)

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

Небезопасный URL (SSRF): Отключается мгновенно после 1-й попытки.
Постоянная HTTP ошибка (3xx/4xx кроме 408/425/429): Отключается после 2 ошибок доставки подряд.
Сетевой таймаут / Отказ в соединении: Отключается после 5 сбоев подряд.
Общий лимит: 10 последовательных ошибок доставки.
Высокая частота сбоев: 30 ошибок доставки в течение 10 минут.

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

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

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

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

Формат Payload (JSON):

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

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

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

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

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

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

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

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

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

Защита от SSRF

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

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

AI Ассистент