Код сопряжения и QR

QR-код обновляется каждые 20 секунд. Реализуйте оба способа: при подключении с одного устройства клиент не сможет сфотографировать собственный экран.

Сопряжение применимо к подключениям qr. Номер cloud_api ничего не сканирует и отвечает 409 not_supported_for_provider.

Способ с QR-кодом

POST /connections возвращает первый QR-код в виде PNG в формате data URI.

Перерисовывайте QR-код при каждом опросе

WhatsApp обновляет код сопряжения примерно каждые 20 секунд. Значение qr в ответе на создание устаревает через несколько секунд после показа, и это происходит незаметно: телефон не сопрягается, а на экране нет ни слова о причине.

Опрашивайте GET /connections/{id} каждые 3–5 с и перерисовывайте qr из каждого ответа, пока status не станет "connected". Не кэшируйте его и не прячьте обновление за кнопкой, которую должен нажимать пользователь.

То же правило действует для идемпотентного повтора: когда POST /connections возвращает 200 с Idempotency-Replayed: true, qr в этом ответе запрашивается заново, а не берётся из хранилища, — именно потому, что сохранённый код уже не отсканируется.

Способ с кодом сопряжения

Для QR-кода нужны два устройства: экран, на котором он показан, и телефон, который его фотографирует. Значительная часть реальных подключений происходит на одном устройстве: клиент проходит ваш сценарий на том же телефоне, где установлен WhatsApp, и не может сфотографировать собственный экран. Для таких клиентов QR-код не просто неудобен — он невозможен.

POST /connections/{id}/pairing-code

curl -X POST https://developers.wasync.app/api/v1/connections/conn_8f3a21/pairing-code \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"40740267964"}'

200 response

{
  "code": "7S59-1KZP"
}

Клиент открывает WhatsApp → Настройки → Связанные устройства → Привязать по номеру телефона и вводит код.

phoneNumber указывается в формате E.164 без ведущего + — только цифры. Любой другой формат отклоняется ответом 400 { "error": "invalid_phone_number" }, и номер не исправляется за вас: если молча переписывать присланный номер, клиент в итоге сопрягает аккаунт, который никто не заказывал. Используется whatsapp.manage, как и при создании подключения.

Код сопряжения доступен не всегда — оставьте QR как запасной вариант

Движок может отказаться выдать код. Это обычная ситуация, а не сбой, и в этом случае возвращается 502 { "error": "pairing_code_unavailable" }, а не общая ошибка 500 — чтобы вы могли отличить одно от другого и вернуть пользователя к QR-коду. Интеграция, в которой есть только код сопряжения, рано или поздно покажет клиенту экран, с которого некуда идти дальше. Показывайте оба способа рядом.

Запрос нового кода

Для того же подключения можно запросить ещё один код: вернётся новый код, а сессия не пересоздаётся, поэтому кнопка «Отправить другой код» безопасна.

Лимит — 5 запросов на подключение за 15 минут; при превышении вы получите 429 { "error": "rate_limited" } с заголовком Retry-After, который нужно соблюдать. Это не бюрократия: многократные запросы кодов для одного номера — именно то, на что реагируют системы защиты WhatsApp от злоупотреблений, а под угрозой оказывается номер вашего клиента.

Ничего дополнительного не расходуется

Сопряжение по коду занимает тот же оплаченный слот и запускает тот же 7-дневный бесплатный пробный период, что и сканирование QR-кода: лицензия занимается в момент, когда номер действительно сопрягается, независимо от способа.

Отслеживание успеха тоже не меняется. События «код принят» нет, поэтому опрашивайте GET /connections/{id}, пока status не станет "connected", и/или слушайте webhook connection.connected.

Стоит предусмотреть два отказа:

409 already_connected — сессия активна, сопрягать нечего.
409 not_supported_for_provider — номер cloud_api. Коды сопряжения относятся только к qr и здесь неприменимы, поэтому не повторяйте запрос.

Повторное сопряжение

Сессия qr может прерваться сама. Об этом сообщает connection.disconnected, а поле needs_reconnect — то, от чего стоит отталкиваться в интерфейсе. QR-кода в этом payload намеренно нет — это учётные данные для входа по сканированию, — поэтому получите его через GET /connections/{id} и покажите владельцу номера точно так же, как при первой настройке. См. Webhooks.

Была ли эта страница полезной?