Types de connexion
Le champ provider vaut qr ou cloud_api. Ce que chacun permet de faire, et les points où les deux diffèrent vraiment.
Chaque connexion indique un provider, qui prend l'une de ces deux valeurs :
provider | De quoi s'agit-il | Comment l'intégrer |
|---|---|---|
qr | Un numéro WhatsApp ordinaire (vendu sous le nom WAPP), associé en liant un appareil. | POST /connections, puis scan d'un QR code ou saisie d'un code d'association. Entièrement en libre-service via l'API — sans compte Meta Business. |
cloud_api | Un numéro WhatsApp Business (vendu sous le nom WABA) enregistré auprès de Meta, sur la Cloud API officielle. | Embedded Signup de Meta, et non cette API. |
Les deux types envoient et reçoivent via les mêmes endpoints, avec les mêmes corps de requête et les mêmes deux identifiants de message. Si vous pensiez qu'il était impossible de connecter un QR depuis votre propre application : c'est possible.
Où ils diffèrent vraiment
Webhooks. Les événements ne sont déclenchés que pour les connexions qr.
Les connexions cloud_api n'émettent aucun webhook aujourd'hui — interrogez
GET /messages et GET /connections/{id} pour celles-ci.
Association. POST /connections/{id}/pairing-code est un concept propre à
qr. Un numéro cloud_api répond 409 not_supported_for_provider ; c'est un
refus définitif, donc ne réessayez pas.
Latence d'envoi. Un envoi qr prend normalement 1 à 7 s (jusqu'à ~20 s
pour un texte long) et peut atteindre ~2,5 minutes en cas d'auto-réparation.
Un envoi cloud_api prend environ 1 s. Dimensionnez votre timeout HTTP pour le
cas le plus lent : au moins 180 s.
Marquage comme lu. POST /messages/read marque toute la conversation sur
une connexion qr. Une connexion cloud_api ne peut marquer qu'un message
précis : une requête avec le seul phone retrouve donc automatiquement votre
message entrant le plus récent provenant de ce numéro.
Volume. Un numéro qr fraîchement associé est soumis à des plafonds de
montée en charge de 72 heures sur le volume horaire ; en dépasser un renvoie
429 warmup_limited. Voir
Licences et essai.
Santé de la session. Une connexion qr est liée à un téléphone qui doit
rester joignable ; elle peut donc se déconnecter et demander une nouvelle
association. C'est à cela que servent connection.disconnected /
connection.connected et l'indicateur needs_reconnect. Une connexion
cloud_api ne scanne jamais rien et ne connaît pas ce mode de défaillance.
Les providers inconnus ne fuient pas
provider vaut null plutôt que de transmettre une valeur non reconnue. Si un
nouveau type de connexion est un jour ajouté, il sera nommé ici de façon
délibérée ; vous pouvez donc brancher votre logique sur qr / cloud_api dès
maintenant. Traitez toutefois null comme « un type que ce client ne connaît
pas » plutôt que de planter.
Espaces de travail
Une clé appartient à un seul espace de travail. Ce que cela implique pour les applications multi-tenant, et en quoi un portail Bitrix24 diffère d'un espace de travail autonome.
Licences et période d'essai
Un essai gratuit de 7 jours par numéro, puis une licence mensuelle par numéro. Ce qu'est un slot et ce qui se passe à son expiration.