SDK Python: установка и методы

Установка

Python 3.10 или новее. Клиент использует стандартную библиотеку и содержит аннотации типов. Запросы синхронные: в асинхронном приложении вызывайте их через рабочий поток.

Команда устанавливает пакет из PyPI. API v1 одинаков для всех трёх SDK; инструкции в репозиториях доступны на русском.

python -m pip install waix-python

Ключ и первый запрос

Ключ хранится на сервере. Для отправки нужен scope messages:write; для чтения — messages:read. Connection ID берётся из раздела WhatsApp. Подготовьте собственный одобренный шаблон с одной переменной или измените компоненты примера.

import os
import uuid
from waix import Waix

waix = Waix(os.environ['WAIX_API_KEY'])
# Сохраните UUID в записи заказа до отправки.
event_id = str(uuid.uuid4())
result = waix.messages.send({
    'connection_id': os.environ['WAIX_CONNECTION_ID'],
    'to': '+77071234567', 'type': 'template',
    'template': {
        'name': 'order_ready', 'language': {'code': 'ru'},
        'components': [{'type': 'body', 'parameters': [
            {'type': 'text', 'text': '42'}
        ]}]
    }
}, event_id)

UUID создаётся один раз для логической отправки и сохраняется до запроса. После тайм-аута повторяйте тот же запрос с тем же UUID; новый ключ означает новое сообщение. HTTP 202 подтверждает постановку в очередь, а не доставку.

Ошибки и тайм-аут

Исключение WaixError содержит status, code, request_id, retry_after. HTTP-статус 0 означает транспортную ошибку или тайм-аут. По request ID поддержка может найти запрос; ключи и полные тела сообщений в журнал писать не нужно.

Настройка тайм-аута: timeout=30 — секунды. По умолчанию 30 секунд. Автоматических повторов и переходов по редиректам нет. При 429 дождитесь Retry-After; ошибки 400, 401 и 403 сначала исправьте.

OTP: отправить, проверить, узнать статус

Нужен ключ OTP-проекта с соответствующими правами. В sandbox отправка возвращает test_code и не обращается к WhatsApp. Не передавайте test_code посетителю: проверка потеряет смысл.

otp = Waix(os.environ['WAIX_OTP_PROJECT_KEY'])
sent = otp.otp.send({'to': '+77071234567', 'ttl': 300}, event_id)
# Сохраните sent['data']['id'] в сессии пользователя.
status = otp.otp.status(sent['data']['id'])
result = otp.otp.verify(sent['data']['id'], supplied_code)

Пример показывает отдельные этапы. suppliedCode / supplied_code / $suppliedCode — код из следующего запроса того же пользователя. Challenge ID хранится в его серверной сессии, а не принимается без проверки от любого посетителя. Успешная доставка кода ещё не означает успешную авторизацию.

Медиа и пагинация

waix.media.upload(connection_id, 'invoice.pdf', content_type='application/pdf', type='document')

Укажите Connection ID, MIME-тип и вид медиа. Файлы должны соответствовать ограничениям API. Python загружает файл в память; для больших документов учитывайте доступную память процесса.

waix.messages.list(limit=50, before=cursor, before_id=cursor_id)

Метод возвращает весь JSON-ответ. Для следующей страницы передайте одновременно pagination.next_before и pagination.next_before_id. Когда оба значения отсутствуют, список закончился.

Проверка вебхука

verify_webhook(raw_body, timestamp, signature, secret)

rawBody / raw_body — исходные байты HTTP-запроса до JSON-парсера. timestamp и signature — заголовки X-Waix-Timestamp и X-Waix-Signature. secret — секрет вашего вебхука или OTP-проекта.

Проверка сравнивает HMAC-SHA256 за постоянное время и допускает расхождение часов до 300 секунд. Неверная подпись или просроченное время дают false. После проверки сохраняйте X-Waix-Delivery и не обрабатывайте одно событие дважды.

SDK 0.2: журнал и диагностика

Во всех SDK появился messages.iterate: он читает журнал по страницам, сохраняет фильтры и переносит оба курсора. У Node.js это async iterator, у Python и PHP — generator. Полный журнал не нужно загружать в память.

По умолчанию ответ ограничен 2 МиБ. Ошибки HTTP сохраняют статус, request ID и Retry-After, даже если прокси вернул HTML. Повторный курсор и превышение заданного количества страниц останавливают обход с понятной ошибкой.

Для журналирования используйте error.toJSON() в Node.js, error.to_dict() в Python или json_encode($error) в PHP. Эти методы исключают тело ответа, которое может содержать данные клиента. Полные примеры и настройки лимитов приведены в README пакета.

Остальные методы

SDK поддерживают чтение и обновление профиля номера, создание и редактирование шаблонов, preview, удаление медиа, настройку вебхука и смену его секрета. Названия методов и полные сигнатуры приведены в README пакета. Для новых методов API v1 есть общий request с относительным путём.

Часть методов управления требует более широких прав. OTP-ключ проекта не может изменять общий вебхук компании. Не расширяйте права рабочего ключа только ради отладки: создайте отдельный ключ для нужной операции.