chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
733566bc2b
commit
c7ed57567b
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над поведінкою каналу WhatsApp/web або маршрутизацією вхідних повідомлень
|
||||
summary: Підтримка каналу WhatsApp, керування доступом, поведінка доставки та операції
|
||||
summary: Підтримка каналу WhatsApp, засоби контролю доступу, поведінка доставки та операції
|
||||
title: WhatsApp
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T04:50:03Z"
|
||||
generated_at: "2026-04-26T16:54:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fd4217adb673bc4c071fc1bff6994fb214966c2b28fe59253a1a6f4b4b7fcdba
|
||||
source_hash: 120a41eabfd7eb2a68555609f8f8282025ecedf54fae9846e85f78f5de2825a1
|
||||
source_path: channels/whatsapp.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Статус: готовий до продакшену через WhatsApp Web (Baileys). Gateway керує пов’язаною сесією(ями).
|
||||
Статус: готовий до production через WhatsApp Web (Baileys). Gateway керує пов’язаними сесіями.
|
||||
|
||||
## Встановлення (за потреби)
|
||||
|
||||
- Онбординг (`openclaw onboard`) і `openclaw channels add --channel whatsapp`
|
||||
пропонують встановити Plugin WhatsApp, коли ви вперше його вибираєте.
|
||||
- `openclaw channels login --channel whatsapp` також пропонує процес встановлення, якщо
|
||||
- Під час початкового налаштування (`openclaw onboard`) і `openclaw channels add --channel whatsapp`
|
||||
буде запропоновано встановити Plugin WhatsApp, коли ви вперше виберете його.
|
||||
- `openclaw channels login --channel whatsapp` також пропонує процес встановлення, коли
|
||||
Plugin ще не встановлено.
|
||||
- Канал розробки + git checkout: за замовчуванням використовується локальний шлях до Plugin.
|
||||
- Канал для розробки + git checkout: за замовчуванням використовується локальний шлях Plugin.
|
||||
- Stable/Beta: за замовчуванням використовується npm-пакет `@openclaw/whatsapp`.
|
||||
|
||||
Ручне встановлення також доступне:
|
||||
@ -34,10 +34,10 @@ openclaw plugins install @openclaw/whatsapp
|
||||
Типова політика DM — сполучення для невідомих відправників.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Діагностика між каналами та сценарії виправлення.
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналу.
|
||||
<Card title="Налаштування Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -67,13 +67,13 @@ openclaw plugins install @openclaw/whatsapp
|
||||
openclaw channels login --channel whatsapp
|
||||
```
|
||||
|
||||
Для певного облікового запису:
|
||||
Для конкретного облікового запису:
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel whatsapp --account work
|
||||
```
|
||||
|
||||
Щоб підключити наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом:
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
|
||||
@ -90,20 +90,20 @@ openclaw gateway
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Схваліть перший запит на сполучення (якщо використовується режим сполучення)">
|
||||
<Step title="Схваліть перший запит на сполучення (якщо використовується режим pairing)">
|
||||
|
||||
```bash
|
||||
openclaw pairing list whatsapp
|
||||
openclaw pairing approve whatsapp <CODE>
|
||||
```
|
||||
|
||||
Термін дії запитів на сполучення спливає через 1 годину. Кількість очікувальних запитів обмежена 3 на канал.
|
||||
Запити на сполучення спливають через 1 годину. Кількість запитів у стані очікування обмежена до 3 на канал.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
OpenClaw рекомендує, за можливості, використовувати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але також підтримуються сценарії з особистим номером.)
|
||||
OpenClaw рекомендує, за можливості, запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але конфігурації з особистим номером також підтримуються.)
|
||||
</Note>
|
||||
|
||||
## Шаблони розгортання
|
||||
@ -114,7 +114,7 @@ OpenClaw рекомендує, за можливості, використову
|
||||
|
||||
- окрема ідентичність WhatsApp для OpenClaw
|
||||
- чіткіші allowlist для DM і межі маршрутизації
|
||||
- менша ймовірність плутанини з чатом із самим собою
|
||||
- нижча ймовірність плутанини із самочатом
|
||||
|
||||
Мінімальний шаблон політики:
|
||||
|
||||
@ -131,19 +131,19 @@ OpenClaw рекомендує, за можливості, використову
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Резервний варіант із особистим номером">
|
||||
Онбординг підтримує режим особистого номера й записує базову конфігурацію, дружню до чату із самим собою:
|
||||
<Accordion title="Резервний варіант з особистим номером">
|
||||
Початкове налаштування підтримує режим особистого номера і записує базову конфігурацію, дружню до самочату:
|
||||
|
||||
- `dmPolicy: "allowlist"`
|
||||
- `allowFrom` містить ваш особистий номер
|
||||
- `selfChatMode: true`
|
||||
|
||||
Під час виконання захист для чату із самим собою прив’язується до підключеного власного номера та `allowFrom`.
|
||||
Під час виконання захист самочату прив’язується до пов’язаного власного номера та `allowFrom`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Охоплення каналу лише для WhatsApp Web">
|
||||
Канал платформи обміну повідомленнями у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
|
||||
<Accordion title="Область каналу лише для WhatsApp Web">
|
||||
Канал платформи обміну повідомленнями в поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
|
||||
|
||||
Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі чат-каналів немає.
|
||||
|
||||
@ -152,19 +152,20 @@ OpenClaw рекомендує, за можливості, використову
|
||||
|
||||
## Модель виконання
|
||||
|
||||
- Gateway керує сокетом WhatsApp і циклом перепідключення.
|
||||
- Gateway керує сокетом WhatsApp і циклом повторного підключення.
|
||||
- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тиха сесія пов’язаного пристрою не перезапускається лише через те, що ніхто не надсилав повідомлень останнім часом. Довше обмеження тиші на рівні застосунку все ж примусово викликає повторне підключення, якщо транспортні фрейми продовжують надходити, але жодні повідомлення застосунку не обробляються в межах вікна watchdog.
|
||||
- Для вихідних надсилань потрібен активний слухач WhatsApp для цільового облікового запису.
|
||||
- Чати статусів і розсилок ігноруються (`@status`, `@broadcast`).
|
||||
- Прямі чати використовують правила сесій DM (`session.dmScope`; типове значення `main` зводить DM до головної сесії агента).
|
||||
- Групові сесії ізольовані (`agent:<agentId>:whatsapp:group:<jid>`).
|
||||
- Транспорт WhatsApp Web враховує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Віддавайте перевагу проксі на рівні хоста, а не специфічним для каналу налаштуванням проксі WhatsApp.
|
||||
- Транспорт WhatsApp Web підтримує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу проксі-конфігурації на рівні хоста, а не специфічним налаштуванням проксі WhatsApp для каналу.
|
||||
- Коли увімкнено `messages.removeAckAfterReply`, OpenClaw очищає реакцію підтвердження WhatsApp після доставки видимої відповіді.
|
||||
|
||||
## Хуки Plugin і конфіденційність
|
||||
|
||||
Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів,
|
||||
ідентифікатори груп, імена відправників і поля кореляції сесій. З цієї причини
|
||||
WhatsApp не транслює вхідні payload `message_received` хуків до Plugin
|
||||
Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери
|
||||
телефонів, ідентифікатори груп, імена відправників і поля кореляції сесій. З цієї причини
|
||||
WhatsApp не транслює вхідні payload хуку `message_received` до Plugin
|
||||
без вашої явної згоди:
|
||||
|
||||
```json5
|
||||
@ -197,10 +198,10 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
}
|
||||
```
|
||||
|
||||
Увімкніть це лише для Plugin, яким ви довіряєте отримання вхідного вмісту
|
||||
повідомлень WhatsApp та ідентифікаторів.
|
||||
Увімкніть це лише для тих Plugin, яким ви довіряєте отримання вмісту
|
||||
та ідентифікаторів вхідних повідомлень WhatsApp.
|
||||
|
||||
## Керування доступом і активація
|
||||
## Контроль доступу та активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика DM">
|
||||
@ -208,55 +209,55 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
|
||||
- `pairing` (типово)
|
||||
- `allowlist`
|
||||
- `open` (вимагає, щоб `allowFrom` містив `"*"`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`allowFrom` приймає номери у форматі E.164 (внутрішньо нормалізуються).
|
||||
`allowFrom` приймає номери у стилі E.164 (внутрішньо нормалізуються).
|
||||
|
||||
Перевизначення для кількох облікових записів: `channels.whatsapp.accounts.<id>.dmPolicy` (і `allowFrom`) мають пріоритет над типовими значеннями на рівні каналу для цього облікового запису.
|
||||
|
||||
Деталі поведінки під час виконання:
|
||||
|
||||
- сполучення зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, пов’язаний власний номер дозволяється за замовчуванням
|
||||
- OpenClaw ніколи не виконує автоматичне сполучення для вихідних `fromMe` DM (повідомлень, які ви надсилаєте собі з пов’язаного пристрою)
|
||||
- сполучення зберігаються у channel allow-store і об’єднуються з налаштованим `allowFrom`
|
||||
- якщо allowlist не налаштовано, пов’язаний власний номер дозволяється типово
|
||||
- OpenClaw ніколи не виконує автоматичне сполучення вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з пов’язаного пристрою)
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Групова політика + allowlist">
|
||||
<Tab title="Політика груп + allowlist">
|
||||
Доступ до груп має два рівні:
|
||||
|
||||
1. **Allowlist членства в групі** (`channels.whatsapp.groups`)
|
||||
- якщо `groups` пропущено, придатними вважаються всі групи
|
||||
- якщо `groups` присутній, він діє як allowlist груп (`"*"` дозволено)
|
||||
1. **Allowlist членства у групі** (`channels.whatsapp.groups`)
|
||||
- якщо `groups` не вказано, усі групи є потенційно допустимими
|
||||
- якщо `groups` задано, воно діє як group allowlist (дозволено `"*"`)
|
||||
|
||||
2. **Політика відправників у групі** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
|
||||
- `open`: allowlist відправників обходиться
|
||||
- `open`: allowlist відправників оминається
|
||||
- `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`)
|
||||
- `disabled`: блокувати всі вхідні повідомлення груп
|
||||
- `disabled`: блокувати всі вхідні повідомлення з груп
|
||||
|
||||
Резервне значення allowlist відправників:
|
||||
Резервний варіант allowlist відправників:
|
||||
|
||||
- якщо `groupAllowFrom` не задано, під час виконання використовується `allowFrom`, якщо воно доступне
|
||||
- allowlist відправників перевіряються перед активацією згадкою/відповіддю
|
||||
- якщо `groupAllowFrom` не встановлено, під час виконання використовується `allowFrom`, якщо він доступний
|
||||
- allowlist відправників перевіряються до активації за згадкою/відповіддю
|
||||
|
||||
Примітка: якщо блоку `channels.whatsapp` немає взагалі, резервна групова політика під час виконання — `allowlist` (із попередженням у журналі), навіть якщо встановлено `channels.defaults.groupPolicy`.
|
||||
Примітка: якщо блока `channels.whatsapp` взагалі немає, резервна політика груп під час виконання — `allowlist` (із попереджувальним записом у журналі), навіть якщо встановлено `channels.defaults.groupPolicy`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Згадки + /activation">
|
||||
Відповіді в групах за замовчуванням вимагають згадки.
|
||||
За замовчуванням відповіді в групі потребують згадки.
|
||||
|
||||
Виявлення згадок включає:
|
||||
Визначення згадки включає:
|
||||
|
||||
- явні згадки WhatsApp ідентичності бота
|
||||
- налаштовані шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`)
|
||||
- явні згадки ідентичності бота в WhatsApp
|
||||
- налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`)
|
||||
- транскрипти вхідних голосових повідомлень для авторизованих групових повідомлень
|
||||
- неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота)
|
||||
- неявне визначення відповіді боту (відправник відповіді збігається з ідентичністю бота)
|
||||
|
||||
Примітка щодо безпеки:
|
||||
|
||||
- цитування/відповідь лише задовольняє умову згадки; це **не** надає авторизацію відправнику
|
||||
- цитування/відповідь лише задовольняє вимогу згадки; це **не** надає авторизації відправнику
|
||||
- з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist
|
||||
|
||||
Команда активації на рівні сесії:
|
||||
@ -264,39 +265,39 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
`activation` оновлює стан сесії (а не глобальну конфігурацію). Доступ до неї обмежений власником.
|
||||
`activation` оновлює стан сесії (а не глобальну конфігурацію). Вона обмежена власником.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Особистий номер і поведінка чату із самим собою
|
||||
## Поведінка особистого номера та самочату
|
||||
|
||||
Коли пов’язаний власний номер також присутній у `allowFrom`, активується захист чату із самим собою в WhatsApp:
|
||||
Коли пов’язаний власний номер також присутній у `allowFrom`, активується захист самочату WhatsApp:
|
||||
|
||||
- пропускати read receipts для ходів у чаті із самим собою
|
||||
- ігнорувати поведінку автоматичного тригера mention-JID, яка інакше надсилала б згадку вам самим
|
||||
- якщо `messages.responsePrefix` не встановлено, відповіді в чаті із самим собою за замовчуванням використовують `[{identity.name}]` або `[openclaw]`
|
||||
- пропускати read receipts для ходів самочату
|
||||
- ігнорувати поведінку автозапуску mention-JID, яка інакше могла б пінгувати вас самих
|
||||
- якщо `messages.responsePrefix` не встановлено, відповіді в самочаті типово використовують `[{identity.name}]` або `[openclaw]`
|
||||
|
||||
## Нормалізація повідомлень і контекст
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вхідний конверт + контекст відповіді">
|
||||
Вхідні повідомлення WhatsApp загортаються у спільний вхідний конверт.
|
||||
Вхідні повідомлення WhatsApp обгортаються у спільний вхідний конверт.
|
||||
|
||||
Якщо існує цитована відповідь, контекст додається в такому вигляді:
|
||||
Якщо існує цитована відповідь, контекст додається в такій формі:
|
||||
|
||||
```text
|
||||
[Replying to <sender> id:<stanzaId>]
|
||||
[Відповідь на <sender> id:<stanzaId>]
|
||||
<quoted body or media placeholder>
|
||||
[/Replying]
|
||||
[/Відповідь]
|
||||
```
|
||||
|
||||
Метадані відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника).
|
||||
Метадані відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Заповнювачі медіа та витягування локації/контактів">
|
||||
Вхідні повідомлення лише з медіа нормалізуються з такими заповнювачами:
|
||||
<Accordion title="Заповнювачі медіа та видобування location/contact">
|
||||
Вхідні повідомлення лише з медіа нормалізуються із заповнювачами на кшталт:
|
||||
|
||||
- `<media:image>`
|
||||
- `<media:video>`
|
||||
@ -304,34 +305,34 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
- `<media:document>`
|
||||
- `<media:sticker>`
|
||||
|
||||
Авторизовані голосові повідомлення в групах транскрибуються до перевірки згадки, коли
|
||||
тіло містить лише `<media:audio>`, тому згадка бота в голосовому повідомленні
|
||||
може спровокувати відповідь. Якщо транскрипт усе одно не містить згадки бота,
|
||||
Авторизовані голосові повідомлення в групі транскрибуються до перевірки згадки, коли
|
||||
тіло повідомлення — лише `<media:audio>`, тож згадка бота в голосовому повідомленні може
|
||||
запустити відповідь. Якщо транскрипт усе ще не містить згадки бота,
|
||||
транскрипт зберігається в історії очікування групи замість сирого заповнювача.
|
||||
|
||||
Тіла повідомлень із локацією використовують стислий текст координат. Мітки/коментарі локацій і деталі контакту/vCard відображаються як огороджені ненадійні метадані, а не як вбудований текст prompt.
|
||||
Тіла location використовують стислий текст координат. Мітки/коментарі location та деталі contact/vCard відображаються як fenced недовірені метадані, а не як вбудований текст prompt.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ін’єкція історії очікування групи">
|
||||
Для груп необроблені повідомлення можуть буферизуватися та вставлятися як контекст, коли бот нарешті активується.
|
||||
Для груп необроблені повідомлення можуть буферизуватися та ін’єктуватися як контекст, коли бот нарешті активується.
|
||||
|
||||
- типове обмеження: `50`
|
||||
- конфігурація: `channels.whatsapp.historyLimit`
|
||||
- резервне значення: `messages.groupChat.historyLimit`
|
||||
- резервний варіант: `messages.groupChat.historyLimit`
|
||||
- `0` вимикає
|
||||
|
||||
Маркери вставки:
|
||||
Маркери ін’єкції:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
- `[Повідомлення чату з вашої останньої відповіді — для контексту]`
|
||||
- `[Поточне повідомлення — дайте відповідь на нього]`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підтвердження прочитання">
|
||||
Підтвердження прочитання увімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
|
||||
Підтвердження прочитання увімкнено типово для прийнятих вхідних повідомлень WhatsApp.
|
||||
|
||||
Вимкнення глобально:
|
||||
Вимкнути глобально:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -343,7 +344,7 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення для кожного облікового запису:
|
||||
Перевизначення для окремого облікового запису:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -359,7 +360,7 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
}
|
||||
```
|
||||
|
||||
Для ходів у чаті із самим собою підтвердження прочитання пропускаються навіть тоді, коли вони глобально увімкнені.
|
||||
Для ходів самочату підтвердження прочитання пропускаються навіть коли вони глобально увімкнені.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -370,40 +371,40 @@ WhatsApp не транслює вхідні payload `message_received` хукі
|
||||
<Accordion title="Розбиття тексту на частини">
|
||||
- типове обмеження частини: `channels.whatsapp.textChunkLimit = 4000`
|
||||
- `channels.whatsapp.chunkMode = "length" | "newline"`
|
||||
- режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечного за довжиною розбиття
|
||||
- режим `newline` надає перевагу межам абзаців (порожні рядки), а потім повертається до безпечного за довжиною розбиття
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка вихідних медіа">
|
||||
- підтримуються payload зображень, відео, аудіо (голосові повідомлення PTT) і документів
|
||||
- аудіомедіа надсилаються через payload `audio` Baileys з `ptt: true`, тому клієнти WhatsApp відображають їх як голосове повідомлення push-to-talk
|
||||
- payload відповідей зберігають `audioAsVoice`; вихід TTS у вигляді голосових повідомлень для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM
|
||||
- нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими повідомленнями
|
||||
- аудіо не у форматі Ogg, включно з MP3/WebM від Microsoft Edge TTS, перед доставкою PTT перекодовується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц
|
||||
- `/tts latest` надсилає останню відповідь асистента як одне голосове повідомлення та пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp
|
||||
- підтримуються payload зображень, відео, аудіо (голосова нотатка PTT) і документів
|
||||
- аудіомедіа надсилаються через payload `audio` у Baileys з `ptt: true`, тому клієнти WhatsApp відображають їх як голосову нотатку push-to-talk
|
||||
- payload відповідей зберігають `audioAsVoice`; вихід TTS голосової нотатки для WhatsApp лишається на цьому шляху PTT навіть тоді, коли провайдер повертає MP3 або WebM
|
||||
- нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими нотатками
|
||||
- аудіо не у форматі Ogg, включно з виходом Microsoft Edge TTS у MP3/WebM, перекодовується за допомогою `ffmpeg` у 48 кГц mono Ogg/Opus перед доставкою як PTT
|
||||
- `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку та пригнічує повторне надсилання для тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp
|
||||
- відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання відео
|
||||
- підписи застосовуються до першого елемента медіа під час надсилання payload відповіді з кількома медіа, за винятком того, що PTT-голосові повідомлення надсилають аудіо першим і видимий текст окремо, оскільки клієнти WhatsApp ненадійно відображають підписи голосових повідомлень
|
||||
- джерелом медіа може бути HTTP(S), `file://` або локальні шляхи
|
||||
- підписи застосовуються до першого елемента медіа під час надсилання payload відповіді з кількома медіа, окрім того, що голосові нотатки PTT надсилають аудіо спочатку, а видимий текст окремо, оскільки клієнти WhatsApp не відображають підписи до голосових нотаток послідовно
|
||||
- джерелом медіа можуть бути HTTP(S), `file://` або локальні шляхи
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження розміру медіа та резервна поведінка">
|
||||
- обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
|
||||
- перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
|
||||
- зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб відповідати обмеженням
|
||||
- у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість того, щоб мовчки відкинути відповідь
|
||||
- зображення автоматично оптимізуються (перебір розміру/якості), щоб відповідати обмеженням
|
||||
- у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість тихого скидання відповіді
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Цитування у відповідях
|
||||
|
||||
WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керування здійснюється через `channels.whatsapp.replyToMode`.
|
||||
WhatsApp підтримує нативне цитування у відповідях, коли вихідні відповіді видимо цитують вхідне повідомлення. Це керується через `channels.whatsapp.replyToMode`.
|
||||
|
||||
| Значення | Поведінка |
|
||||
| ----------- | --------------------------------------------------------------------- |
|
||||
| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
|
||||
| `"first"` | Цитувати лише першу частину вихідної відповіді |
|
||||
| `"all"` | Цитувати кожну частину вихідної відповіді |
|
||||
| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, лишаючи негайні без цитування |
|
||||
| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування |
|
||||
|
||||
Типове значення — `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<id>.replyToMode`.
|
||||
|
||||
@ -421,14 +422,14 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
|
||||
`channels.whatsapp.reactionLevel` визначає, наскільки широко агент використовує emoji-реакції у WhatsApp:
|
||||
|
||||
| Рівень | Реакції підтвердження | Реакції, ініційовані агентом | Опис |
|
||||
| ------------- | --------------------- | ---------------------------- | ------------------------------------------------ |
|
||||
| `"off"` | Ні | Ні | Жодних реакцій |
|
||||
| `"ack"` | Так | Ні | Лише реакції підтвердження (отримання до відповіді) |
|
||||
| `"minimal"` | Так | Так (консервативно) | Підтвердження + реакції агента з консервативними вказівками |
|
||||
| `"extensive"` | Так | Так (заохочено) | Підтвердження + реакції агента із заохочувальними вказівками |
|
||||
| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис |
|
||||
| ------------ | ----------- | ---------------------------- | ------------------------------------------------ |
|
||||
| `"off"` | Ні | Ні | Жодних реакцій |
|
||||
| `"ack"` | Так | Ні | Лише ack-реакції (підтвердження до відповіді) |
|
||||
| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з консервативними вказівками |
|
||||
| `"extensive"`| Так | Так (заохочується) | Ack + реакції агента із заохочувальними вказівками |
|
||||
|
||||
Типове значення: `"minimal"`.
|
||||
Типово: `"minimal"`.
|
||||
|
||||
Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts.<id>.reactionLevel`.
|
||||
|
||||
@ -442,10 +443,10 @@ WhatsApp підтримує нативне цитування відповіде
|
||||
}
|
||||
```
|
||||
|
||||
## Реакції підтвердження
|
||||
## Реакції-підтвердження
|
||||
|
||||
WhatsApp підтримує негайні реакції підтвердження після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
|
||||
Реакції підтвердження обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
|
||||
WhatsApp підтримує негайні ack-реакції під час отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
|
||||
Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -464,8 +465,8 @@ WhatsApp підтримує негайні реакції підтверджен
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- надсилаються негайно після прийняття вхідного повідомлення (до відповіді)
|
||||
- помилки журналюються, але не блокують звичайну доставку відповіді
|
||||
- груповий режим `mentions` реагує на ходи, активовані згадкою; групова активація `always` працює як обхід цієї перевірки
|
||||
- збої записуються в журнал, але не блокують звичайну доставку відповіді
|
||||
- груповий режим `mentions` реагує на ходи, запущені згадкою; групова активація `always` працює як обхід цієї перевірки
|
||||
- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується)
|
||||
|
||||
## Кілька облікових записів і облікові дані
|
||||
@ -473,37 +474,37 @@ WhatsApp підтримує негайні реакції підтверджен
|
||||
<AccordionGroup>
|
||||
<Accordion title="Вибір облікового запису та типові значення">
|
||||
- ідентифікатори облікових записів беруться з `channels.whatsapp.accounts`
|
||||
- вибір типового облікового запису: `default`, якщо присутній, інакше перший налаштований ідентифікатор облікового запису (після сортування)
|
||||
- ідентифікатори облікових записів нормалізуються внутрішньо для пошуку
|
||||
- вибір типового облікового запису: `default`, якщо присутній, інакше перший налаштований ідентифікатор облікового запису (відсортований)
|
||||
- ідентифікатори облікових записів внутрішньо нормалізуються для пошуку
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Шляхи до облікових даних і сумісність із застарілими варіантами">
|
||||
<Accordion title="Шляхи до облікових даних і сумісність зі застарілими варіантами">
|
||||
- поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
|
||||
- резервний файл: `creds.json.bak`
|
||||
- застаріла типова автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрує для потоків типового облікового запису
|
||||
- застаріла типова автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрується для сценаріїв типового облікового запису
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Поведінка виходу">
|
||||
`openclaw channels logout --channel whatsapp [--account <id>]` очищає стан автентифікації WhatsApp для цього облікового запису.
|
||||
|
||||
У застарілих каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються.
|
||||
У каталогах застарілої автентифікації `oauth.json` зберігається, тоді як файли автентифікації Baileys видаляються.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Інструменти, дії та запис конфігурації
|
||||
## Інструменти, дії та записи конфігурації
|
||||
|
||||
- Підтримка інструментів агента включає дію реакції WhatsApp (`react`).
|
||||
- Обмеження дій:
|
||||
- `channels.whatsapp.actions.reactions`
|
||||
- `channels.whatsapp.actions.polls`
|
||||
- Запис конфігурації, ініційований каналом, увімкнений за замовчуванням (вимкнення через `channels.whatsapp.configWrites=false`).
|
||||
- Записи конфігурації, ініційовані каналом, увімкнено типово (вимкнення через `channels.whatsapp.configWrites=false`).
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Не пов’язано (потрібен QR)">
|
||||
Симптом: статус каналу показує, що зв’язок не встановлено.
|
||||
Симптом: статус каналу повідомляє, що канал не пов’язано.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -514,8 +515,12 @@ WhatsApp підтримує негайні реакції підтверджен
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Пов’язано, але відключено / цикл перепідключення">
|
||||
Симптом: пов’язаний обліковий запис із повторними відключеннями або спробами перепідключення.
|
||||
<Accordion title="Пов’язано, але відключено / цикл повторного підключення">
|
||||
Симптом: пов’язаний обліковий запис із повторюваними відключеннями або спробами повторного підключення.
|
||||
|
||||
Тихі облікові записи можуть залишатися підключеними довше за звичайний тайм-аут повідомлень; watchdog
|
||||
перезапускає з’єднання, коли зупиняється транспортна активність WhatsApp Web, сокет закривається або
|
||||
активність на рівні застосунку залишається тихою довше за розширене безпечне вікно.
|
||||
|
||||
Виправлення:
|
||||
|
||||
@ -524,14 +529,14 @@ WhatsApp підтримує негайні реакції підтверджен
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
За потреби повторно встановіть зв’язок через `channels login`.
|
||||
За потреби повторно пов’яжіть через `channels login`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Немає активного слухача під час надсилання">
|
||||
Вихідні надсилання швидко завершуються з помилкою, якщо для цільового облікового запису немає активного слухача Gateway.
|
||||
Вихідні надсилання завершуються з помилкою одразу, якщо для цільового облікового запису немає активного слухача Gateway.
|
||||
|
||||
Переконайтеся, що Gateway запущено та обліковий запис пов’язано.
|
||||
Переконайтеся, що Gateway запущено і обліковий запис пов’язано.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -541,13 +546,13 @@ WhatsApp підтримує негайні реакції підтверджен
|
||||
- `groupPolicy`
|
||||
- `groupAllowFrom` / `allowFrom`
|
||||
- записи allowlist у `groups`
|
||||
- перевірка згадок (`requireMention` + шаблони згадок)
|
||||
- дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` для кожної області
|
||||
- обмеження згадкою (`requireMention` + шаблони згадок)
|
||||
- дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тож зберігайте лише один `groupPolicy` на область
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Попередження про середовище виконання Bun">
|
||||
Для середовища виконання Gateway WhatsApp слід використовувати Node. Bun позначено як несумісний для стабільної роботи Gateway WhatsApp/Telegram.
|
||||
<Accordion title="Попередження середовища виконання Bun">
|
||||
Середовище виконання Gateway для WhatsApp має використовувати Node. Bun позначено як несумісне для стабільної роботи Gateway WhatsApp/Telegram.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -557,28 +562,28 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
|
||||
Ієрархія визначення для групових повідомлень:
|
||||
|
||||
Спочатку визначається ефективна мапа `groups`: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
|
||||
Спочатку визначається ефективна мапа `groups`: якщо обліковий запис має власний `groups`, він повністю замінює кореневу мапу `groups` (без deep merge). Потім пошук prompt виконується за єдиною результуючою мапою:
|
||||
|
||||
1. **Системний prompt для конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для груп** (`groups["*"].systemPrompt`): використовується, коли запис конкретної групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
1. **Системний prompt для конкретної групи** (`groups["<groupId>"].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` — порожній рядок (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Wildcard-системний prompt групи** (`groups["*"].systemPrompt`): використовується, коли запис конкретної групи повністю відсутній у мапі або коли він існує, але не має ключа `systemPrompt`.
|
||||
|
||||
Ієрархія визначення для прямих повідомлень:
|
||||
|
||||
Спочатку визначається ефективна мапа `direct`: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
|
||||
Спочатку визначається ефективна мапа `direct`: якщо обліковий запис має власний `direct`, він повністю замінює кореневу мапу `direct` (без deep merge). Потім пошук prompt виконується за єдиною результуючою мапою:
|
||||
|
||||
1. **Системний prompt для конкретного прямого чату** (`direct["<peerId>"].systemPrompt`): використовується, коли запис конкретного співрозмовника існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Системний prompt wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного співрозмовника повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
|
||||
1. **Системний prompt для конкретного прямого чату** (`direct["<peerId>"].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` — порожній рядок (`""`), wildcard пригнічується і системний prompt не застосовується.
|
||||
2. **Wildcard-системний prompt прямого чату** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не має ключа `systemPrompt`.
|
||||
|
||||
Примітка: `dms` залишається спрощеним контейнером перевизначень історії для окремих DM (`dms.<id>.historyLimit`); перевизначення prompt містяться в `direct`.
|
||||
Примітка: `dms` лишається спрощеним контейнером перевизначення історії для окремих DM (`dms.<id>.historyLimit`); перевизначення prompt живуть у `direct`.
|
||||
|
||||
**Відмінність від поведінки Telegram з кількома обліковими записами:** у Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для облікових записів, які не визначають власний `groups`, — щоб бот не отримував групові повідомлення для груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і кореневі `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні prompt для груп або прямих чатів на рівні облікового запису, визначайте повну мапу явно під кожним обліковим записом, а не покладайтеся на типові значення кореневого рівня.
|
||||
**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, які не мають власного `groups`, — щоб бот не отримував групові повідомлення для груп, до яких він не належить. WhatsApp не застосовує цей запобіжник: кореневі `groups` і кореневі `direct` завжди успадковуються обліковими записами, які не мають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні групові або прямі prompt для кожного облікового запису окремо, явно визначайте повну мапу в кожному обліковому записі, а не покладайтеся на кореневі типові значення.
|
||||
|
||||
Важлива поведінка:
|
||||
|
||||
- `channels.whatsapp.groups` — це і мапа конфігурації для окремих груп, і allowlist груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає, що «усі групи допущені» для цієї області.
|
||||
- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` для типового prompt. Натомість повторіть prompt у кожному явно внесеному до allowlist записі групи.
|
||||
- Допуск груп і авторизація відправників — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але саме по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як DM уже допущено через `dmPolicy` плюс `allowFrom` або правила pairing-store.
|
||||
- `channels.whatsapp.groups` — це і мапа конфігурації для окремих груп, і allowlist груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає «усі групи допущені» для цієї області.
|
||||
- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як типове значення prompt. Натомість повторіть prompt у кожному явно дозволеному записі групи.
|
||||
- Допуск груп і авторизація відправника — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
|
||||
- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як DM вже допущено через `dmPolicy` плюс `allowFrom` або правила pairing-store.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -587,29 +592,29 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
channels: {
|
||||
whatsapp: {
|
||||
groups: {
|
||||
// Використовуйте лише якщо всі групи мають бути допущені на кореневому рівні.
|
||||
// Застосовується до всіх облікових записів, які не визначають власну мапу groups.
|
||||
// Use only if all groups should be admitted at the root scope.
|
||||
// Applies to all accounts that do not define their own groups map.
|
||||
"*": { systemPrompt: "Типовий prompt для всіх груп." },
|
||||
},
|
||||
direct: {
|
||||
// Застосовується до всіх облікових записів, які не визначають власну мапу direct.
|
||||
// Applies to all accounts that do not define their own direct map.
|
||||
"*": { systemPrompt: "Типовий prompt для всіх прямих чатів." },
|
||||
},
|
||||
accounts: {
|
||||
work: {
|
||||
groups: {
|
||||
// Цей обліковий запис визначає власну groups, тому коренева groups повністю
|
||||
// замінюється. Щоб зберегти wildcard, явно визначте тут також "*".
|
||||
// This account defines its own groups, so root groups are fully
|
||||
// replaced. To keep a wildcard, define "*" explicitly here too.
|
||||
"120363406415684625@g.us": {
|
||||
requireMention: false,
|
||||
systemPrompt: "Зосереджуйся на керуванні проєктами.",
|
||||
systemPrompt: "Зосередься на керуванні проєктами.",
|
||||
},
|
||||
// Використовуйте лише якщо всі групи мають бути допущені в цьому обліковому записі.
|
||||
// Use only if all groups should be admitted in this account.
|
||||
"*": { systemPrompt: "Типовий prompt для робочих груп." },
|
||||
},
|
||||
direct: {
|
||||
// Цей обліковий запис визначає власну мапу direct, тому кореневі записи direct
|
||||
// повністю замінюються. Щоб зберегти wildcard, явно визначте тут також "*".
|
||||
// This account defines its own direct map, so root direct entries are
|
||||
// fully replaced. To keep a wildcard, define "*" explicitly here too.
|
||||
"+15551234567": { systemPrompt: "Prompt для конкретного робочого прямого чату." },
|
||||
"*": { systemPrompt: "Типовий prompt для робочих прямих чатів." },
|
||||
},
|
||||
@ -624,7 +629,7 @@ WhatsApp підтримує системні prompt у стилі Telegram дл
|
||||
|
||||
Основний довідник:
|
||||
|
||||
- [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp)
|
||||
- [Довідник конфігурації — WhatsApp](/uk/gateway/config-channels#whatsapp)
|
||||
|
||||
Ключові поля WhatsApp:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user