viberio 1.0.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- viberio-1.0.2/PKG-INFO +1182 -0
- viberio-1.0.2/README.md +1170 -0
- viberio-1.0.2/examples/echo_bot.py +48 -0
- viberio-1.0.2/pyproject.toml +21 -0
- viberio-1.0.2/src/viberio/__init__.py +24 -0
- viberio-1.0.2/src/viberio/_json.py +22 -0
- viberio-1.0.2/src/viberio/bot.py +269 -0
- viberio-1.0.2/src/viberio/client.py +407 -0
- viberio-1.0.2/src/viberio/events.py +196 -0
- viberio-1.0.2/src/viberio/exceptions.py +139 -0
- viberio-1.0.2/src/viberio/filters.py +50 -0
- viberio-1.0.2/src/viberio/messages.py +569 -0
- viberio-1.0.2/src/viberio/models.py +131 -0
- viberio-1.0.2/src/viberio/server.py +119 -0
- viberio-1.0.2/tests/test_all.py +395 -0
viberio-1.0.2/PKG-INFO
ADDED
|
@@ -0,0 +1,1182 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: viberio
|
|
3
|
+
Version: 1.0.2
|
|
4
|
+
Summary: Fast, typed, asyncio-native library for the Viber Bot REST API
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Requires-Dist: aiohttp>=3.9
|
|
7
|
+
Provides-Extra: dev
|
|
8
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
9
|
+
Provides-Extra: fast
|
|
10
|
+
Requires-Dist: orjson>=3.9; extra == 'fast'
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
|
|
13
|
+
# viberio: повна документація
|
|
14
|
+
|
|
15
|
+
Версія бібліотеки: **1.0.0** · Python **3.10+** · залежність: `aiohttp>=3.9` (необов'язково `orjson>=3.9`)
|
|
16
|
+
|
|
17
|
+
Це довідник по всій бібліотеці: архітектура, кожен клас і метод, поведінка за замовчуванням, ліміти, обробка помилок,
|
|
18
|
+
розгортання і діагностика. Усе, що описано нижче, перевірено за вихідним кодом у `src/viberio/`.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Зміст
|
|
23
|
+
|
|
24
|
+
1. [Огляд і архітектура](#1-огляд-і-архітектура)
|
|
25
|
+
2. [Встановлення](#2-встановлення)
|
|
26
|
+
3. [Швидкий старт](#3-швидкий-старт)
|
|
27
|
+
4. [Життєвий цикл запиту (від вебхука до відповіді)](#4-життєвий-цикл-запиту-від-вебхука-до-відповіді)
|
|
28
|
+
5. [`Bot`: роутер подій](#5-bot-роутер-подій)
|
|
29
|
+
6. [Події (`events`)](#6-події-events)
|
|
30
|
+
7. [Фільтри (`F`)](#7-фільтри-f)
|
|
31
|
+
8. [Повідомлення (`messages`)](#8-повідомлення-messages)
|
|
32
|
+
9. [Клавіатури і кнопки](#9-клавіатури-і-кнопки)
|
|
33
|
+
10. [Rich media і каруселі](#10-rich-media-і-каруселі)
|
|
34
|
+
11. [Платежі](#11-платежі)
|
|
35
|
+
12. [`ViberClient`: REST-клієнт](#12-viberclient-rest-клієнт)
|
|
36
|
+
13. [Мережа: таймаути, проксі, ретраї, конкурентність](#13-мережа-таймаути-проксі-ретраї-конкурентність)
|
|
37
|
+
14. [Моделі результатів](#14-моделі-результатів)
|
|
38
|
+
15. [Помилки і коди Viber](#15-помилки-і-коди-viber)
|
|
39
|
+
16. [Вебхук-сервер і інтеграція з фреймворками](#16-вебхук-сервер-і-інтеграція-з-фреймворками)
|
|
40
|
+
17. [Розгортання (nginx, systemd, HTTPS)](#17-розгортання-nginx-systemd-https)
|
|
41
|
+
18. [Безпека](#18-безпека)
|
|
42
|
+
19. [Ліміти Viber, які перевіряються локально](#19-ліміти-viber-які-перевіряються-локально)
|
|
43
|
+
20. [Діагностика проблем (troubleshooting)](#20-діагностика-проблем-troubleshooting)
|
|
44
|
+
21. [Тестування](#21-тестування)
|
|
45
|
+
22. [Відомі особливості та підводні камені](#22-відомі-особливості-та-підводні-камені)
|
|
46
|
+
23. [Довідник публічного API](#23-довідник-публічного-api)
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 1. Огляд і архітектура
|
|
51
|
+
|
|
52
|
+
Бібліотека складається з двох шарів, які можна використовувати разом або окремо:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
Viber Ваш код
|
|
56
|
+
│ POST /webhook (подія) │
|
|
57
|
+
▼ │
|
|
58
|
+
┌───────────────┐ handle_update(body, signature) │
|
|
59
|
+
│ server.py │ ─────────────────────────────────► │
|
|
60
|
+
│ (aiohttp app) │ │
|
|
61
|
+
└───────────────┘ │
|
|
62
|
+
│ │
|
|
63
|
+
▼ ▼
|
|
64
|
+
┌──────────────────────────────┐ ┌────────────────────────┐
|
|
65
|
+
│ Bot (bot.py) │ │ ViberClient (client.py)│
|
|
66
|
+
│ підпис → JSON → parse_event │ │ send_*, broadcast, │
|
|
67
|
+
│ dedup → middleware → │ ─────► │ set_webhook, ... │
|
|
68
|
+
│ фільтри → handler │ reply │ ретраї, ліміти, проксі│
|
|
69
|
+
└──────────────────────────────┘ └───────────┬────────────┘
|
|
70
|
+
│ HTTPS (опційно через проксі)
|
|
71
|
+
▼
|
|
72
|
+
https://chatapi.viber.com/pa
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
| Модуль | Призначення |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `client.py` | `ViberClient`: усі REST-ендпоінти, ретраї, rate limiter, проксі, чанкінг |
|
|
78
|
+
| `bot.py` | `Bot`: реєстрація обробників, диспетчеризація, дедуп, `handle_update` |
|
|
79
|
+
| `events.py` | Типізовані вхідні події та `parse_event` |
|
|
80
|
+
| `filters.py` | Фільтри для обробників (`F.text`, `F.message_type`, `F.users`, `F.not_`) |
|
|
81
|
+
| `messages.py` | Вихідні повідомлення, клавіатури, rich media, платежі, локальна валідація |
|
|
82
|
+
| `models.py` | Типізовані результати API (`SendResult`, `User`, `AccountInfo`, ...) |
|
|
83
|
+
| `exceptions.py` | Ієрархія помилок, відображення кодів Viber на класи |
|
|
84
|
+
| `server.py` | aiohttp-сервер вебхука: `create_app`, `serve`, `run_webhook` |
|
|
85
|
+
| `_json.py` | Швидкий JSON: `orjson`, якщо встановлено, інакше стандартний `json` |
|
|
86
|
+
|
|
87
|
+
**Принципи дизайну**
|
|
88
|
+
|
|
89
|
+
- **Повністю асинхронна** (asyncio + aiohttp). Усі обробники мають бути `async def`; інакше `Bot` кидає `TypeError` при реєстрації.
|
|
90
|
+
- **Не дублювати повідомлення.** `send_message` і `broadcast_message` не повторюються автоматично після таймауту або 5xx, бо невідомо, чи дійшов запит. Повторюються лише помилки з'єднання (запит точно не пішов) та rate limit для broadcast.
|
|
91
|
+
- **Вебхук завжди відповідає 200** (за замовчуванням). Інакше Viber може вимкнути вебхук після серії помилок.
|
|
92
|
+
- **Валідація до запиту.** Ліміти з документації Viber перевіряються локально й дають `ValidationError`, а не незрозумілу відповідь API.
|
|
93
|
+
- **`min_api_version` визначається автоматично** за використаними можливостями.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 2. Встановлення
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
cd viberio-lib
|
|
101
|
+
pip install -e ".[fast]" # fast = orjson (швидший JSON); без extras теж працює
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Extras у `pyproject.toml`:
|
|
105
|
+
|
|
106
|
+
| Extra | Що ставить |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `fast` | `orjson>=3.9` |
|
|
109
|
+
| `dev` | `pytest>=8` |
|
|
110
|
+
|
|
111
|
+
> **Важливо.** Якщо бачите `ImportError: cannot import name ... from 'viberio' (unknown location)`, пакет не встановлено,
|
|
112
|
+
> а Python підхопив порожню теку з такою самою назвою (namespace package). Виконайте `pip install -e .` і запускайте
|
|
113
|
+
> скрипти з іншої теки. Альтернатива без встановлення: `PYTHONPATH=viberio-lib/src python echo_bot.py`.
|
|
114
|
+
|
|
115
|
+
Для запуску потрібні:
|
|
116
|
+
- токен бота (`X-Viber-Auth-Token`) із адмін-панелі Viber;
|
|
117
|
+
- публічний **HTTPS**-URL із сертифікатом від довіреного CA (самопідписані не підтримуються Viber).
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 3. Швидкий старт
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
import asyncio, os
|
|
125
|
+
import viberio as vb
|
|
126
|
+
|
|
127
|
+
bot = vb.Bot(os.environ["VIBER_TOKEN"], name="My Bot")
|
|
128
|
+
|
|
129
|
+
@bot.on_conversation_started()
|
|
130
|
+
async def welcome(ev: vb.ConversationStarted):
|
|
131
|
+
return vb.TextMessage(f"Вітаю, {ev.user.name or 'друже'}!") # йде у HTTP-відповіді на callback
|
|
132
|
+
|
|
133
|
+
@bot.on_text(r"^(?:hi|привіт)")
|
|
134
|
+
async def hi(ev: vb.MessageEvent):
|
|
135
|
+
await ev.reply("Привіт! 👋")
|
|
136
|
+
|
|
137
|
+
@bot.on_message() # fallback: реєструйте ОСТАННІМ
|
|
138
|
+
async def fallback(ev: vb.MessageEvent):
|
|
139
|
+
await ev.reply(f"Ви написали: {ev.text}")
|
|
140
|
+
|
|
141
|
+
if __name__ == "__main__":
|
|
142
|
+
asyncio.run(vb.serve(bot, host="127.0.0.1", port=8080, path="/viber"))
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Далі, коли сервіс уже доступний ззовні по HTTPS, **один раз** зареєструйте вебхук (з окремого скрипта або консолі):
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
import asyncio, viberio as vb
|
|
149
|
+
async def main():
|
|
150
|
+
async with vb.ViberClient(TOKEN, sender_name="My Bot") as c:
|
|
151
|
+
print(await c.set_webhook("https://bot.example.com/viber", wait=60))
|
|
152
|
+
asyncio.run(main())
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`serve()` вебхук **не реєструє**: це свідомий вибір, щоб запуск процесу не мав побічних ефектів. Якщо потрібно реєструвати
|
|
156
|
+
автоматично, використовуйте `run_webhook(bot, webhook_url=...)` (див. [розділ 16](#16-вебхук-сервер-і-інтеграція-з-фреймворками)).
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## 4. Життєвий цикл запиту (від вебхука до відповіді)
|
|
161
|
+
|
|
162
|
+
`Bot.handle_update(body, signature)` виконує кроки в такому порядку:
|
|
163
|
+
|
|
164
|
+
1. **Підпис.** Якщо `verify_signatures=True` (за замовчуванням), перевіряється HMAC-SHA256 від сирого тіла з ключем = токен
|
|
165
|
+
бота, порівняно із заголовком `X-Viber-Content-Signature` (`hmac.compare_digest`). Невалідний або відсутній підпис →
|
|
166
|
+
подія **ігнорується** (не обробляється), у лог іде `webhook update ignored: invalid signature`.
|
|
167
|
+
2. **JSON.** Тіло має бути JSON-об'єктом. Інакше → `bad json`, ігнорується.
|
|
168
|
+
3. **`parse_event`** перетворює словник на типізований `Event`.
|
|
169
|
+
4. **Дедуп повідомлень.** Для `MessageEvent` з `message_token` ключ `("m", message_token, user_id)` запам'ятовується на 600 с
|
|
170
|
+
(до 20 000 записів). Повторний callback від Viber (якщо відповідь була повільною) відповідається 200 і не обробляється вдруге.
|
|
171
|
+
5. **Службові події.** `webhook` (перевірка при `set_webhook`) та невідомі події → просто 200.
|
|
172
|
+
6. **`conversation_started`** виконується **синхронно** з таймаутом `welcome_timeout` (4 с). Якщо обробник повернув
|
|
173
|
+
`Message`, він іде у тілі HTTP-відповіді як welcome-повідомлення. Якщо `dict`, відправляється як є. Інакше порожній 200.
|
|
174
|
+
7. **Усі інші події** запускаються у **фоні** (`asyncio.ensure_future`), а Viber одразу отримує 200. Тому повільні обробники
|
|
175
|
+
не блокують відповідь вебхуку.
|
|
176
|
+
|
|
177
|
+
Кожен виклик обробника проходить через `_safe_dispatch`: будь-який виняток (крім `CancelledError`) логується
|
|
178
|
+
(`handler failed for <EventClass>`), викликається `bot.on_error(event, exc)`, якщо задано, а процес продовжує працювати.
|
|
179
|
+
|
|
180
|
+
> Висновок для діагностики: помилка в `ev.reply(...)` (наприклад, `TransportError`) **не** впливає на HTTP-відповідь вебхуку.
|
|
181
|
+
> Вхідні повідомлення продовжують долітати, а у логах з'являється `handler failed`.
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 5. `Bot`: роутер подій
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
Bot(
|
|
189
|
+
token: str,
|
|
190
|
+
*,
|
|
191
|
+
name: str, # ім'я відправника, 1..28 символів
|
|
192
|
+
avatar: str | None = None, # URL аватара відправника
|
|
193
|
+
verify_signatures: bool = True,
|
|
194
|
+
always_ok: bool = True,
|
|
195
|
+
welcome_timeout: float = 4.0,
|
|
196
|
+
client: ViberClient | None = None, # готовий клієнт; тоді client_kwargs ігноруються
|
|
197
|
+
**client_kwargs, # передаються в ViberClient (timeout, proxy, ...)
|
|
198
|
+
)
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
| Параметр | Опис |
|
|
202
|
+
|---|---|
|
|
203
|
+
| `verify_signatures` | Перевіряти `X-Viber-Content-Signature`. Вимикайте лише в тестах. |
|
|
204
|
+
| `always_ok` | `True`: на будь-який вхід відповідь 200. `False`: строгі коди (403 для поганого підпису, 400 для битого JSON). |
|
|
205
|
+
| `welcome_timeout` | Скільки секунд чекати обробник `conversation_started`. У Viber на відповідь приблизно 4–5 с. |
|
|
206
|
+
| `client` | Передайте свій `ViberClient`, якщо треба спільна сесія/налаштування. |
|
|
207
|
+
| `**client_kwargs` | Усе з [розділу 12](#12-viberclient-rest-клієнт): `proxy`, `connect_timeout`, `timeout`, `max_retries` тощо. |
|
|
208
|
+
|
|
209
|
+
Атрибути: `bot.client` (`ViberClient`), `bot.on_error` (хук помилок), `bot.verify_signatures`, `bot.always_ok`, `bot.welcome_timeout`.
|
|
210
|
+
|
|
211
|
+
### 5.1 Реєстрація обробників
|
|
212
|
+
|
|
213
|
+
Усі декоратори мають параметр `block: bool = True` (див. [5.2](#52-порядок-і-блокування)).
|
|
214
|
+
|
|
215
|
+
| Декоратор | Подія | Примітка |
|
|
216
|
+
|---|---|---|
|
|
217
|
+
| `@bot.on_message(*filters)` | `MessageEvent` | Без фільтрів ловить **усі** повідомлення. |
|
|
218
|
+
| `@bot.on_text(pattern=None, *, equals=None, startswith=None, regex=None)` | `MessageEvent` (тип `text`) | Позиційний `pattern` = регулярний вираз (`re.search`, без урахування регістру). |
|
|
219
|
+
| `@bot.on_subscribed(*filters)` | `Subscribed` | Користувач підписався. |
|
|
220
|
+
| `@bot.on_unsubscribed(*filters)` | `Unsubscribed` | Відписався. |
|
|
221
|
+
| `@bot.on_conversation_started(*filters)` | `ConversationStarted` | Може **повернути** `Message` (welcome). |
|
|
222
|
+
| `@bot.on_delivered(*filters)` | `Delivered` | Лише `delivered`; `seen` сюди **не** потрапляє. |
|
|
223
|
+
| `@bot.on_seen(*filters)` | `Seen` | Прочитано. |
|
|
224
|
+
| `@bot.on_failed(*filters)` | `Failed` | Повідомлення не доставлено (`ev.desc`). |
|
|
225
|
+
| `@bot.on_payment_button(*filters)` | `PaymentButtonClicked` | Подія `client_status` (натиснуто «Оплатити»). |
|
|
226
|
+
|
|
227
|
+
Приклади:
|
|
228
|
+
|
|
229
|
+
```python
|
|
230
|
+
@bot.on_text(equals="📦 Каталог") # точний збіг без урахування регістру
|
|
231
|
+
@bot.on_text(startswith="/start")
|
|
232
|
+
@bot.on_text(regex=r"order\s+(\d+)") # ev.match.group(1)
|
|
233
|
+
@bot.on_text(r"^hi") # те саме, що regex=
|
|
234
|
+
@bot.on_message(vb.F.message_type("location"))
|
|
235
|
+
@bot.on_message(vb.F.users("U1", "U2"), vb.F.text(startswith="/admin")) # фільтри через «І»
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Обробник отримує подію і може повертати значення. Значення має сенс лише для `conversation_started`.
|
|
239
|
+
|
|
240
|
+
### 5.2 Порядок і блокування
|
|
241
|
+
|
|
242
|
+
Для кожного типу події обробники перебираються **у порядку реєстрації**. Для кожного перевіряються всі його фільтри (логічне «І»).
|
|
243
|
+
Якщо обробник спрацював і `block=True` (за замовчуванням), перебір **зупиняється**. Якщо `block=False`, перебір продовжується
|
|
244
|
+
наступним підходящим обробником.
|
|
245
|
+
|
|
246
|
+
Наслідки:
|
|
247
|
+
- **Загальний обробник (`@bot.on_message()` без фільтрів) реєструйте останнім**, інакше він перехопить усе.
|
|
248
|
+
- Для логування/метрик використовуйте `block=False` або middleware.
|
|
249
|
+
- Маршрутизація йде за **точним типом** класу події: `Seen` успадковує `Delivered`, але `on_delivered` його не отримає.
|
|
250
|
+
|
|
251
|
+
### 5.3 Middleware
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
@bot.middleware
|
|
255
|
+
async def timing(ev, call_next):
|
|
256
|
+
t = time.perf_counter()
|
|
257
|
+
try:
|
|
258
|
+
return await call_next(ev)
|
|
259
|
+
finally:
|
|
260
|
+
log.info("%s took %.3fs", type(ev).__name__, time.perf_counter() - t)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
- Middleware викликаються у порядку реєстрації (перший зареєстрований найзовнішній).
|
|
264
|
+
- Щоб відхилити подію, не викликайте `call_next`.
|
|
265
|
+
- Результат `call_next` треба повертати, інакше `conversation_started` втратить welcome-повідомлення.
|
|
266
|
+
- Middleware обгортає **кожну** подію, включно з `Delivered`/`Seen`.
|
|
267
|
+
|
|
268
|
+
### 5.4 Обробка помилок
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
async def on_err(ev, exc):
|
|
272
|
+
log.error("помилка в %s: %r", type(ev).__name__, exc)
|
|
273
|
+
bot.on_error = on_err # може бути sync або async
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Хук викликається після логування `handler failed`. Помилка всередині хука теж перехоплюється (`on_error hook failed`).
|
|
277
|
+
|
|
278
|
+
### 5.5 Інші методи `Bot`
|
|
279
|
+
|
|
280
|
+
| Метод | Опис |
|
|
281
|
+
|---|---|
|
|
282
|
+
| `await bot.handle_update(body, signature)` | Точка входу для будь-якого веб-фреймворку; повертає `UpdateResult`. |
|
|
283
|
+
| `await bot.process(payload_dict)` | Диспетчеризує вже розібраний словник синхронно (зручно в тестах, у консьюмерах черг). |
|
|
284
|
+
| `await bot.dispatch(event)` | Middleware + обробники для вже створеної події. |
|
|
285
|
+
| `await bot.close(drain_timeout=10.0)` | Чекає завершення фонових обробників (до `drain_timeout`), потім закриває HTTP-сесію. |
|
|
286
|
+
| `async with Bot(...) as bot:` | Те саме через контекстний менеджер. |
|
|
287
|
+
|
|
288
|
+
`UpdateResult(status, body, reason)`: що відповісти Viber. `.json()` повертає байти тіла відповіді
|
|
289
|
+
(`{"status":0,"status_message":"ok"}`, якщо `body` порожнє). `reason` пояснює, чому подію проігноровано (для логів/метрик).
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## 6. Події (`events`)
|
|
294
|
+
|
|
295
|
+
Усі події успадковують `Event` (dataclass, `kw_only`). Спільні поля:
|
|
296
|
+
|
|
297
|
+
| Поле | Тип | Опис |
|
|
298
|
+
|---|---|---|
|
|
299
|
+
| `timestamp` | `int` | Час події (мс, як у Viber) |
|
|
300
|
+
| `message_token` | `int \| None` | Токен повідомлення |
|
|
301
|
+
| `raw` | `dict` | Сирий JSON події |
|
|
302
|
+
| `bot` | `Bot` | Інжектується при диспетчеризації |
|
|
303
|
+
| `match` | `re.Match \| None` | Результат regex-фільтра |
|
|
304
|
+
| `user_id` | `str \| None` | Властивість: ID користувача (залежить від типу) |
|
|
305
|
+
|
|
306
|
+
### `await event.reply(message, **kw)`
|
|
307
|
+
|
|
308
|
+
Надсилає повідомлення користувачеві, що викликав подію.
|
|
309
|
+
|
|
310
|
+
- `message`: рядок (стає `TextMessage`) або об'єкт `Message`.
|
|
311
|
+
- `keyboard=`: клавіатура. Для рядка створюється `TextMessage(text, keyboard=...)`. Для готового `Message` клавіатура
|
|
312
|
+
**присвоюється** `message.keyboard` (мутація об'єкта!); якщо тип не підтримує клавіатуру, `TypeError`.
|
|
313
|
+
- Решта `**kw` (`sender`, `tracking_data`, `min_api_version`) передаються в `ViberClient.send`.
|
|
314
|
+
- `RuntimeError`, якщо подія не прив'язана до бота або в неї немає користувача.
|
|
315
|
+
|
|
316
|
+
### Типи подій
|
|
317
|
+
|
|
318
|
+
| Клас | `event` у Viber | Додаткові поля | `user_id` |
|
|
319
|
+
|---|---|---|---|
|
|
320
|
+
| `MessageEvent` | `message` | `sender: User`, `message: IncomingMessage`, `.text` | `sender.id` |
|
|
321
|
+
| `Subscribed` | `subscribed` | `user: User` | `user.id` |
|
|
322
|
+
| `Unsubscribed` | `unsubscribed` | `id: str` | `id` |
|
|
323
|
+
| `ConversationStarted` | `conversation_started` | `user`, `type` (`"open"`), `context`, `subscribed: bool` | `user.id` |
|
|
324
|
+
| `Delivered` | `delivered` | `id` | `id` |
|
|
325
|
+
| `Seen` (наслідує `Delivered`) | `seen` | `id` | `id` |
|
|
326
|
+
| `Failed` | `failed` | `id`, `desc` | `id` |
|
|
327
|
+
| `PaymentButtonClicked` | `client_status` | `user`, `status: dict`, `chat_hostname`, `.tracking_data` | `user.id` |
|
|
328
|
+
| `WebhookVerified` | `webhook` | — | `None` |
|
|
329
|
+
| `UnknownEvent` | будь-що інше | `event: str` | `None` |
|
|
330
|
+
|
|
331
|
+
`WebhookVerified` і `UnknownEvent` не доходять до обробників: `handle_update` одразу відповідає 200.
|
|
332
|
+
|
|
333
|
+
### `IncomingMessage`
|
|
334
|
+
|
|
335
|
+
Поля: `type`, `text`, `media`, `thumbnail`, `file_name`, `size`, `duration`, `contact` (dict), `location` (dict `lat`/`lon`),
|
|
336
|
+
`sticker_id`, `tracking_data`, `raw`. Конструюється через `IncomingMessage.from_dict`.
|
|
337
|
+
|
|
338
|
+
Типові значення `type`: `text`, `picture`, `video`, `file`, `contact`, `location`, `url`, `sticker`.
|
|
339
|
+
|
|
340
|
+
### `User`
|
|
341
|
+
|
|
342
|
+
`id, name, avatar, country, language, api_version, primary_device_os, viber_version, mcc, mnc, device_type`. Усі, крім `id`, можуть бути `None`
|
|
343
|
+
(Viber надсилає імена/фото лише якщо при `set_webhook` вказано `send_name=True`/`send_photo=True`).
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## 7. Фільтри (`F`)
|
|
348
|
+
|
|
349
|
+
`from viberio import F` (це модуль `filters`). Фільтр = функція `(event) -> bool | re.Match | Awaitable[...]`. Можна писати власні,
|
|
350
|
+
у тому числі `async`.
|
|
351
|
+
|
|
352
|
+
| Фільтр | Опис |
|
|
353
|
+
|---|---|
|
|
354
|
+
| `F.text(equals=, startswith=, regex=, ignore_case=True)` | Лише текстові повідомлення. Рівно один із `equals`/`startswith`/`regex` (пріоритет: `equals` → `startswith` → `regex`). Без аргументів = будь-який текст. `regex` використовує `re.search`, збіг кладеться в `ev.match`. |
|
|
355
|
+
| `F.message_type(*types)` | `message.type` входить у набір (`"picture"`, `"location"`, ...). |
|
|
356
|
+
| `F.users(*ids)` | `ev.user_id` у наборі (зручно для адміністраторів). |
|
|
357
|
+
| `F.not_(f)` | Інвертує фільтр (результат — `async`-функція). |
|
|
358
|
+
|
|
359
|
+
Власний фільтр:
|
|
360
|
+
|
|
361
|
+
```python
|
|
362
|
+
def is_admin(ev): # sync
|
|
363
|
+
return ev.user_id in ADMINS
|
|
364
|
+
|
|
365
|
+
async def is_blocked(ev): # async
|
|
366
|
+
return await db.is_blocked(ev.user_id)
|
|
367
|
+
|
|
368
|
+
@bot.on_message(is_admin, F.not_(is_blocked))
|
|
369
|
+
async def h(ev): ...
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Фільтр, що повертає `re.Match`, автоматично записується в `ev.match`.
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## 8. Повідомлення (`messages`)
|
|
377
|
+
|
|
378
|
+
Усі типи успадковують `Message` (dataclass, `kw_only` для базових полів):
|
|
379
|
+
|
|
380
|
+
| Поле | Опис |
|
|
381
|
+
|---|---|
|
|
382
|
+
| `tracking_data` | До 4000 символів; Viber поверне це значення разом з відповіддю користувача |
|
|
383
|
+
| `keyboard` | `Keyboard` або `None` |
|
|
384
|
+
| `min_api_version` | Явне значення; інакше обчислюється автоматично |
|
|
385
|
+
|
|
386
|
+
| Клас | Обов'язкові поля | Перевірки |
|
|
387
|
+
|---|---|---|
|
|
388
|
+
| `TextMessage(text)` | `text` | не порожній, ≤ 7000 символів |
|
|
389
|
+
| `PictureMessage(media, text="", thumbnail=None)` | `media` | URL закінчується на `.jpeg/.jpg/.png/.gif`; `text` ≤ 512 |
|
|
390
|
+
| `VideoMessage(media, size, thumbnail=None, duration=None)` | `media`, `size` | `.mp4`; `size` ≤ 26 МБ (27 262 976 байт); `duration` 0..180 с |
|
|
391
|
+
| `FileMessage(media, size, file_name)` | усі три | `size` ≤ 50 МБ; `file_name` ≤ 256 і має розширення; заборонені розширення (`.exe`, `.bat`, `.apk`, ...) |
|
|
392
|
+
| `ContactMessage(name, phone_number)` | обидва | ім'я ≤ 28; телефон `^\+?\d{1,17}$`, ≤ 18 |
|
|
393
|
+
| `LocationMessage(lat, lon)` | обидва | lat −90..90, lon −180..180 |
|
|
394
|
+
| `UrlMessage(media)` | `media` | `http(s)://`, ≤ 2000 символів |
|
|
395
|
+
| `StickerMessage(sticker_id)` | `sticker_id` | приводиться до `int` |
|
|
396
|
+
| `RichMediaMessage(rich_media, alt_text=None)` | `rich_media` | див. [розділ 10](#10-rich-media-і-каруселі); базова версія API 2 |
|
|
397
|
+
| `PaymentMessage(payment)` | `payment` | див. [розділ 11](#11-платежі); версія API 10 |
|
|
398
|
+
|
|
399
|
+
Додатково: для будь-якого повідомлення сумарний розмір JSON має бути ≤ **30 КБ** (`ValidationError` до відправки).
|
|
400
|
+
|
|
401
|
+
### Автоматичний `min_api_version`
|
|
402
|
+
|
|
403
|
+
`required_api_version()` = максимум із:
|
|
404
|
+
- базової версії типу (1; rich media 2; payment 10);
|
|
405
|
+
- версії клавіатури: 3 (4, якщо задано `ButtonsGroupColumns/Rows` або `InputFieldState`);
|
|
406
|
+
- версій кнопок: 3 для `InternalBrowser`; 4 для `TextPaddings` та тегів `<s>`/`<font size`; 6 для `TextShouldFit`, `Map`, `Frame`, `MediaPlayer`, `send-to-bot`/`ActionReplyData`.
|
|
407
|
+
|
|
408
|
+
Значення вказується у payload як `min_api_version`. Користувачі зі старішим клієнтом Viber повідомлення з вищою версією не отримають.
|
|
409
|
+
|
|
410
|
+
### Мутація повідомлень
|
|
411
|
+
|
|
412
|
+
`ViberClient.build_payload` **змінює** переданий об'єкт: якщо передано `tracking_data=` або `min_api_version=`, вони записуються в `message`.
|
|
413
|
+
`Event.reply(..., keyboard=...)` теж присвоює `message.keyboard`. Тому не використовуйте один об'єкт `Message` повторно для різних
|
|
414
|
+
користувачів із різним `tracking_data`: створюйте новий.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## 9. Клавіатури і кнопки
|
|
419
|
+
|
|
420
|
+
### `Button`
|
|
421
|
+
|
|
422
|
+
Dataclass; усі поля необов'язкові, `None` не потрапляє в JSON. Імена перетворюються з `snake_case` у `PascalCase`
|
|
423
|
+
(із винятками `OpenURLType`, `OpenURLMediaType`, `ThumbnailURL`, `ActionPredefinedURL`).
|
|
424
|
+
|
|
425
|
+
Ключові поля: `columns` (1..6), `rows` (1..7), `bg_color` (`#rgb`/`#rrggbb`), `silent`, `action_type`
|
|
426
|
+
(`reply`, `open-url`, `location-picker`, `share-phone`, `buy`, `none`), `action_body`, `text` (HTML-розмітка Viber), `text_v_align`,
|
|
427
|
+
`text_h_align`, `text_paddings` (4 числа 0..12), `text_opacity` (0..100), `text_size` (`small|medium|regular|large`), `image`,
|
|
428
|
+
`bg_media`, `bg_media_type`, `bg_media_scale_type`/`image_scale_type` (`crop|fill|fit`), `bg_loop`, `open_url_type`,
|
|
429
|
+
`open_url_media_type`, `text_bg_gradient_color`, `text_should_fit`, `internal_browser`, `map`, `frame`, `mediaplayer`.
|
|
430
|
+
|
|
431
|
+
Конструктори:
|
|
432
|
+
|
|
433
|
+
| Метод | Результат |
|
|
434
|
+
|---|---|
|
|
435
|
+
| `Button.reply(text, body=None, *, raw_html=False, **kw)` | `ActionType=reply`; `body` за замовчуванням = `text`; текст екранується (`html.escape`), якщо не `raw_html=True` |
|
|
436
|
+
| `Button.url(text, url, *, raw_html=False, **kw)` | `ActionType=open-url` |
|
|
437
|
+
| `Button.location_picker(text, **kw)` | `location-picker`, body `location` |
|
|
438
|
+
| `Button.share_phone(text, **kw)` | `share-phone`, body `phone` |
|
|
439
|
+
|
|
440
|
+
> **Екранування.** `Button.reply("A & B")` надішле `A & B`. Якщо потрібна HTML-розмітка Viber (`<b>`, `<font color=...>`),
|
|
441
|
+
> передайте `raw_html=True` і самі відповідайте за коректність. Для `location_picker`/`share_phone` екранування завжди увімкнено.
|
|
442
|
+
|
|
443
|
+
Валідація `Button.validate()`: діапазони `columns/rows/opacity/paddings`, формат кольорів, допустимі `action_type`/`text_size`/scale,
|
|
444
|
+
обов'язковий `action_body` (крім `buy`), для `open-url` значення має починатися з `http://` або `https://`.
|
|
445
|
+
|
|
446
|
+
Допоміжні типи: `InternalBrowser` (`custom_title` ≤ 15), `MapLocation(latitude, longitude)`, `Frame` (`border_width` 0..10,
|
|
447
|
+
`corner_radius` 0..10, `border_color`), `MediaPlayer(title, subtitle, thumbnail_url, loop)`.
|
|
448
|
+
|
|
449
|
+
### `Keyboard`
|
|
450
|
+
|
|
451
|
+
```python
|
|
452
|
+
Keyboard(buttons, bg_color=None, default_height=None, custom_default_height=None, # 40..70
|
|
453
|
+
height_scale=None, # 20..100
|
|
454
|
+
buttons_group_columns=None, # 1..6 (API 4)
|
|
455
|
+
buttons_group_rows=None, # 1..2 (API 4)
|
|
456
|
+
input_field_state=None) # regular | minimized | hidden (API 4)
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
Обмеження: 1..24 кнопки.
|
|
460
|
+
|
|
461
|
+
`Keyboard.from_rows(rows, **kw)`: зручний конструктор. Кожен рядок містить 1..6 елементів (`str` або `Button`), ширина рівномірно:
|
|
462
|
+
`columns = 6 // len(row)` (якщо в кнопки вже є `columns`, воно зберігається). Рядки-`str` стають `Button.reply`.
|
|
463
|
+
|
|
464
|
+
```python
|
|
465
|
+
MENU = vb.Keyboard.from_rows([
|
|
466
|
+
["📦 Каталог", "ℹ️ Допомога"], # дві кнопки по 3 колонки
|
|
467
|
+
[vb.Button.share_phone("📞 Надіслати номер")], # одна на 6 колонок
|
|
468
|
+
[vb.Button.url("Сайт", "https://example.com")],
|
|
469
|
+
])
|
|
470
|
+
await ev.reply("Меню:", keyboard=MENU)
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## 10. Rich media і каруселі
|
|
476
|
+
|
|
477
|
+
### `Card` і `RichMedia.carousel`
|
|
478
|
+
|
|
479
|
+
```python
|
|
480
|
+
cards = [vb.Card(f"Товар {i}", image=f"https://example.com/img/{i}.jpg", subtitle="Опис", price="₴199",
|
|
481
|
+
button_text="Детальніше", action_body=f"https://example.com/p/{i}") for i in range(1, 4)]
|
|
482
|
+
await bot.client.send_rich_media(user_id, vb.RichMedia.carousel(cards), alt_text="Каталог")
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
`Card(title, image=None, subtitle=None, price=None, button_text="Open", action_type="open-url", action_body="",
|
|
486
|
+
image_url_action=None, button_bg_color="#8367db")`. Заголовок/опис/ціна екрануються. Картка складається з кнопок: зображення
|
|
487
|
+
(`rows = 3` при групі з 6 рядків), текстовий блок (2 рядки), кнопка-дія (1 рядок).
|
|
488
|
+
|
|
489
|
+
`RichMedia.carousel(cards, bg_color="#FFFFFF")`: від 1 до 6 карток; параметри групи 6 колонок × 6 рядків.
|
|
490
|
+
|
|
491
|
+
### Ручний `RichMedia`
|
|
492
|
+
|
|
493
|
+
`RichMedia(buttons, buttons_group_columns=6, buttons_group_rows=7, bg_color="#FFFFFF")`. Перевірки: кожна кнопка вміщується у групу
|
|
494
|
+
(`columns ≤ ButtonsGroupColumns`, `rows ≤ ButtonsGroupRows`), кількість карток (сума `rows` / `ButtonsGroupRows`, з округленням вгору) має бути 1..6.
|
|
495
|
+
Мінімальна версія API: 2 (або більше залежно від кнопок).
|
|
496
|
+
|
|
497
|
+
---
|
|
498
|
+
|
|
499
|
+
## 11. Платежі
|
|
500
|
+
|
|
501
|
+
Лише для українського ринку, API **v10+**. Кнопка оплати діє 15 хвилин.
|
|
502
|
+
|
|
503
|
+
```python
|
|
504
|
+
pay = vb.Payment.liqpay(type="GooglePay", total_price=199.0, currency_code="UAH",
|
|
505
|
+
merchant_id="...", data="...", signature="...", description="Замовлення №1")
|
|
506
|
+
await bot.client.send_payment(user_id, pay)
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
| Конструктор | Шлюз |
|
|
510
|
+
|---|---|
|
|
511
|
+
| `Payment.liqpay(type, total_price, currency_code, merchant_id, data, signature, payee_id=None, url=..., description=None)` | LiqPay |
|
|
512
|
+
| `Payment.portmone(type, total_price, currency_code, merchant_id, login, password, payee_id=None, url=..., description=None)` | Portmone |
|
|
513
|
+
| `Payment.ipay(type, total_price, currency_code, merchant_id, sub_merchant_id, auth_salt, auth_sign, transactions=None, url=..., description=None)` | iPay |
|
|
514
|
+
|
|
515
|
+
Перевірки `Payment.to_dict()`: `type` ∈ {`GooglePay`, `ApplePay`}; `total_price > 0`; `currency_code` = три великі літери (ISO 4217);
|
|
516
|
+
параметри непорожні. Подію натискання «Оплатити» ловить `@bot.on_payment_button()`.
|
|
517
|
+
|
|
518
|
+
---
|
|
519
|
+
|
|
520
|
+
## 12. `ViberClient`: REST-клієнт
|
|
521
|
+
|
|
522
|
+
```python
|
|
523
|
+
ViberClient(
|
|
524
|
+
token: str,
|
|
525
|
+
*,
|
|
526
|
+
sender_name: str, # 1..28 символів
|
|
527
|
+
sender_avatar: str | None = None,
|
|
528
|
+
base_url: str = "https://chatapi.viber.com/pa",
|
|
529
|
+
timeout: float = 15.0, # загальний таймаут запиту, с
|
|
530
|
+
connect_timeout: float | None = None, # таймаут встановлення з'єднання, с
|
|
531
|
+
proxy: str | None = None,
|
|
532
|
+
proxy_auth: aiohttp.BasicAuth | None = None,
|
|
533
|
+
trust_env: bool = False,
|
|
534
|
+
max_retries: int = 3,
|
|
535
|
+
backoff: float = 0.5,
|
|
536
|
+
max_concurrency: int = 64,
|
|
537
|
+
broadcast_rate: tuple[int, float] = (500, 10.0), # 500 запитів / 10 с
|
|
538
|
+
session: aiohttp.ClientSession | None = None,
|
|
539
|
+
account_info_method: str = "POST",
|
|
540
|
+
)
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
| Параметр | Опис |
|
|
544
|
+
|---|---|
|
|
545
|
+
| `timeout` | `ClientTimeout(total=...)`: весь запит, включно з підключенням до проксі, TLS і читанням відповіді. |
|
|
546
|
+
| `connect_timeout` | `ClientTimeout(sock_connect=...)`: лише встановлення TCP-з'єднання. Таймаут тут безпечно повторюється (див. [розділ 13](#13-мережа-таймаути-проксі-ретраї-конкурентність)). |
|
|
547
|
+
| `proxy` | URL HTTP-проксі для вихідних запитів: `http://host:port` або `http://user:pass@host:port`. |
|
|
548
|
+
| `proxy_auth` | `aiohttp.BasicAuth` для проксі, якщо логін/пароль не вписано в URL. |
|
|
549
|
+
| `trust_env` | Враховувати `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` та `~/.netrc`. |
|
|
550
|
+
| `max_retries` | Кількість повторів **після** першої спроби (усього до `max_retries + 1` спроб). |
|
|
551
|
+
| `backoff` | База експоненційної затримки: `min(backoff * 2**attempt, 10) * (0.5 + random())`. |
|
|
552
|
+
| `max_concurrency` | Семафор одночасних запитів. |
|
|
553
|
+
| `broadcast_rate` | `(rate, per)`: ковзне вікно лімітера для `broadcast_message`. |
|
|
554
|
+
| `session` | Власна `aiohttp.ClientSession`. Тоді `timeout`, `connect_timeout`, `trust_env` і налаштування конектора **ігноруються** (використовуються налаштування вашої сесії), а `proxy`/`proxy_auth` передаються в кожен запит і працюють. Закривати таку сесію маєте ви. |
|
|
555
|
+
| `account_info_method` | `"POST"` (за замовчуванням) або `"GET"` для `get_account_info`. |
|
|
556
|
+
|
|
557
|
+
Життєвий цикл: `async with ViberClient(...) as c:` або `await c.close()`. Сесія створюється лениво при першому запиті
|
|
558
|
+
(`TCPConnector(limit=100, ttl_dns_cache=300, enable_cleanup_closed=True)`).
|
|
559
|
+
|
|
560
|
+
### 12.1 Вебхук
|
|
561
|
+
|
|
562
|
+
**`await set_webhook(url, event_types=None, *, send_name=None, send_photo=None, wait=None, wait_interval=3.0) -> list[str]`**
|
|
563
|
+
|
|
564
|
+
- `url` **мусить** починатися з `https://`, інакше `ValidationError`.
|
|
565
|
+
- `event_types=None`: параметр не надсилається, активні всі події. `[]`: лише обов'язкові (`message`, `subscribed`, `unsubscribed`).
|
|
566
|
+
Інакше список назв: `"delivered"`, `"seen"`, `"failed"`, `"conversation_started"`, `"client_status"`.
|
|
567
|
+
- `send_name`/`send_photo`: чи отримувати ім'я та фото користувача в подіях.
|
|
568
|
+
- `wait`: **скільки секунд повторювати**, поки ваш сервіс не почне відповідати. Під час `set_webhook` Viber сам звертається до URL;
|
|
569
|
+
якщо сервіс іще не готовий, повертається `status=1`. З `wait=60` бібліотека повторює кожні `wait_interval` секунд.
|
|
570
|
+
- Повертає список активних типів подій.
|
|
571
|
+
|
|
572
|
+
**`await remove_webhook()`**: знімає вебхук (одночасно вимикає розмови 1-на-1).
|
|
573
|
+
|
|
574
|
+
### 12.2 Акаунт і користувачі
|
|
575
|
+
|
|
576
|
+
| Метод | Опис |
|
|
577
|
+
|---|---|
|
|
578
|
+
| `get_account_info() -> AccountInfo` | Інформація про акаунт бота. |
|
|
579
|
+
| `get_user_details(user_id) -> User` | Деталі підписника. Viber дозволяє **2 запити на 12 годин** на користувача. |
|
|
580
|
+
| `get_online(user_ids) -> list[OnlineStatus]` | Статус онлайн; дедуплікація, авто-чанки по 100, чанки паралельно. |
|
|
581
|
+
|
|
582
|
+
### 12.3 Надсилання
|
|
583
|
+
|
|
584
|
+
Усі методи надсилання повертають `SendResult` і приймають `**kw`: `sender`, `tracking_data`, `min_api_version`.
|
|
585
|
+
|
|
586
|
+
| Метод | Еквівалент |
|
|
587
|
+
|---|---|
|
|
588
|
+
| `send(receiver, message)` | Базовий. Будь-який `Message`. |
|
|
589
|
+
| `send_messages(receiver, messages)` | Послідовно, зберігаючи порядок; повертає `list[SendResult]`. |
|
|
590
|
+
| `send_text(receiver, text, *, keyboard=None)` | `TextMessage` |
|
|
591
|
+
| `send_picture(receiver, media, text="", *, thumbnail=None, keyboard=None)` | `PictureMessage` |
|
|
592
|
+
| `send_video(receiver, media, size, *, thumbnail=None, duration=None, keyboard=None)` | `VideoMessage` |
|
|
593
|
+
| `send_file(receiver, media, size, file_name, *, keyboard=None)` | `FileMessage` |
|
|
594
|
+
| `send_contact(receiver, name, phone_number)` | `ContactMessage` |
|
|
595
|
+
| `send_location(receiver, lat, lon)` | `LocationMessage` |
|
|
596
|
+
| `send_url(receiver, url)` | `UrlMessage` |
|
|
597
|
+
| `send_sticker(receiver, sticker_id)` | `StickerMessage` |
|
|
598
|
+
| `send_rich_media(receiver, rich_media, *, alt_text=None)` | `RichMediaMessage` |
|
|
599
|
+
| `send_payment(receiver, payment)` | `PaymentMessage` |
|
|
600
|
+
|
|
601
|
+
`build_payload(message, *, receiver=None, sender=None, tracking_data=None, min_api_version=None) -> dict`: повне тіло `send_message`.
|
|
602
|
+
Без `receiver` це валідне тіло welcome-повідомлення. Перевіряє `sender.name` (1..28).
|
|
603
|
+
|
|
604
|
+
### 12.4 Розсилка
|
|
605
|
+
|
|
606
|
+
```python
|
|
607
|
+
res = await client.broadcast(user_ids, vb.TextMessage("Акція!"), raise_on_error=False)
|
|
608
|
+
print(res.total, res.delivered_count, res.ok)
|
|
609
|
+
for f in res.failed: print(f.receiver, f.status, f.status_message) # помилки по окремих отримувачах
|
|
610
|
+
for ids, err in res.errors: print(len(ids), err) # впали цілі чанки
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
- Дедуплікація отримувачів зі збереженням порядку; чанки по **300**; чанки виконуються паралельно через лімітер 500/10 с.
|
|
614
|
+
- Помилка одного чанка **не зупиняє** інші: вона потрапляє в `result.errors` як `(список_id, виняток)`.
|
|
615
|
+
- `retry_on_rate_limit=True` для розсилки: при 429/коді 12 чекає `Retry-After` (або backoff) і повторює.
|
|
616
|
+
- `raise_on_error=True`: перша помилка чанка піднімається одразу; якщо були `failed`, піднімається `APIError(19, ...)`.
|
|
617
|
+
- Ретраї після таймауту/5xx **не виконуються** (див. розділ 13).
|
|
618
|
+
|
|
619
|
+
---
|
|
620
|
+
|
|
621
|
+
## 13. Мережа: таймаути, проксі, ретраї, конкурентність
|
|
622
|
+
|
|
623
|
+
### 13.1 Матриця ретраїв
|
|
624
|
+
|
|
625
|
+
| Ситуація | Що викидається | `maybe_delivered` | Ретраїться? |
|
|
626
|
+
|---|---|---|---|
|
|
627
|
+
| Не вдалося з'єднатися (`ClientConnectorError`, у т. ч. відмова/невідомий хост/проксі недоступний) | `TransportError("connection failed: ...")` | `False` | **Так** (для всіх запитів) |
|
|
628
|
+
| Таймаут на етапі з'єднання (`connect_timeout`, aiohttp ≥ 3.10) | `TransportError("connect timeout: ...")` | `False` | **Так** (для всіх запитів) |
|
|
629
|
+
| Загальний таймаут (`timeout`) або інша `ClientError` | `TransportError("request failed: ...")` | `True` | Лише ідемпотентні запити |
|
|
630
|
+
| HTTP 5xx | `TransportError("HTTP 5xx")` | `True` | Лише ідемпотентні запити |
|
|
631
|
+
| Невалідний JSON у відповіді | `TransportError("invalid JSON in response")` | `True` | Лише ідемпотентні запити |
|
|
632
|
+
| HTTP 429 / код 12 | `RateLimitError` | — | Лише якщо `retry_on_rate_limit` (розсилка) |
|
|
633
|
+
| `status != 0` у відповіді | відповідний `APIError` | — | Ні |
|
|
634
|
+
|
|
635
|
+
Ідемпотентні: `set_webhook`, `get_*`. **Неідемпотентні** (`idempotent=False`): `send_message`, `broadcast_message`.
|
|
636
|
+
|
|
637
|
+
Затримка між спробами: `min(backoff * 2**attempt, 10) * (0.5 + random())`, а для rate limit береться `Retry-After`.
|
|
638
|
+
|
|
639
|
+
### 13.2 Чому `TimeoutError` при `ev.reply(...)` не повторюється
|
|
640
|
+
|
|
641
|
+
Загальний таймаут (`timeout=15`) не дозволяє відрізнити «не підключилися» від «підключилися, але не дочекалися відповіді».
|
|
642
|
+
Тому `TransportError(maybe_delivered=True)` для `send_message` піднімається одразу, без повтору (щоб користувач не отримав дублікат).
|
|
643
|
+
|
|
644
|
+
Щоб таймаут **на етапі з'єднання** повторювався автоматично, задайте `connect_timeout`:
|
|
645
|
+
|
|
646
|
+
```python
|
|
647
|
+
bot = vb.Bot(TOKEN, name="Bot", timeout=30, connect_timeout=10)
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
Якщо з'єднання не встановилося за 10 с, aiohttp викидає `ConnectionTimeoutError`, бібліотека кидає
|
|
651
|
+
`TransportError(maybe_delivered=False)` і виконує повтор із backoff. Потрібен aiohttp ≥ 3.10; на старіших версіях таймаут з'єднання
|
|
652
|
+
по-старому дає `maybe_delivered=True`.
|
|
653
|
+
|
|
654
|
+
### 13.3 Проксі
|
|
655
|
+
|
|
656
|
+
Типовий сценарій корпоративної мережі: сервер не має прямого виходу в інтернет, а вихідні запити йдуть через внутрішній проксі.
|
|
657
|
+
Без проксі з'єднання з `chatapi.viber.com` просто висить до таймауту (`TimeoutError` у `_create_connection`), хоча **вхідні**
|
|
658
|
+
вебхуки працюють (їх приймає ваш reverse proxy).
|
|
659
|
+
|
|
660
|
+
```python
|
|
661
|
+
# 1. Явно
|
|
662
|
+
bot = vb.Bot(TOKEN, name="Bot", proxy="proxy, connect_timeout=10)
|
|
663
|
+
|
|
664
|
+
# 2. З автентифікацією
|
|
665
|
+
vb.ViberClient(TOKEN, sender_name="Bot", proxy="http://user:pass@10.0.0.1:3128")
|
|
666
|
+
vb.ViberClient(TOKEN, sender_name="Bot", proxy="http://10.0.0.1:3128",
|
|
667
|
+
proxy_auth=aiohttp.BasicAuth("user", "pass"))
|
|
668
|
+
|
|
669
|
+
# 3. З оточення: HTTPS_PROXY=http://10.0.0.1:3128 python bot.py
|
|
670
|
+
vb.ViberClient(TOKEN, sender_name="Bot", trust_env=True)
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
Нюанси:
|
|
674
|
+
- Підтримується **HTTP-проксі** з методом `CONNECT` для HTTPS (стандартна поведінка aiohttp). SOCKS потребує окремого `aiohttp-socks` і своєї `session`.
|
|
675
|
+
- Проксі застосовується лише до **вихідних** запитів клієнта. Вебхук-сервер (вхідні) від нього не залежить.
|
|
676
|
+
- Задаєте і `proxy`, і `trust_env=True`: явний `proxy` має пріоритет.
|
|
677
|
+
- Помилки проксі: недоступний проксі → `connection failed` (ретраїться); `407 Proxy Authentication Required` або відмова проксі на `CONNECT` → `aiohttp.ClientHttpProxyError`, яка загортається в `TransportError("request failed: ...", maybe_delivered=True)` (перевірте логін/пароль і чи дозволено домен на проксі).
|
|
678
|
+
- Перевірка з сервера: `curl -x http://proxy -v -m 15 https://chatapi.viber.com/pa/get_account_info`. Будь-яка відповідь Viber (навіть помилка авторизації) означає, що шлях працює.
|
|
679
|
+
- Своя сесія: `ViberClient(..., session=aiohttp.ClientSession(trust_env=True))`; `proxy=` усе одно передається в запити.
|
|
680
|
+
|
|
681
|
+
### 13.4 TLS/сертифікати для вихідних запитів
|
|
682
|
+
|
|
683
|
+
Клієнт використовує стандартну перевірку aiohttp (системні CA / `certifi`). Окремого `ssl_context` для клієнта в API немає: якщо
|
|
684
|
+
потрібен корпоративний CA чи IPv4-only, створіть свою сесію:
|
|
685
|
+
|
|
686
|
+
```python
|
|
687
|
+
import ssl, socket, aiohttp, certifi
|
|
688
|
+
ctx = ssl.create_default_context(cafile=certifi.where())
|
|
689
|
+
ctx.load_verify_locations(cafile="/etc/ssl/corp-ca.pem") # додати, а не замінити
|
|
690
|
+
session = aiohttp.ClientSession(
|
|
691
|
+
connector=aiohttp.TCPConnector(ssl=ctx, family=socket.AF_INET),
|
|
692
|
+
timeout=aiohttp.ClientTimeout(total=30, sock_connect=10),
|
|
693
|
+
)
|
|
694
|
+
client = vb.ViberClient(TOKEN, sender_name="Bot", session=session, proxy=None)
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
Не змішуйте клієнтський і серверний контексти: для вхідного вебхука (`ssl_context` у `serve`) потрібен контекст `Purpose.CLIENT_AUTH` із
|
|
698
|
+
`load_cert_chain(fullchain.pem, privkey.pem)`, а для вихідних запитів. Це `Purpose.SERVER_AUTH` із довіреними CA, без вашого сертифіката.
|
|
699
|
+
|
|
700
|
+
### 13.5 Конкурентність і ліміти
|
|
701
|
+
|
|
702
|
+
- `max_concurrency` (64): одночасних запитів до Viber.
|
|
703
|
+
- Лімітер broadcast: ковзне вікно `(500, 10.0)`.
|
|
704
|
+
- Конектор: `limit=100` з'єднань, DNS-кеш 300 с.
|
|
705
|
+
|
|
706
|
+
---
|
|
707
|
+
|
|
708
|
+
## 14. Моделі результатів
|
|
709
|
+
|
|
710
|
+
| Клас | Поля / властивості |
|
|
711
|
+
|---|---|
|
|
712
|
+
| `SendResult` | `message_token: int`, `billing_status: BillingStatus \| None`, `chat_hostname`, `raw` |
|
|
713
|
+
| `BroadcastResult` | `results`, `failed: list[FailedReceiver]`, `errors: list[(ids, Exception)]`, `total`, `.ok`, `.delivered_count` |
|
|
714
|
+
| `FailedReceiver` | `receiver`, `status`, `status_message` |
|
|
715
|
+
| `OnlineStatus` | `id`, `status: OnlineState`, `message`, `.online` |
|
|
716
|
+
| `AccountInfo` | `id, name, uri, icon, background, category, subcategory, location, country, webhook, event_types, subscribers_count, members` |
|
|
717
|
+
| `User` | див. розділ 6 |
|
|
718
|
+
| `Sender` | `name`, `avatar` |
|
|
719
|
+
|
|
720
|
+
`BillingStatus`: `FREE=0`, `IN_SESSION_NON_BILLABLE_BOT=1`, `IN_SESSION_BILLABLE_BOT=2`, `OUT_OF_SESSION_FREE_NON_BILLABLE_BOT=3`,
|
|
721
|
+
`OUT_OF_SESSION_FREE_BILLABLE_BOT=4`, `OUT_OF_SESSION_BILLED=5`.
|
|
722
|
+
|
|
723
|
+
`OnlineState`: `ONLINE=0`, `OFFLINE=1`, `UNDISCLOSED=2`, `TRY_LATER=3`, `UNAVAILABLE=4`.
|
|
724
|
+
|
|
725
|
+
`AccountInfo.from_dict` приймає поле `Country` (як у документації Viber) і кладе його в `country`.
|
|
726
|
+
|
|
727
|
+
---
|
|
728
|
+
|
|
729
|
+
## 15. Помилки і коди Viber
|
|
730
|
+
|
|
731
|
+
```
|
|
732
|
+
ViberError
|
|
733
|
+
├── ValidationError (ще й ValueError) # локальна валідація, запит не надсилався
|
|
734
|
+
├── SignatureError # оголошено в API, самою бібліотекою не піднімається
|
|
735
|
+
├── TransportError # мережа; .maybe_delivered
|
|
736
|
+
└── APIError # status != 0; .status, .status_message, .payload, .http_status, .code
|
|
737
|
+
├── AuthError (2)
|
|
738
|
+
├── BadRequestError (1, 3, 4, 16)
|
|
739
|
+
├── RecipientError (5, 6, 11, 21) # .is_unsubscribed для 5 і 6
|
|
740
|
+
├── AccountError (7, 8, 9, 10, 15, 17)
|
|
741
|
+
├── RateLimitError (12) # .retry_after
|
|
742
|
+
├── ApiVersionError (13, 14)
|
|
743
|
+
├── BroadcastError (19, 20)
|
|
744
|
+
└── BillingError (22, 23, 24)
|
|
745
|
+
```
|
|
746
|
+
|
|
747
|
+
| Код | `ErrorCode` | Клас | Значення |
|
|
748
|
+
|---|---|---|---|
|
|
749
|
+
| 1 | `INVALID_URL` | `BadRequestError` | Невірний URL вебхука (також якщо сервіс недоступний під час `set_webhook`) |
|
|
750
|
+
| 2 | `INVALID_AUTH_TOKEN` | `AuthError` | Токен недійсний |
|
|
751
|
+
| 3 | `BAD_DATA` | `BadRequestError` | Некоректні дані запиту |
|
|
752
|
+
| 4 | `MISSING_DATA` | `BadRequestError` | Бракує обов'язкових даних |
|
|
753
|
+
| 5 | `RECEIVER_NOT_REGISTERED` | `RecipientError` | Отримувач не зареєстрований у Viber |
|
|
754
|
+
| 6 | `RECEIVER_NOT_SUBSCRIBED` | `RecipientError` | Не підписаний на бота |
|
|
755
|
+
| 7 | `PUBLIC_ACCOUNT_BLOCKED` | `AccountError` | Акаунт заблоковано |
|
|
756
|
+
| 8 | `PUBLIC_ACCOUNT_NOT_FOUND` | `AccountError` | Акаунт не знайдено |
|
|
757
|
+
| 9 | `PUBLIC_ACCOUNT_SUSPENDED` | `AccountError` | Акаунт призупинено |
|
|
758
|
+
| 10 | `WEBHOOK_NOT_SET` | `AccountError` | Вебхук не встановлено |
|
|
759
|
+
| 11 | `RECEIVER_NO_SUITABLE_DEVICE` | `RecipientError` | Немає пристрою, що підтримує повідомлення |
|
|
760
|
+
| 12 | `TOO_MANY_REQUESTS` | `RateLimitError` | Перевищено ліміт запитів |
|
|
761
|
+
| 13 | `API_VERSION_NOT_SUPPORTED` | `ApiVersionError` | Версія API не підтримується |
|
|
762
|
+
| 14 | `INCOMPATIBLE_WITH_VERSION` | `ApiVersionError` | Несумісно з версією |
|
|
763
|
+
| 15 | `PUBLIC_ACCOUNT_NOT_AUTHORIZED` | `AccountError` | Акаунт не авторизований |
|
|
764
|
+
| 16 | `INCHAT_MESSAGE_NOT_ALLOWED` | `BadRequestError` | Повідомлення в чат не дозволено |
|
|
765
|
+
| 17 | `PUBLIC_ACCOUNT_IS_NOT_INLINE` | `AccountError` | Акаунт не «inline» |
|
|
766
|
+
| 19 | `CANNOT_SEND_BROADCAST` | `BroadcastError` | Не вдалося розіслати |
|
|
767
|
+
| 20 | `BROADCAST_NOT_ALLOWED` | `BroadcastError` | Розсилка заборонена |
|
|
768
|
+
| 21 | `UNSUPPORTED_COUNTRY` | `RecipientError` | Країна не підтримується |
|
|
769
|
+
| 22 | `PAYMENT_UNSUPPORTED` | `BillingError` | Платежі не підтримуються |
|
|
770
|
+
| 23 | `FREE_MESSAGES_EXCEEDED` | `BillingError` | Вичерпано безкоштовні повідомлення |
|
|
771
|
+
| 24 | `NO_BALANCE` | `BillingError` | Недостатньо коштів |
|
|
772
|
+
|
|
773
|
+
(Коду 18 у переліку немає; невідомі коди дають базовий `APIError`, `err.code` тоді `None`.)
|
|
774
|
+
|
|
775
|
+
Приклад обробки:
|
|
776
|
+
|
|
777
|
+
```python
|
|
778
|
+
try:
|
|
779
|
+
await ev.reply("hi")
|
|
780
|
+
except vb.RecipientError as e:
|
|
781
|
+
if e.is_unsubscribed: await db.mark_unsubscribed(ev.user_id)
|
|
782
|
+
except vb.RateLimitError as e:
|
|
783
|
+
await asyncio.sleep(e.retry_after or 5)
|
|
784
|
+
except vb.TransportError as e:
|
|
785
|
+
if e.maybe_delivered: log.warning("можливо, вже доставлено")
|
|
786
|
+
except vb.ValidationError as e:
|
|
787
|
+
log.error("некоректне повідомлення: %s", e)
|
|
788
|
+
```
|
|
789
|
+
|
|
790
|
+
Не-JSON відповідь із HTTP ≥ 400 → `APIError(http, "non-JSON error response")`. Відповідь 2xx з невалідним JSON → `TransportError(maybe_delivered=True)`.
|
|
791
|
+
|
|
792
|
+
---
|
|
793
|
+
|
|
794
|
+
## 16. Вебхук-сервер і інтеграція з фреймворками
|
|
795
|
+
|
|
796
|
+
### 16.1 Вбудований aiohttp-сервер
|
|
797
|
+
|
|
798
|
+
| Функція | Опис |
|
|
799
|
+
|---|---|
|
|
800
|
+
| `create_app(bot, path="/viber") -> web.Application` | aiohttp-додаток: маршрут вебхука (`path` і `path + "/"`, усі HTTP-методи), `GET /healthz` → `ok`, ліміт тіла 10 МБ, закриття `bot` при cleanup |
|
|
801
|
+
| `serve(bot, *, host="0.0.0.0", port=8080, path="/viber", ssl_context=None)` | Запускає сервер і блокується. **Вебхук не реєструє.** |
|
|
802
|
+
| `run_webhook(bot, *, webhook_url=None, host, port, path, event_types=None, send_name=True, send_photo=True, ssl_context=None)` | Те саме + (якщо задано `webhook_url`) фонова реєстрація вебхука з `wait=60`. Помилка реєстрації лише логується, сервер працює далі. Для `webhook_url=None` ≡ `serve`. |
|
|
803
|
+
|
|
804
|
+
Поведінка маршруту з `always_ok=True`:
|
|
805
|
+
- Будь-який HTTP-метод, окрім POST → 200.
|
|
806
|
+
- Не вдалося прочитати тіло, надто велике тіло (413), помилки фреймворку → 200 (middleware).
|
|
807
|
+
- Підпис/JSON → див. розділ 4.
|
|
808
|
+
- Заголовок підпису: `X-Viber-Content-Signature`.
|
|
809
|
+
|
|
810
|
+
**Шлях має збігатися** з тим, що ви реєструєте у Viber:
|
|
811
|
+
|
|
812
|
+
```python
|
|
813
|
+
webhook_path = "/test_webhook"
|
|
814
|
+
await vb.serve(bot, host="127.0.0.1", port=8080, path=webhook_path)
|
|
815
|
+
await client.set_webhook("https://52-br.example.com" + webhook_path)
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
`path` за замовчуванням `/viber`. Розбіжність шляху дає 404 у reverse proxy або в aiohttp, і Viber подій не отримає.
|
|
819
|
+
|
|
820
|
+
### 16.2 TLS у `serve`
|
|
821
|
+
|
|
822
|
+
Якщо перед ботом стоїть reverse proxy (nginx/caddy), що терминує TLS, **не** передавайте `ssl_context`, а слухайте на `127.0.0.1`:
|
|
823
|
+
|
|
824
|
+
```python
|
|
825
|
+
await vb.serve(bot, host="127.0.0.1", port=8080, path="/viber") # без ssl
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
Власний TLS без проксі:
|
|
829
|
+
|
|
830
|
+
```python
|
|
831
|
+
ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) # саме CLIENT_AUTH!
|
|
832
|
+
ctx.load_cert_chain("fullchain.pem", "privkey.pem") # fullchain, не лише cert
|
|
833
|
+
await vb.serve(bot, host="0.0.0.0", port=8443, ssl_context=ctx)
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
Viber підтримує порти 443, 80, 88, 8443 для вебхуків. Клієнтські сертифікати Viber не надсилає, тому `ca` для вебхука не потрібен (mTLS не використовується).
|
|
837
|
+
|
|
838
|
+
### 16.3 FastAPI / Starlette
|
|
839
|
+
|
|
840
|
+
```python
|
|
841
|
+
from fastapi import FastAPI, Request, Response
|
|
842
|
+
app = FastAPI()
|
|
843
|
+
|
|
844
|
+
@app.post("/viber")
|
|
845
|
+
async def viber(request: Request):
|
|
846
|
+
res = await bot.handle_update(await request.body(),
|
|
847
|
+
request.headers.get("X-Viber-Content-Signature"))
|
|
848
|
+
return Response(res.json(), status_code=res.status, media_type="application/json")
|
|
849
|
+
|
|
850
|
+
@app.on_event("shutdown")
|
|
851
|
+
async def shutdown():
|
|
852
|
+
await bot.close()
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
### 16.4 Інші фреймворки (Flask/Django/aiohttp)
|
|
856
|
+
|
|
857
|
+
`handle_update` приймає **сирі байти тіла**; не перекодовуйте JSON перед передачею (підпис рахується від оригінальних байтів).
|
|
858
|
+
Для синхронних фреймворків викликайте корутину через `asyncio.run_coroutine_threadsafe` у фоновому event loop.
|
|
859
|
+
|
|
860
|
+
### 16.5 Обробка з черги
|
|
861
|
+
|
|
862
|
+
`await bot.process(payload_dict)` виконує обробку без HTTP: зручно, якщо вебхук приймає окремий сервіс, а обробка йде з Redis/Kafka.
|
|
863
|
+
|
|
864
|
+
---
|
|
865
|
+
|
|
866
|
+
## 17. Розгортання (nginx, systemd, HTTPS)
|
|
867
|
+
|
|
868
|
+
### Схема
|
|
869
|
+
|
|
870
|
+
```
|
|
871
|
+
Viber ──HTTPS:443──► nginx (TLS, fullchain) ──HTTP──► 127.0.0.1:8080 (viberio.serve)
|
|
872
|
+
│
|
|
873
|
+
вихідні запити ─┴─► corporate proxy ─► chatapi.viber.com
|
|
874
|
+
```
|
|
875
|
+
|
|
876
|
+
### nginx
|
|
877
|
+
|
|
878
|
+
```nginx
|
|
879
|
+
server {
|
|
880
|
+
listen 443 ssl;
|
|
881
|
+
server_name bot.example.com;
|
|
882
|
+
ssl_certificate /etc/ssl/fullchain.pem;
|
|
883
|
+
ssl_certificate_key /etc/ssl/privkey.pem;
|
|
884
|
+
|
|
885
|
+
location /viber {
|
|
886
|
+
proxy_pass http://127.0.0.1:8080;
|
|
887
|
+
proxy_set_header Host $host;
|
|
888
|
+
proxy_set_header X-Real-IP $remote_addr;
|
|
889
|
+
proxy_read_timeout 10s;
|
|
890
|
+
client_max_body_size 10m;
|
|
891
|
+
}
|
|
892
|
+
}
|
|
893
|
+
```
|
|
894
|
+
|
|
895
|
+
`proxy_set_header X-Viber-Content-Signature` додавати не треба: nginx за замовчуванням пересилає всі заголовки клієнта.
|
|
896
|
+
|
|
897
|
+
### systemd
|
|
898
|
+
|
|
899
|
+
```ini
|
|
900
|
+
[Unit]
|
|
901
|
+
Description=Viber bot
|
|
902
|
+
After=network-online.target
|
|
903
|
+
|
|
904
|
+
[Service]
|
|
905
|
+
User=botuser
|
|
906
|
+
WorkingDirectory=/home/botuser/chatbot_tg
|
|
907
|
+
Environment=VIBER_TOKEN=...
|
|
908
|
+
Environment=VIBER_PROXY=http://proxy
|
|
909
|
+
ExecStart=/home/botuser/chatbot_tg/.venv/bin/python echo_bot.py
|
|
910
|
+
Restart=always
|
|
911
|
+
RestartSec=3
|
|
912
|
+
|
|
913
|
+
[Install]
|
|
914
|
+
WantedBy=multi-user.target
|
|
915
|
+
```
|
|
916
|
+
|
|
917
|
+
Рекомендується тримати токен в окремому `EnvironmentFile` з правами `600`.
|
|
918
|
+
|
|
919
|
+
### Чекліст запуску
|
|
920
|
+
|
|
921
|
+
1. `pip install -e ".[fast]"` у віртуальному середовищі.
|
|
922
|
+
2. Задати `VIBER_TOKEN` (та `VIBER_PROXY`, якщо потрібен).
|
|
923
|
+
3. Запустити сервіс; `curl http://127.0.0.1:8080/healthz` → `ok`.
|
|
924
|
+
4. Перевірити зовнішній HTTPS: `curl -i https://bot.example.com/viber` → `200`.
|
|
925
|
+
5. Один раз викликати `set_webhook("https://bot.example.com/viber", wait=60)`.
|
|
926
|
+
6. Написати боту й перевірити лог: немає `handler failed`.
|
|
927
|
+
|
|
928
|
+
---
|
|
929
|
+
|
|
930
|
+
## 18. Безпека
|
|
931
|
+
|
|
932
|
+
- **Підпис вебхука.** Тримайте `verify_signatures=True`. Підпис = `HMAC-SHA256(token, raw_body)` у hex; порівняння сталого часу.
|
|
933
|
+
- **Токен.** Не комітьте в репозиторій; використовуйте змінні оточення або секрет-менеджер. Токен потрапляє лише в заголовок `X-Viber-Auth-Token`.
|
|
934
|
+
- **`always_ok=True` не означає довіри.** Невалідні запити відповідаються 200, але **не обробляються**; фіксується лише лог.
|
|
935
|
+
- **Ліміт тіла** вхідного вебхука: 10 МБ (aiohttp `client_max_size`).
|
|
936
|
+
- **Дедуп** захищає від повторної обробки одного й того самого callback.
|
|
937
|
+
- Виведення в логи: бібліотека не логує токен і тіла повідомлень; перевіряйте власні обробники, щоб не логувати персональні дані.
|
|
938
|
+
- Облікові дані проксі (`http://user:pass@...`) не логуються бібліотекою, але можуть потрапити у ваші логи, якщо ви друкуєте конфіг.
|
|
939
|
+
|
|
940
|
+
---
|
|
941
|
+
|
|
942
|
+
## 19. Ліміти Viber, які перевіряються локально
|
|
943
|
+
|
|
944
|
+
| Ліміт | Значення |
|
|
945
|
+
|---|---|
|
|
946
|
+
| Довжина тексту | 7000 символів |
|
|
947
|
+
| Підпис до картинки | 512 символів |
|
|
948
|
+
| `tracking_data` | 4000 символів |
|
|
949
|
+
| Ім'я відправника | 1..28 символів |
|
|
950
|
+
| Розмір payload `send_message` | 30 КБ |
|
|
951
|
+
| Відео | `.mp4`, ≤ 26 МБ (27 262 976 байт), до 180 с |
|
|
952
|
+
| Файл | ≤ 50 МБ (52 428 800 байт), ім'я ≤ 256 символів, обов'язкове розширення |
|
|
953
|
+
| Заборонені розширення | `.bat .bin .cmd .com .cpl .exe .gadget .inf1 .ins .inx .isu .job .jse .lnk .msc .msi .msp .mst .paf .pif .ps1 .reg .rgs .sct .shb .shs .u3p .vb .vbe .vbs .vbscript .ws .wsf .action .app .command .csh .osx .workflow .ksh .out .run .apk .ipa` |
|
|
954
|
+
| URL | ≤ 2000 символів, `http(s)://` |
|
|
955
|
+
| Контакт: ім'я / телефон | ≤ 28 / `^\+?\d{1,17}$`, ≤ 18 |
|
|
956
|
+
| Кнопок у клавіатурі | 1..24 |
|
|
957
|
+
| Колонок / рядків кнопки | 1..6 / 1..7 |
|
|
958
|
+
| Карток rich media / карусель | 1..6 |
|
|
959
|
+
| Розсилка | чанк 300 отримувачів, 500 запитів / 10 с |
|
|
960
|
+
| `get_online` | чанк 100 ID |
|
|
961
|
+
| `get_user_details` | 2 запити / 12 год на користувача (контролює Viber) |
|
|
962
|
+
| Welcome-повідомлення | відповідь на `conversation_started` ≈ 4 с (`welcome_timeout`) |
|
|
963
|
+
| Кнопка оплати | діє 15 хв |
|
|
964
|
+
|
|
965
|
+
Перевищення дає `ValidationError` **до** мережевого запиту.
|
|
966
|
+
|
|
967
|
+
---
|
|
968
|
+
|
|
969
|
+
## 20. Діагностика проблем (troubleshooting)
|
|
970
|
+
|
|
971
|
+
### 20.1 `handler failed for MessageEvent` … `TransportError: request failed: TimeoutError()`
|
|
972
|
+
|
|
973
|
+
**Симптом.** Повідомлення від користувачів долітають (обробник запускається), але `ev.reply(...)` падає. Трасування закінчується
|
|
974
|
+
в `asyncio ... _create_connection_transport ... await waiter`, потім `CancelledError` → `TimeoutError`.
|
|
975
|
+
|
|
976
|
+
**Причина.** Вихідне з'єднання до `chatapi.viber.com` не встановлюється за `timeout` секунд. Вхідна та вихідна частини незалежні.
|
|
977
|
+
Найчастіші причини: (1) сервер виходить в інтернет лише через проксі, а проксі в клієнті не задано; (2) файрвол/allowlist блокує домен;
|
|
978
|
+
(3) IPv6-маршрут «висить».
|
|
979
|
+
|
|
980
|
+
**Рішення.**
|
|
981
|
+
1. Перевірте мережу з **того ж сервера**:
|
|
982
|
+
```bash
|
|
983
|
+
curl -4 -v -m 15 https://chatapi.viber.com/pa/get_account_info
|
|
984
|
+
curl -6 -v -m 15 https://chatapi.viber.com/pa/get_account_info
|
|
985
|
+
curl -x http://proxy -v -m 15 https://chatapi.viber.com/pa/get_account_info
|
|
986
|
+
```
|
|
987
|
+
2. Якщо працює лише через проксі → `proxy="http://proxy"`.
|
|
988
|
+
3. Якщо працює лише `-4` → власна сесія з `family=socket.AF_INET` (розділ 13.4).
|
|
989
|
+
4. Якщо нічого не працює → дозвольте домен у файрволі/проксі або зверніться до мережевого адміністратора.
|
|
990
|
+
5. Додайте `connect_timeout=10`, щоб помилки з'єднання швидко виявлялись і ретраїлись.
|
|
991
|
+
|
|
992
|
+
> SSL-контекст тут **не** допомагає: таймаут виникає до/під час підключення, а не через сертифікат. Помилки сертифікатів виглядають
|
|
993
|
+
> як `ClientConnectorCertificateError`/`SSLCertVerificationError`.
|
|
994
|
+
|
|
995
|
+
### 20.2 `TypeError: ViberClient.send() got an unexpected keyword argument 'keyboard'`
|
|
996
|
+
|
|
997
|
+
Старіша версія `Event.reply` пересилала `keyboard` у `client.send`. У поточній версії `reply` сама обробляє `keyboard=`. Оновіть
|
|
998
|
+
`events.py` (або всю бібліотеку). Для прямих викликів клієнта використовуйте `send_text(..., keyboard=...)` або
|
|
999
|
+
`send(receiver, TextMessage(text, keyboard=kb))`.
|
|
1000
|
+
|
|
1001
|
+
### 20.3 `ImportError: cannot import name ... from 'viberio' (unknown location)`
|
|
1002
|
+
|
|
1003
|
+
Пакет не встановлено: див. розділ 2.
|
|
1004
|
+
|
|
1005
|
+
### 20.4 Вебхук не встановлюється (`APIError 1`)
|
|
1006
|
+
|
|
1007
|
+
- URL має бути HTTPS із валідним сертифікатом від довіреного CA і повним ланцюжком (`fullchain`).
|
|
1008
|
+
- Сервіс має відповідати 200 на POST під час `set_webhook`: запустіть бота **до** виклику й додайте `wait=60`.
|
|
1009
|
+
- Шлях і порт збігаються з `path=` у `serve`, reverse proxy пересилає саме цей шлях.
|
|
1010
|
+
|
|
1011
|
+
### 20.5 Користувачі пишуть, а обробник не спрацьовує
|
|
1012
|
+
|
|
1013
|
+
- У логах `webhook update ignored: invalid signature`: токен не збігається з токеном бота, на якого зареєстровано вебхук, або проксі змінює тіло запиту.
|
|
1014
|
+
- Немає взагалі логів: запит не доходить (nginx, шлях, порт, файрвол). Перевірте `access.log` nginx.
|
|
1015
|
+
- Спрацьовує не той обробник: порядок реєстрації та `block` (розділ 5.2).
|
|
1016
|
+
- `on_delivered` не ловить `seen`: це різні події.
|
|
1017
|
+
|
|
1018
|
+
### 20.6 Дублікати відповідей
|
|
1019
|
+
|
|
1020
|
+
Бібліотека не повторює `send_message` після таймауту. Якщо дублікати все ж є, ймовірно, Viber повторив callback через затримку
|
|
1021
|
+
відповіді (у `handle_update` це покриває дедуп за `message_token`) або обробник зареєстровано двічі.
|
|
1022
|
+
|
|
1023
|
+
### 20.7 `ValidationError`
|
|
1024
|
+
|
|
1025
|
+
Повідомлення містить причину (напр. `picture URL must end with .jpeg/.jpg/.png/.gif`). Запит до Viber не відправлявся.
|
|
1026
|
+
|
|
1027
|
+
### 20.8 `RateLimitError`
|
|
1028
|
+
|
|
1029
|
+
Для звичайних `send_*` автоповтору немає: обробляйте самі (`e.retry_after`). Розсилки (`broadcast`) повторюються автоматично.
|
|
1030
|
+
|
|
1031
|
+
### 20.9 Увімкнути діагностичні логи
|
|
1032
|
+
|
|
1033
|
+
```python
|
|
1034
|
+
import logging
|
|
1035
|
+
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
|
|
1036
|
+
logging.getLogger("viberio").setLevel(logging.DEBUG)
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
Корисні повідомлення: `webhook update ignored: ...`, `handler failed for ...`, `retrying <endpoint> in ...s (attempt N)`,
|
|
1040
|
+
`serving webhook on ...`, `webhook set: ...`.
|
|
1041
|
+
|
|
1042
|
+
---
|
|
1043
|
+
|
|
1044
|
+
## 21. Тестування
|
|
1045
|
+
|
|
1046
|
+
```bash
|
|
1047
|
+
pip install -e ".[dev]"
|
|
1048
|
+
pytest -q # 19 тестів, фейковий Viber-сервер на aiohttp.test_utils
|
|
1049
|
+
```
|
|
1050
|
+
|
|
1051
|
+
Покриття: payload і версії, валідація, відправка/помилки/ретраї, розсилка (чанки, часткові збої), `get_online`, ліміти й підпис,
|
|
1052
|
+
сквозний сценарій бота, парсинг подій, режим `always_ok`, `serve` без реєстрації вебхука, передача `proxy` в aiohttp, `reply(keyboard=...)`.
|
|
1053
|
+
|
|
1054
|
+
Для власних тестів обробників:
|
|
1055
|
+
|
|
1056
|
+
```python
|
|
1057
|
+
await bot.process({"event": "message", "timestamp": 1, "message_token": 1,
|
|
1058
|
+
"sender": {"id": "U1", "name": "T"}, "message": {"type": "text", "text": "hi"}})
|
|
1059
|
+
```
|
|
1060
|
+
|
|
1061
|
+
Щоб не ходити в мережу, підставте `client` із підміненим `send`, або використайте `base_url` фейкового сервера:
|
|
1062
|
+
`vb.ViberClient(TOKEN, sender_name="Bot", base_url=str(server.make_url("/pa")))`.
|
|
1063
|
+
|
|
1064
|
+
---
|
|
1065
|
+
|
|
1066
|
+
## 22. Відомі особливості та підводні камені
|
|
1067
|
+
|
|
1068
|
+
1. **`serve()` не ставить вебхук.** Це навмисно; використовуйте `run_webhook(webhook_url=...)` або `set_webhook` окремо.
|
|
1069
|
+
2. **Фоновий запуск обробників.** При `always_ok` і незавершених обробниках процес можна зупиняти лише через `bot.close()`
|
|
1070
|
+
(чекає до `drain_timeout`), інакше відповіді, що ще надсилаються, обірвуться.
|
|
1071
|
+
3. **`conversation_started`: лише `welcome_timeout` секунд.** Довгі операції (БД, HTTP) робіть у фоні; welcome повертайте швидко.
|
|
1072
|
+
4. **Загальний `on_message()` без фільтрів** перехоплює все, якщо зареєстрований раніше за інші (при `block=True`).
|
|
1073
|
+
5. **`Seen` ≠ `Delivered` для маршрутизації**, хоч і успадковує клас.
|
|
1074
|
+
6. **Мутація `Message`** при `tracking_data`/`keyboard` (розділ 8).
|
|
1075
|
+
7. **Екранування в `Button.reply`/`url`**: `&`, `<`, `>` стають HTML-сутностями; для розмітки потрібен `raw_html=True`.
|
|
1076
|
+
8. **Власна `session`** ігнорує `timeout`/`connect_timeout`/`trust_env` клієнта.
|
|
1077
|
+
9. **`connect_timeout` вимагає aiohttp ≥ 3.10** для автоповтору таймаутів з'єднання.
|
|
1078
|
+
10. **`get_account_info`**: нові доки вказують `GET`, старі — `POST`; за замовчуванням `POST`, змінюється `account_info_method="GET"`.
|
|
1079
|
+
11. **Платежі** працюють лише для українського ринку, потрібен API v10.
|
|
1080
|
+
12. **`set_webhook` вимагає HTTPS** (перевірка `url.startswith("https://")` на стороні бібліотеки).
|
|
1081
|
+
13. **`remove_webhook`** вимикає й розмови 1-на-1.
|
|
1082
|
+
14. **Бот має бути створений на комерційних умовах** (з 05.02.2024), інакше деякі методи недоступні.
|
|
1083
|
+
15. **Дедуп in-memory.** Він діє в межах одного процесу; при кількох воркерах/репліках потрібен спільний сховок.
|
|
1084
|
+
|
|
1085
|
+
---
|
|
1086
|
+
|
|
1087
|
+
## 23. Довідник публічного API
|
|
1088
|
+
|
|
1089
|
+
Експортується з `viberio` (`from viberio import ...`):
|
|
1090
|
+
|
|
1091
|
+
**Клієнт і бот:** `Bot`, `UpdateResult`, `ViberClient`, `create_app`, `serve`, `run_webhook`
|
|
1092
|
+
|
|
1093
|
+
**Події:** `Event`, `MessageEvent`, `Subscribed`, `Unsubscribed`, `ConversationStarted`, `Delivered`, `Seen`, `Failed`,
|
|
1094
|
+
`PaymentButtonClicked`, `UnknownEvent`, `IncomingMessage`, `parse_event`
|
|
1095
|
+
|
|
1096
|
+
**Фільтри:** `F` (`F.text`, `F.message_type`, `F.users`, `F.not_`)
|
|
1097
|
+
|
|
1098
|
+
**Повідомлення:** `Message`, `TextMessage`, `PictureMessage`, `VideoMessage`, `FileMessage`, `ContactMessage`, `LocationMessage`,
|
|
1099
|
+
`UrlMessage`, `StickerMessage`, `RichMediaMessage`, `PaymentMessage`
|
|
1100
|
+
|
|
1101
|
+
**Клавіатури/rich media:** `Keyboard`, `Button`, `InternalBrowser`, `MapLocation`, `Frame`, `MediaPlayer`, `Card`, `RichMedia`
|
|
1102
|
+
|
|
1103
|
+
**Платежі:** `Payment`
|
|
1104
|
+
|
|
1105
|
+
**Моделі:** `AccountInfo`, `BillingStatus`, `BroadcastResult`, `OnlineState`, `OnlineStatus`, `SendResult`, `Sender`, `User`
|
|
1106
|
+
|
|
1107
|
+
**Помилки:** `ViberError`, `ValidationError`, `SignatureError`, `TransportError`, `APIError`, `ErrorCode`, `AuthError`,
|
|
1108
|
+
`BadRequestError`, `RecipientError`, `AccountError`, `RateLimitError`, `ApiVersionError`, `BroadcastError`, `BillingError`
|
|
1109
|
+
|
|
1110
|
+
`viberio.__version__ == "1.0.0"`.
|
|
1111
|
+
|
|
1112
|
+
### Сигнатури `ViberClient` (коротко)
|
|
1113
|
+
|
|
1114
|
+
```text
|
|
1115
|
+
set_webhook(url, event_types=None, *, send_name=None, send_photo=None, wait=None, wait_interval=3.0) -> list[str]
|
|
1116
|
+
remove_webhook() -> None
|
|
1117
|
+
get_account_info() -> AccountInfo
|
|
1118
|
+
get_user_details(user_id) -> User
|
|
1119
|
+
get_online(user_ids) -> list[OnlineStatus]
|
|
1120
|
+
send(receiver, message, *, sender=None, tracking_data=None, min_api_version=None) -> SendResult
|
|
1121
|
+
send_messages(receiver, messages, **kw) -> list[SendResult]
|
|
1122
|
+
send_text | send_picture | send_video | send_file | send_contact | send_location | send_url | send_sticker
|
|
1123
|
+
send_rich_media(receiver, rich_media, *, alt_text=None, **kw) | send_payment(receiver, payment, **kw)
|
|
1124
|
+
broadcast(receivers, message, *, sender=None, tracking_data=None, min_api_version=None, raise_on_error=False) -> BroadcastResult
|
|
1125
|
+
build_payload(message, *, receiver=None, sender=None, tracking_data=None, min_api_version=None) -> dict
|
|
1126
|
+
verify_signature(body, signature) -> bool
|
|
1127
|
+
close() -> None
|
|
1128
|
+
```
|
|
1129
|
+
|
|
1130
|
+
### Повний приклад бота
|
|
1131
|
+
|
|
1132
|
+
```python
|
|
1133
|
+
import asyncio, logging, os
|
|
1134
|
+
import viberio as vb
|
|
1135
|
+
from viberio import F
|
|
1136
|
+
|
|
1137
|
+
logging.basicConfig(level=logging.INFO)
|
|
1138
|
+
|
|
1139
|
+
bot = vb.Bot(os.environ["VIBER_TOKEN"], name="Demo Bot",
|
|
1140
|
+
proxy=os.environ.get("VIBER_PROXY"), timeout=30, connect_timeout=10)
|
|
1141
|
+
|
|
1142
|
+
MENU = vb.Keyboard.from_rows([["📦 Каталог", "ℹ️ Допомога"],
|
|
1143
|
+
[vb.Button.share_phone("📞 Надіслати номер")]])
|
|
1144
|
+
|
|
1145
|
+
@bot.middleware
|
|
1146
|
+
async def log_events(ev, call_next):
|
|
1147
|
+
logging.info("event=%s user=%s", type(ev).__name__, ev.user_id)
|
|
1148
|
+
return await call_next(ev)
|
|
1149
|
+
|
|
1150
|
+
@bot.on_conversation_started()
|
|
1151
|
+
async def welcome(ev):
|
|
1152
|
+
return vb.TextMessage(f"Вітаю, {ev.user.name or 'друже'}!", keyboard=MENU)
|
|
1153
|
+
|
|
1154
|
+
@bot.on_text(equals="📦 Каталог")
|
|
1155
|
+
async def catalog(ev):
|
|
1156
|
+
cards = [vb.Card(f"Товар {i}", image=f"https://example.com/img/{i}.jpg", price="₴199",
|
|
1157
|
+
button_text="Детальніше", action_body=f"https://example.com/p/{i}") for i in range(1, 4)]
|
|
1158
|
+
await ev.bot.client.send_rich_media(ev.user_id, vb.RichMedia.carousel(cards))
|
|
1159
|
+
|
|
1160
|
+
@bot.on_text(r"^(?:hi|привіт)")
|
|
1161
|
+
async def hi(ev):
|
|
1162
|
+
await ev.reply("Привіт! 👋", keyboard=MENU)
|
|
1163
|
+
|
|
1164
|
+
@bot.on_message(F.message_type("location"))
|
|
1165
|
+
async def loc(ev):
|
|
1166
|
+
await ev.reply(f"Отримав локацію: {ev.message.location}")
|
|
1167
|
+
|
|
1168
|
+
@bot.on_failed()
|
|
1169
|
+
async def failed(ev):
|
|
1170
|
+
logging.warning("не доставлено: %s %s", ev.message_token, ev.desc)
|
|
1171
|
+
|
|
1172
|
+
@bot.on_message() # останнім
|
|
1173
|
+
async def fallback(ev):
|
|
1174
|
+
await ev.reply(f"Ви написали: {ev.text}")
|
|
1175
|
+
|
|
1176
|
+
async def on_error(ev, exc):
|
|
1177
|
+
logging.error("handler error: %r", exc)
|
|
1178
|
+
bot.on_error = on_error
|
|
1179
|
+
|
|
1180
|
+
if __name__ == "__main__":
|
|
1181
|
+
asyncio.run(vb.serve(bot, host="127.0.0.1", port=8080, path="/viber"))
|
|
1182
|
+
```
|