Типы подключений

У каждого подключения есть поле provider, и оно принимает одно из двух значений:

Оба типа отправляют и принимают сообщения через одни и те же эндпоинты, с одинаковыми телами запросов и двумя одинаковыми идентификаторами сообщения. Если вы считали, что подключить QR-номер из собственного приложения невозможно, то это не так.

Где они действительно отличаются

Webhooks. События отправляются только для подключений qr. Подключения cloud_api сейчас не отправляют webhooks — для них используйте опрос GET /messages и GET /connections/{id}.

Сопряжение. POST /connections/{id}/pairing-code относится только к qr. Номер cloud_api отвечает 409 not_supported_for_provider; это постоянный отказ, поэтому повторять запрос не нужно.

Задержка отправки. Отправка через qr обычно занимает 1–7 с (до ~20 с для длинного текста) и может занять около 2,5 минут при самовосстановлении сессии. Отправка через cloud_api занимает около 1 с. Настраивайте тайм-аут HTTP с расчётом на медленный вариант: не менее 180 с.

Отметка о прочтении. POST /messages/read отмечает прочитанным весь чат на подключении qr. Подключение cloud_api может отметить только одно конкретное сообщение, поэтому запрос только с phone автоматически находит последнее входящее сообщение от этого номера.

Объём. У недавно привязанного номера qr в течение 72 часов действуют лимиты прогрева на почасовой объём; при превышении возвращается 429 warmup_limited. Подробнее — в разделе Лицензии и пробный период.

Состояние сессии. Подключение qr привязано к телефону, который должен оставаться доступным, поэтому оно может отключиться, и потребуется повторное сопряжение. Для этого и нужны connection.disconnected / connection.connected и флаг needs_reconnect. Подключение cloud_api ничего не сканирует и такого сбоя не знает.