> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Интеграция с Chatwoot

> Зеркально отражать разговоры WhatsApp в почтовый ящик Chatwoot и пусть агенты ответили от Chatwoot.

При включенном Chatwoot GOWA перенаправляет сообщения WhatsApp (входящие, и исходящие из телефона, отправленные в входящий канал Chatwoot **API** и отправляющие ответы агента из Chatwoot обратно в WhatsApp. Поддерживаются текст, изображения, аудио, видео, документы, наклейки, местоположение и контакты; групповые чаты появляются как один разговор для группы, с префиксом имени отправителя.

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## Требования

* GOWA доступен с Chatwoot через публичный URL (для agent-reply webhooks).
* Учетная запись Chatwoot с правами администратора и маркером доступа к API пользователя.
* По крайней мере одно залогиненное устройство WhatsApp.

## Настроить

**1. Создать входящий API канал**

В Чате перейдите в **Настройки → Входящие → Добавить Входящие → API**. Обратите внимание на числовые **входящие ID** по адресу "Входящие" и на **секрет webhook** в чате для канала. Или пусть GOWA создаст входящие (см. [Auto-provisioning](#%D0%B0%D0%B2%D1%82%D0%BE%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0)).

**2. Сбор идентификаторов и токена**

**ID аккаунта** — это число в `/app/accounts/<id>/...`. Скопируйте пользователя **маркер доступа** из **настроек профиля**. Оба идентификатора должны быть цифровыми идентификаторами, а не идентификатором канала `identifier` или `hmac_token`.

**3. Настроить GOWA**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

Перезапустить GOWA: маршруты Chatwoot регистрируются при запуске.

**4. Точка Чатвут на GOWA**

Установите URL-адрес канала API в `https://gowa.example.com/chatwoot/webhook` (с `APP_BASE_PATH`, укажите путь к базе данных). Этот маршрут является общедоступным: он защищен секретом webhook, а не Базовым Автом.

**5. Тест**

Сообщайте номер WhatsApp с другого телефона; он должен появиться в папке "Входящие". Ответьте из Чатвута и проверьте, что он прибудет на WhatsApp.

## Конфигурация

| Переменная | По умолчанию | Описание |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | Мастер переключения. |
| `CHATWOOT_URL` | — | URL базы данных чата, нет конечной слэш. |
| `CHATWOOT_API_TOKEN` | — | Маркер доступа к API пользователя. |
| `CHATWOOT_ACCOUNT_ID` | — | Числовой идентификатор аккаунта. |
| `CHATWOOT_INBOX_ID` | — | Цифровой идентификатор. Необязательно использовать `CHATWOOT_AUTO_CREATE=true`; когда задано, он всегда выигрывает. |
| `CHATWOOT_DEVICE_ID` | — | Устройство (слот ID или JID), которое отправляет ответы агента. Требуется при наличии нескольких устройств. |
| `CHATWOOT_WEBHOOK_URL` | — | Публичный GOWA webhook URL; используется при автоматическом создании ящика. |
| `CHATWOOT_WEBHOOK_SECRET` | — | Проверяет входящие вебхуки Chatwoot. Пустой эффективный секрет отклоняет вызовы, если не включено явное неподписанное переопределение. |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | Принимать запросы без эффективной секретности. Ограничьте это доверенной сетью. |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | Максимальный возраст / часы `X-Chatwoot-Timestamp`. |
| `CHATWOOT_AUTO_CREATE` | `false` | Повторно использовать или создать почтовый ящик API с именем `CHATWOOT_INBOX_NAME` при запуске. |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | Имя папки "Входящие" для автонастройки. |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | Импортировать историю автоматически, когда устройство подключено. |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | Дни истории для импорта. |
| `CHATWOOT_IMPORT_DB_URI` | — | Chatwoot PostgreSQL URI для прямого импорта истории (хранит оригинальные временные метки). |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | Прямой импорт: вставьте `[image]`-style плейсхолдеров, которые не могут быть скачаны. |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | Прямой импорт: выгрузка медиа через REST API, так что вложения создаются. |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | Повторно открыть разрешенный разговор, когда контакт заново записывает контакт. |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | Создавать новые диалоги со статусом `pending` вместо `open`. |
| `CHATWOOT_IGNORE_JIDS` | — | Разделенные запятыми JIDs или звездочками (`@g.us`, `@s.whatsapp.net`, `@lid`) никогда не зеркалируется. |
| `CHATWOOT_SIGN_MSG` | `false` | Ответы префиксного агента на имя агента. |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | Разделитель между подписью и сообщением. |
| `CHATWOOT_FORWARD_EDITS` | `true` | Зеркальное редактирование WhatsApp как личные заметки. |
| `CHATWOOT_FORWARD_DELETES` | `true` | Зеркальное удаление для всех как личные заметки. |
| `CHATWOOT_EVENTS` | Следует `WHATSAPP_WEBHOOK_EVENTS` | События, разделенные запятой, для пересылки на Чатвут. |
| `CHATWOOT_MESSAGE_READ` | `false` | Синхронизировать статус чтения обоих способов. |
| `CHATWOOT_MESSAGE_DELETE` | `false` | Исключить связанное сообщение с другой стороны. |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | Отозвать связанные исходящие сообщения WhatsApp, когда агент удалит их сообщение Chatwoot. |
| `CHATWOOT_ALLOWED_HOSTS` | — | Разрешенный список хостов `chatwoot_url` для каждого из устройств. |

У большинства настроек также есть флаг `--chatwoot-*`; `CHATWOOT_URL`, `CHATWOOT_API_TOKEN`, `CHATWOOT_ACCOUNT_ID` и `CHATWOOT_INBOX_ID` задаются только через переменные окружения. См. [справочник конфигурации](https://gowa-docs.mintlify.site/ru/configuration.md).

Для GOWA `main` после v9.9.0 установите `CHATWOOT_EVENTS=message`, чтобы поддерживать зеркалирование сообщений в Chatwoot при фильтрации обычных доставки веб-хука отдельно. Селектор `message` также позволяет реакции, квитанции, правки и удалять через фильтр Chatwoot. Все еще применяются параметры для чтения, редактирования и удаления.

Оставьте поле `CHATWOOT_EVENTS` пустым, чтобы наследовать `WHATSAPP_WEBHOOK_EVENTS`. Если эффективный фильтр пуст, он позволяет все поддерживаемые события. Если он исключает `message`, GOWA записывает предупреждение при запуске и останавливает зеркалирование сообщений WhatsApp в Chatwoot.

В этих сборках GOWA посылает токен пользователя Chatwoot в заголовке `api-access-token`, чтобы nginx мог передать его с параметрами заголовка по умолчанию.

## Секрет Webhook

Пустой эффективный секретный вебхук отказывает в доставке. `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true` явно разрешает доставку без знака, когда эффективный секрет пуст. С помощью секретного ключа каждый запрос должен доказать его одним из:

1. **Chatwoot's signature** (`X-Chatwoot-Signature` + `X-Chatwoot-Timestamp`), рекомендуется. Используйте собственный секрет webhook каналов. GOWA проверяет HMAC-SHA256 из `<timestamp>.<raw body>` и отвергает временные метки вне настроенного допущения.
2. `X-Hub-Signature-256` HMAC тела.
3. Секрет в заголовке `X-Chatwoot-Webhook-Secret` или `X-Gowa-Chatwoot-Secret`.
4. `?secret=` в URL webhook, только для версий Chatwoot, которые не могут подписать или добавить заголовки. Секрет, затем появляется в логах доступа.

При ошибке возвращается `401`; GOWA записывает причину в журнал (`signature does not match` означает неверный секрет, `timestamp outside the tolerance window` — расхождение часов).

`webhook_secret` на устройстве заменяет глобальный секрет для этого устройства как на общедоступных терминалах, так и на отдельных устройствах. Без секретного устройства глобальная секретная информация будет сохранена. GOWA проверяет секрет маршрутизированного устройства перед отправкой, удалением, маркировкой чтения или записью данных. При использовании нескольких устройств одним и тем же идентификатором учетной записи и папки "входящие" предпочтение отдается URL обратного вызова на устройство.

Повторный запрос с подписью Chatwoot, на который уже был получен ответ `2xx`, подтверждается ответом `200` и пропускается в пределах допустимого временного окна. Неудавшиеся запросы можно повторять. Идентичный запрос, обработка которого ещё продолжается, может получить `503` после ожидания до 30 секунд. Данные для защиты от повторов хранятся локально в процессе, теряются при перезапуске и ограничены 65,536 принятыми запросами. Они не разделяются между экземплярами GOWA. Две доставки одного сообщения Chatwoot с отдельными подписями по-прежнему могут привести к двойной отправке. HMAC только для тела запроса, заголовки с секретом и секреты в параметрах запроса не обеспечивают такую дедупликацию доставок.

## Автонастройка

С `CHATWOOT_AUTO_CREATE=true` без `CHATWOOT_INBOX_ID`, GOWA ищет входящий API с именем `CHATWOOT_INBOX_NAME` при запуске и повторно использует его или создает его с помощью `CHATWOOT_WEBHOOK_URL` в качестве веб-хука.

## Один входящий на устройство

Переменные окружения настраивают одно направление общего доступа для всех устройств. Для маршрутизации каждого устройства на свой почтовый ящик, аккаунт или сервер Chatwoot, храните настройки для каждого устройства (применяется основная аутентификация):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

Ответ включает в себя `webhook_url` (`<base>/chatwoot/webhook/<device_id>`); установите его как webhook inbox. Другие маршруты: `GET /chatwoot/configs`, `GET` и `DELETE /devices/{device_id}/chatwoot/config`.

> [!WARNING]
>
> Как только **любой** конфигурация для каждого устройства существует, `CHATWOOT_*` назначения больше не используется в качестве резервного хранилища. Устройства без конфигурации не зеркалируются.

* `api_token` хранится в базе данных GOWA и замаскирован в чтениях; `webhook_secret` никогда не возвращается.
* `chatwoot_url` должен быть HTTP или HTTPS без учётных данных. Без `CHATWOOT_ALLOWED_HOSTS`, приватного, loopback, ссылки локальных и метаданных не учитываются. Откровенно подходящий хост в `CHATWOOT_ALLOWED_HOSTS` является доверенным и может быть использован в чатwoot приватной сети. Установите этот список только для хостов, которым вы управляете.
* Изменение `chatwoot_url`, `account_id` или `inbox_id` после того, как разговоры связаны, возвращает `409`; удалите и пересоздайте конфигурацию.
* Перед синхронизацией устройства можно создать конфигурацию.
* Прямой импорт баз данных работает только в режиме одинарной конфигурации (окружения).

## Ответы и форматирование

Когда агент использует **Ответь** в Чатвуде, GOWA цитирует исходное сообщение WhatsApp, когда оно может разрешать его в локальном магазине и в том же чате. Это применимо к тексту и каждому вложению, включая аудио- и файловый резерв. Заголовок остается только на первом вложении.

Для входящего сообщения WhatsApp GOWA разрешает `in_reply_to_external_id` с префиксом `WAID:<id>`. Для более раннего ответа агента числовое значение `in_reply_to` разрешает через прочную ссылку сообщения в том же устройстве, разговоре, аккаунте, папке "Входящие" и настройке. Сообщение с несколькими вложениями цитирует первый файл. Если цель не может быть решена, ответ доставлен без цитаты.

Входящие ответы WhatsApp и темы реакций на указанное сообщение в Chatwoot. Agent reply Markdown ссылки и акцент преобразуются в читаемый текст WhatsApp. Списки, разрывы строк и код сохраняются. Пустые разделители подписи удаляются. `CHATWOOT_SIGN_MSG` префиксы имени агента после этой конвертации.

Отправляются только сообщения публичных исходящих агентов. Приватные заметки и исключенные чаты не пересылаются. GOWA использует настроенную идентификацию устройства и учетной записи/папки "входящие" для маршрута общих обратных вызовов. Обратный вызов каждого устройства обеспечивает однозначный маршрут.

### Опросы и Агенты удаляют

На GOWA `main` после v9.9.0 зеркала Chatwoot создают, редактируют и добавляют опции. Чтобы обработать голосование, подпишитесь на `message` в [WhatsApp webhooks](https://gowa-docs.mintlify.site/ru/concepts/webhooks.md#%D0%B0%D0%BB%D1%8C%D0%B1%D0%BE%D0%BC%D1%8B-%D0%B8-%D1%81%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D1%8B%D0%B5-%D1%81%D0%BE%D0%BE%D0%B1%D1%89%D0%B5%D0%BD%D0%B8%D1%8F) и прочитайте структурированные данные опроса.

Для этих сборок установите `CHATWOOT_REVOKE_ON_DELETE=true` для синхронизации удалений из Chatwoot только в WhatsApp. Удаление должно совпадать с прочными ссылками на исходящие сообщения в конфигурации активного чата. GOWA аннулирует каждое связанное сообщение WhatsApp, включая вложения, отправленные отдельно. С помощью `CHATWOOT_FORWARD_DELETES=true`, удаляет из WhatsApp все еще как личные заметки. Используйте `CHATWOOT_MESSAGE_DELETE=true` для удаления связанных сообщений в обоих направлениях.

## История импорта

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

По умолчанию: `days_limit=3`, `include_media=true` и `include_groups=true`. Синхронизация считывает локальное хранилище чатов GOWA и работает в фоновом режиме. Каждое устройство может запустить одну синхронизацию одновременно.

На GOWA `main` после v9.9.0, история может попросить телефон повторно загрузить просроченный носитель. Телефон должен быть онлайн и все еще иметь файл. Если телефон не ответил в течение 30 секунд, синхронизация пропускает дальнейшие повторные запросы на загрузку и продолжает импортировать сообщения. Сообщение, файл которого не доступен, импортирован без вложения.

Путь REST не может установить оригинальные временные метки; импортированные сообщения получают время импорта. Для самостоятельной работы Chatwoot, `CHATWOOT_IMPORT_DB_URI` записывается в PostgreSQL и сохраняет их.

С помощью `CHATWOOT_REOPEN_CONVERSATION=true` в `main` GOWA после v9.9.0, синхронизация истории только вновь открывает разрешенный разговор, когда у него есть новое сообщение для импорта. Повторная синхронизация вновь открывает разговор перед отправкой сообщения и повторяет чат в следующей синхронизации, если возобновление завершилось неудачей. Прямой импорт PostgreSQL открывает его в той же транзакции, что и запись сообщения. Если настройка выключена, REST синхронизация создает свежую беседу для новых сообщений, в то время как прямой импорт продолжит использовать разрешенную беседу.

## Поставки и повторы

Живые сообщения, которые столкнулись с временной ошибкой Chatwoot (ошибка сети, HTTP 429 или 5xx) поставлен в очередь на локальное хранилище и повторен в фоновом режиме с ограниченным экспоненциальным backoff. Другие 4xx ошибки регистрируются и удаляются.

## Устранение проблем

| Симптом | Проверить |
| - | - |
| Ответы Агента не доставлены | Установка `CHATWOOT_DEVICE_ID` и авторизация на устройстве; URL-адрес webhook правильно и открыт; `DEVICE_NOT_AVAILABLE` в журналах означает, что устройство не может быть использовано. |
| `401` на `/chatwoot/webhook` | Секретное несоответствие или дрейф часов (см. выше). |
| Сообщения WhatsApp отсутствуют в Chatwoot | Проверьте `CHATWOOT_ENABLED`, токен пользователя, ID папки и папки "входящие" и подключение к `CHATWOOT_URL`. При более новых сборках проверьте, что эффективный фильтр событий включает в себя `message`. |
| `CHATWOOT_NOT_CONFIGURED` | Отсутствует URL, токен, ID аккаунта или ID входящих. |

Запустите `APP_DEBUG=true` и найдите строки журнала, начиная с `Chatwoot:` и `Chatwoot Webhook:`. Вверх [Руководство по Chatwoot](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md) описывает непосредственный импорт баз данных и правила форматирования в более глубокой степени.


## Related topics

- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/ru/index.md)
- [Синхронизировать историю сообщений в Chatwoot](https://gowa-docs.mintlify.site/ru/api-reference/chatwoot/синхронизировать-историю-сообщений-в-chatwoot.md)
- [Получить конфигурацию Chatwoot устройства](https://gowa-docs.mintlify.site/ru/api-reference/chatwoot/получить-конфигурацию-chatwoot-устройства.md)
- [Удалить конфигурацию Chatwoot устройства](https://gowa-docs.mintlify.site/ru/api-reference/chatwoot/удалить-конфигурацию-chatwoot-устройства.md)
- [Получить прогресс синхронизации Chatwoot](https://gowa-docs.mintlify.site/ru/api-reference/chatwoot/получить-прогресс-синхронизации-chatwoot.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.