Tipos de conexión
El campo provider es qr o cloud_api. Qué puede hacer cada uno y en qué se diferencian de verdad.
Cada conexión informa un provider, y su valor es uno de estos dos:
provider | Qué es | Cómo se incorpora |
|---|---|---|
qr | Un número de WhatsApp común (se vende como WAPP), vinculado al enlazar un dispositivo. | POST /connections, y luego escanee un QR o escriba un código de emparejamiento. Totalmente autogestionado a través de la API, sin cuenta de Meta Business. |
cloud_api | Un número de WhatsApp Business (se vende como WABA) registrado en Meta, en la Cloud API oficial. | Embedded Signup de Meta, no esta API. |
Ambos tipos envían y reciben a través de los mismos endpoints, con los mismos cuerpos de solicitud y los mismos dos ids de mensaje. Si usted creía que era imposible usar QR desde su propia aplicación: sí se puede.
En qué se diferencian realmente
Webhooks. Los eventos se disparan solo para las conexiones qr. Hoy las
conexiones cloud_api no emiten webhooks: para ellas consulte GET /messages y
GET /connections/{id}.
Emparejamiento. POST /connections/{id}/pairing-code es un concepto de qr.
Un número cloud_api responde 409 not_supported_for_provider; es un rechazo
permanente, así que no lo reintente.
Latencia de envío. Un envío qr normalmente tarda de 1 a 7 s (hasta ~20 s
con un texto largo) y puede tardar ~2,5 minutos en la ruta de autorreparación.
Un envío cloud_api tarda cerca de 1 s. Dimensione el tiempo de espera HTTP
para el caso lento: al menos 180 s.
Marcar como leído. POST /messages/read marca todo el chat en una conexión
qr. Una conexión cloud_api solo puede marcar un mensaje específico, así que
una solicitud con solo phone resuelve automáticamente el mensaje entrante más
reciente de ese número.
Volumen. Un número qr recién emparejado tiene límites de calentamiento de
72 horas sobre el volumen por hora; superarlos devuelve 429 warmup_limited.
Consulte Licencias y prueba.
Salud de la sesión. Una conexión qr está atada a un teléfono que debe
seguir accesible, por lo que puede caerse y pedir un nuevo emparejamiento. Para
eso sirven connection.disconnected / connection.connected y la marca
needs_reconnect. Una conexión cloud_api nunca escanea nada y no tiene ese
modo de fallo.
Los proveedores desconocidos no se filtran
provider se convierte en null en lugar de pasar un valor no reconocido. Si
alguna vez se agrega un nuevo tipo de conexión, se nombrará aquí de forma
deliberada, así que hoy es seguro ramificar según qr / cloud_api. Aun así,
trate null como «un tipo que este cliente no conoce» en lugar de dejar que
falle.
Espacios de trabajo
Una clave pertenece a un único espacio de trabajo. Qué implica esto para las aplicaciones multi-tenant y en qué se diferencia un portal de Bitrix24 de un espacio de trabajo independiente.
Licencias y prueba
Una prueba gratuita de 7 días por número y, después, una licencia mensual por número. Qué es un slot y qué ocurre cuando uno vence.