Documentación
API de WhatsApp por Zera: qué recibes y qué hacer con eso.
La referencia de endpoint y de payload es la de Meta, y sigue siéndolo. Esta página documenta la parte que es de Zera: cómo llega la credencial hasta ti, qué hace la conexión con tu número, qué errores aparecen y qué hacer en cada uno.
Lo que no fue confirmado en el código no está escrito aquí. Donde falta información, esta página lo dice y explica por qué. Documentación que llena un hueco con una suposición cuesta más caro que documentación que no existe.
Qué recibes
Lo que se entrega es una credencial de la Cloud API de Meta, en tu número, dentro de la cuenta de WhatsApp Business de tu empresa. Son cinco campos, y la pantalla del panel devuelve exactamente estos.
| token texto | La autorización que Meta generó para tu empresa cuando conectaste el número. Va en el encabezado Authorization de tus llamadas. No es una clave de Zera, no es un token de plataforma, no es un secreto compartido. |
|---|---|
| phone_number_id texto | El identificador de tu número en la Cloud API. Es el que entra en la URL de envío del mensaje. |
| waba_id texto | El identificador de la cuenta de WhatsApp Business de tu empresa en Meta. Sirve para consultar números, plantillas de mensaje y suscripciones. |
| webhook texto o nulo | La dirección https que informaste para recibir los eventos. Nulo quiere decir que todavía no informaste ninguna, y la pantalla lo dice en vez de esconderlo. |
| expira_em fecha o nulo | El vencimiento del token, cuando existe. Nulo quiere decir que Meta no devolvió plazo, y no que el token venció. Por defecto el token del Embedded Signup no expira por tiempo. |
De quién es esto, en la práctica
- La cuenta de WhatsApp Business es de tu empresa, y el token también. Zera lo guarda cifrado para operar tu número, y la posesión sigue siendo tuya.
- Solo Meta revoca ese token. Zera no puede, y por eso no existe un botón para generar otra credencial en el panel. Un botón que promete lo que el sistema no cumple es peor que su ausencia.
- Como no se puede rotar la credencial, tampoco tiene sentido mostrarla una sola vez: quien la perdiera quedaría atrapado. La regla es la otra: la ves cuantas veces necesites, y cada exhibición hace ruido.
Cómo obtener la credencial
La credencial está en la pantalla del canal, dentro del panel. No se envía por WhatsApp ni por correo, y nunca viaja en una URL. Las reglas de abajo no son burocracia: cada una cierra un camino concreto, y la pantalla explica cada negativa con sus propias palabras.
Solo en el plan sin bandeja de entrada
En el plan de API la credencial es el producto. En un plan con bandeja de atención, ZeraSync usa esa misma credencial, y rotarla o filtrarla tumbaría tu propia atención. En esos planes la pantalla lo explica y no muestra nada.
Sesión de menos de diez minutos
Estar conectado no basta. La cookie de sesión dura treinta días, y la credencial le sobrevive. Si tu sesión es más vieja que diez minutos, la pantalla pide un enlace nuevo y ofrece el botón que lo envía, en vez de dar un error seco.
Tres exhibiciones por día, por cuenta
El conteo incluye el intento en curso y cuenta intentos, no éxitos. Si se agota, la pantalla dice que pediste demasiado hoy, y no finge que la falla fue nuestra.
Cada exhibición avisa al dueño de la cuenta
Sale un correo en el momento, con fecha, hora y origen, y aparece una línea en la pestaña Actividad del canal. Si el proveedor no acepta el correo, la credencial no se muestra. El aviso es la traba, no el adorno: sin poder revocar, la única defensa es que te enteres rápido.
Un token vencido no se entrega
Si el token ya venció, la pantalla lo dice y ofrece reconectar el número. Entregar una credencial muerta te haría perder media hora depurando tu sistema por algo que era nuestro deber avisar.
La conexión de tu número
La conexión ocurre en la ventana oficial de Meta, en tu navegador. Lo que cambia el camino es la situación en la que está hoy tu número, y cada camino ejecuta pasos distintos del lado del servidor.
| Número nuevo | Un número sin WhatsApp. Necesitas recibir un SMS o una llamada en ese número para la verificación. |
|---|---|
| Número en WhatsApp común | La cuenta tiene que borrarse antes en el aparato, y el historial local se pierde. Eso está dicho en pantalla antes del clic, no después. |
| Número en WhatsApp Business | Es la coexistencia. El número sigue funcionando en el celular y el historial se preserva. Es la ruta más usada, y tiene su propia lista de cambios más abajo. |
| Número en otra plataforma de API | Hoy no tiene botón, y la ausencia es deliberada. La migración depende de que la plataforma anterior apague la verificación en dos pasos, y Zera no destraba eso sola. Ese caso entra en fila con una persona, con instrucción en pantalla. Prometer un botón aquí sería vender lo que no existe. |
Qué cambia en tu número después de la coexistencia
Esta lista es la de la tabla oficial de Meta sobre la integración de usuarios de la aplicación Business, y no un recuerdo de alguien. Está aquí porque la diferencia entre un desarrollador informado y un ticket de soporte es leerla antes.
- Los aparatos vinculados al número quedan desvinculados.
- Las listas de difusión se desactivan. No se pueden crear nuevas, y las existentes quedan solo de lectura.
- Los grupos no se sincronizan. Siguen funcionando solo en la aplicación.
- Los mensajes temporales se desactivan en las conversaciones de una persona a otra.
- Ver una vez se desactiva en esas mismas conversaciones.
- La ubicación en tiempo real se desactiva.
- Las llamadas de voz y de video siguen solo en la aplicación.
- El catálogo, los pedidos y los estados siguen solo en la aplicación.
- El caudal queda en veinte mensajes por segundo, fijo.
En la coexistencia el número ya está registrado en la Cloud API, así que el paso de registro se salta a propósito: llamarlo igual quemaría una de las diez llamadas que Meta permite por número cada 72 horas. Y la lista de números de tu cuenta puede volver vacía por algunos minutos después de que termina el diálogo. En ese caso la conexión espera en vez de fallar. Honestidad sobre la fuente: ese retraso no está documentado por Meta en ningún lugar, es reporte de quien opera. Lo que la documentación de Meta sí sostiene, y es lo que fundamenta la decisión, es otra cosa: el evento de fin prueba que el diálogo terminó, no que todo paso de servidor salió bien.
El primer envío
Un endpoint, una clave, un minuto. La dirección es la de Meta, y el mensaje va de tu servidor directo hacia allá. Zera no queda en el medio.
curl -X POST https://graph.facebook.com/v25.0/SEU_PHONE_NUMBER_ID/messages \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5545999999999",
"type": "text",
"text": { "body": "¡Hola!" }
}'La versión v25.0 es la que usa la conexión hoy, y vale hasta el 29 de julio de 2028. Mandar siempre la versión en la URL es a propósito: una llamada sin versión usa la que esté marcada en el panel de la aplicación, y cuando una versión expira Meta reenvía en silencio a la siguiente, cambiando el comportamiento sin avisar.
El webhook
Lo que está confirmado
- Zera suscribe su aplicación en la cuenta de WhatsApp Business de tu empresa, y vuelve a leer la suscripción después para confirmar que existe de verdad. Sin esa suscripción, ningún evento de tu número sale de Meta.
- Informas una dirección https en la ficha de contratación. El https es obligatorio: Meta rechaza direcciones en http, y descubrirlo en el momento de la configuración te manda al final de la fila.
- La dirección es opcional al contratar. La mitad de quien compra la credencial cruda todavía está desarrollando y no tiene dirección para dar, y trabar la entrega por eso crearía fila humana en vano.
Lo que todavía no está documentado, y por qué
- Apuntar los eventos a tu dirección lo hace hoy una persona de Zera, como un paso de la fila de entrega, y no un código que se pueda citar aquí.
- Mientras sea así, esta página no describe el formato exacto de lo que llega a tu dirección, ni los encabezados, ni la firma. No existe implementación nuestra contra la cual verificar, y escribir eso de memoria es como se publica una dirección equivocada a quien va a construir un receptor encima.
- El contrato que vale es el de Meta: el cuerpo es el payload de la Cloud API, en el formato de ella. Antes de escribir tu receptor, confirma con Zera cuál es el apuntamiento vigente en tu número.
Errores comunes
Estos son códigos de Meta, y aparecen tanto en la conexión de tu número como en tus propias llamadas. La decisión sale siempre del código, nunca de la frase del mensaje: la propia Meta recomienda no usar el texto como lógica, porque lo reescribe sin avisar.
| Código | Qué hacer |
|---|---|
| 133016 | El registro del número agotó el presupuesto y queda bloqueado por 72 horas. No insistas: cada intento de más empuja el plazo. Espera y lee el tiempo en error_data.details. |
| 133008 y 133009 | Espera con plazo. El tiempo viene escrito en error_data.details, en la propia respuesta. Léelo de ahí. Meta no publica un número fijo para estos dos, y un valor adivinado o traba tu número demasiado tiempo o quema un intento del presupuesto. |
| 133005 | El número ya tenía verificación en dos pasos, y el PIN es tuyo. La salida es apagar la verificación en WhatsApp Manager y conectar de nuevo. Zera no puede destrabar eso de su lado. |
| 190 | El token ya no es válido. Obtén la credencial de nuevo en el panel, y reconecta el número si la pantalla lo pide. |
| 200 | Falta permiso para lo que se pidió. Verifica que el token sea el del número correcto. |
| 368 | Cuenta restringida por violación de política. Insistir no destraba nada, y aún genera llamadas en una cuenta ya marcada. El camino es resolver la restricción con Meta. |
| 100 | Parámetro inválido. En las lecturas suele ser un campo pedido en fields que no existe en esa versión de la Graph, y ahí se pierde la lista entera por un campo opcional. En las llamadas de autorización suele ser un parámetro de más. |
| 4 | Techo de la aplicación entera, no de tu número. Insistir no resuelve. Si aparece, todos los clientes de esa aplicación se detuvieron juntos. |
| 1 y 2 | Indisponibilidad temporal de Meta. Intentar de nuevo más tarde es la respuesta correcta. |
| 17, 341, 80007, 80008, 131000, 133004 y 133015 | Zera los trata como reintentables: intentar de nuevo en un rato tiene chance de funcionar. |
| 3, 10, 131031, 133006 y 133010 | Zera los trata como definitivos: insistir no destraba y aún gasta una llamada. |
- Las dos últimas filas están clasificadas por lo que el código de Zera hace con ellas. El significado exacto de cada una es de Meta y está en su referencia de códigos de error. Repetir aquí ese texto de memoria sería inventar.
- Una llamada que muere a la mitad, o un 5xx sin cuerpo, no es un rechazo de Meta: es Meta que no respondió. Son cosas distintas, y la segunda pide un nuevo intento.
- Un código desconocido se trata como definitivo, a propósito. Insistir en un error que nadie entiende, contra un endpoint que crea cuentas de verdad, es como se descubre un límite después de haberlo quemado.
Los límites que valen
El código del Embedded Signup vale 30 segundos
Es de un solo uso y el intercambio ocurre dentro de la propia petición del navegador, no en una fila. Encolarlo significaría despertar con él ya quemado.
Registro del número: 10 llamadas por 72 horas
Es el techo de Meta, por número. La undécima bloquea el número por tres días. Zera se detiene en 6 a propósito, para dejar margen a un registro manual sin tocar el límite de ella.
Coexistencia: 20 mensajes por segundo
Es fijo, y viene de la propia tabla de Meta sobre la integración de usuarios de la aplicación Business.
La alta capacidad no se compra, se solicita
La liberación de mayor caudal es de Meta, número por número, con criterios de ella. Zera arma el pedido y lo acompaña. Si Meta no aprueba, no pagas nada más.
El token no expira por tiempo, por defecto
Un expira_em nulo quiere decir que Meta no devolvió plazo. Tratar la ausencia de plazo como vencimiento le quitaría la credencial a quien la tiene funcionando.
Lo que todavía no está documentado
Esta lista existe para que no pierdas tiempo buscando lo que no hay. Cada punto dice el motivo, porque una ausencia sin motivo parece un olvido.
- El formato del evento que llega a tu webhook
- Por el motivo de la sección del webhook: el apuntamiento es un paso humano hoy, y no existe implementación nuestra contra la cual verificar. Confirma con Zera antes de escribir el receptor.
- Un ambiente de prueba
- No existe sandbox de Zera. Pruebas en tu propio número conectado, contra la Cloud API de Meta. Si algún día existe, entra aquí.
- Una biblioteca o SDK de Zera
- No existe, y no va a existir. Lo que vale es la Cloud API de Meta, con sus payloads. Por eso tu código sigue funcionando si algún día cambias de proveedor.
- Un endpoint de Zera para que llames
- No existe, y eso no es una falta: es el diseño. Tu mensaje va de tu servidor a graph.facebook.com. Zera conecta el número y lo mantiene conectado.
La conexión es nuestra. La API es de Meta, y sigue siendo tuya.
R$ 147 por número, por mes. Sin fidelidad y sin intermediario en tu mensaje.
Ver los planes de la API¿Faltó algo en esta página? Habla con Zera