Cómo conectar su software a WhatsApp
API Management es la forma en que otro sistema — su software de facturación, su tienda en línea, su propio backend — envía mensajes de WhatsApp a través de WizMessage. Aquí le emite una clave de API, le indica qué plantilla de WhatsApp aprobada puede enviar y lo apunta a un webhook para que las respuestas vuelvan. Esta guía recorre todo el camino y después documenta la API REST que llamarán sus desarrolladores.
El panel
Dónde están sus claves de API
Todas las claves que haya emitido aparecen aquí, en API Keys. Cada fila muestra el estado de la clave, su prefijo público (la única parte de la clave que se vuelve a mostrar una vez creada) y cuántas llamadas ha realizado hoy. «Manage» abre la clave; el interruptor la pausa sin eliminarla.
Una clave que todavía no está terminada
Una clave sin ninguna plantilla asignada lleva la etiqueta «Needs setup». Puede autenticarse, pero no puede enviar un mensaje de plantilla hasta que le asigne una, de modo que una integración a medio configurar se detecta de un vistazo en lugar de fallar más tarde, al enviar.
Configuración guiada
Paso 1 — ¿Qué va a conectar?
«Connect your software» abre un asistente de cuatro pasos. Empiece por dar a la clave el nombre del sistema que la va a usar y elija el preajuste que corresponda. Los preajustes solo sugieren nombres de campo razonables — facturación sugiere invoice_number, amount, due_date, customer_name — pero no limitan lo que puede asignar.
Paso 2 — Elija el mensaje
Elija una de sus plantillas de WhatsApp aprobadas. Las plantillas están en Meta, no aquí: esta lista se obtiene en vivo desde su cuenta de WhatsApp conectada y solo se pueden enviar las plantillas APROBADAS. Este paso es opcional: omítalo si la clave solo va a enviar texto sin formato y asigne una plantilla más adelante.
Paso 3 — ¿Adónde deben ir las respuestas?
Cuando alguien responde a su mensaje, o llega un informe de entrega, lo enviamos mediante POST a una URL que usted controla. Deje esto desactivado si su sistema solo envía. Puede añadirlo más tarde desde la pestaña Webhooks de la clave: aquí nada es permanente.
Paso 4 — Póngala en marcha
Pulsar Next en el paso anterior es lo que realmente crea la clave; esta pantalla es la confirmación. Copie ahora los tres valores: la clave de API, el secreto de API y el secreto de firma del webhook se muestran exactamente una vez y después no se pueden recuperar. Si pierde el secreto, tendrá que rotarlo, lo que implica actualizar el sistema que lo estuviera usando.
Gestión de una clave
Resumen
Al abrir una clave se llega a Overview: lo que tiene permitido hacer, con qué intensidad se está usando y los endpoints a los que puede llamar. Los recuentos de uso se leen del registro de solicitudes, así que reflejan el tráfico real.
Una clave que todavía está por configurar
Una clave sin plantilla asignada se abre en una pestaña Setup: el mismo asistente, integrado. Fíjese en que las pestañas difieren de la captura anterior: hasta que una clave no tiene al menos una plantilla, no se ofrecen Templates ni Webhooks, porque todavía no hay nada sobre lo que puedan actuar.
Plantillas
En la pestaña Templates, cada tarjeta es una plantilla que esta clave puede enviar. El texto del cuerpo es el mensaje tal como se aprobó en Meta, y los chips que aparecen debajo son los nombres de las variables que suministrará su sistema. «Try it» envía una prueba y «Get code» genera una solicitud lista para usar en ocho lenguajes.
Cómo leer las variables — lo único en lo que merece la pena detenerse
Fíjese en la tarjeta payment_failed_alert. Su mensaje va {{1}}, luego {{3}} y después {{2}}: los marcadores de posición NO aparecen en orden numérico dentro del texto. Los chips de debajo sí están en orden numérico: customer_name rellena {{1}}, renewal_date rellena {{2}} y plan_name rellena {{3}}. Haga coincidir sus valores con el NÚMERO, nunca con el orden en que los marcadores aparezcan en la frase. Esto es lo que más despista a la gente en las plantillas traducidas, donde el orden de las palabras cambia de sitio los marcadores.
Los tres botones de cada plantilla
«Try it» — envíe una prueba sin escribir código
El botón del avión de papel abre esta plantilla precargada con valores de ejemplo, uno por nombre de variable. Es la forma más rápida de comprobar que una asignación es correcta antes de que sus desarrolladores la toquen. Fíjese en el interruptor: «Simulate Only» es el valor predeterminado y nada sale de casa — el servidor le devuelve su carga útil tal cual. Cámbielo a «Send Real Message» y saldrá un mensaje de WhatsApp real al número del cuadro, que además se cobra.
Qué le devuelve un envío simulado
Pulsar Send Request en modo Simulate Only devuelve la solicitud tal como la recibió la plataforma, con el estado HTTP y el tiempo de ida y vuelta. Léalo como una comprobación de forma, no como un ensayo general: confirma que su JSON se ha analizado y que la clave se ha aceptado, pero NO valida los nombres de sus variables frente a la asignación y nunca contacta con Meta. Una carga útil que se simula sin errores puede rechazarse igualmente en real. Para demostrar la asignación en sí, active Send Real Message y envíe a su propio teléfono.
«Get code» — la solicitud, ya escrita por usted
El botón de los corchetes angulares genera una solicitud funcional para esta plantilla exacta en ocho lenguajes: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go y C#. Entrégueselo a quien esté escribiendo la integración. Las variables aparecen como {{placeholders}} con el nombre de su asignación, y las credenciales se dejan como YOUR_API_KEY / YOUR_API_SECRET: este diálogo nunca imprime su clave real, así que el fragmento se puede pegar en un ticket sin riesgo.
Cómo cambiar de lenguaje
Haga clic en cualquier lenguaje de la parte superior y el fragmento se reescribe para él: la misma llamada, las mismas cabeceras, el cliente HTTP de ese lenguaje. Cada uno se genera la primera vez que hace clic, así que un breve indicador de carga en el primer cambio es normal. Copy se lleva el fragmento tal como aparece: está completo, imports incluidos, y si esta clave exige firmas, el paso de firma ya viene dentro.
«Edit» — cambie lo que envía su sistema
El lápiz abre la asignación en sí. La maqueta de teléfono de la parte superior es el mensaje real con sus nombres actuales sustituidos, así que puede ver lo que leerá el cliente. Debajo, cada variable detectada se puede renombrar, reordenar, marcar como obligatoria o tipar: una fecha, un importe monetario, una imagen. Renombrar una variable la renombra también en su carga útil de la API, de modo que un sistema que ya envíe el nombre antiguo empezará a fallar: cambie las dos cosas a la vez.
Test API — la misma herramienta, cualquier endpoint
«Test API», en la parte superior de la pestaña, es «Try it» sin el bloqueo de plantilla: elija cualquiera de los tres endpoints de envío, cambie de plantilla en el segundo desplegable y edite el cuerpo libremente. Úselo para comprobar las llamadas en crudo a /messages/text o /messages/template, que no tienen tarjeta propia porque no están ligadas a ninguna asignación. Fíjese en que las variables de esta plantilla todavía se llaman body_1, body_2, body_3: así es como se ve una plantilla sin asignar, y es justo lo que «Edit» sirve para arreglar.
Respuestas
Webhooks — cómo recibir las respuestas
Enviar es solo la mitad de una integración. Apunte un webhook a su propio endpoint HTTPS y WizMessage le enviará mediante POST los mensajes entrantes y las actualizaciones de entrega. El secreto de firma se muestra una sola vez, al generarlo; verifíquelo en cada entrega para tener la certeza de que la llamada procede realmente de nosotros.
Referencia de la API REST
Todo lo anterior configura la clave. Esto es lo que llamarán realmente sus desarrolladores. La URL base es /api/v1/external. Todos los endpoints requieren las cabeceras de autenticación que se indican abajo y están sujetos a los límites de frecuencia de la clave.
Autenticación
Envíe su clave de API en cada solicitud. Si la clave tiene activada la opción «Require signature», también debe firmar la solicitud: una clave con esa opción activada rechazará de plano cualquier llamada sin firmar.
| Cabecera | Valor |
|---|---|
X-API-Key | Su clave de API: el valor pk_live_… completo, no solo el prefijo que se muestra en el panel. |
X-Timestamp | Marca de tiempo Unix en segundos. Se rechaza si difiere en más de 5 minutos de la hora del servidor. |
X-API-Signature | HMAC-SHA256 de timestamp + "." + rawBody, con clave SHA256(api_secret), en hexadecimal minúsculas. |
Nota: Las firmas solo se exigen cuando la clave tiene activado
require_signature. Si no lo tiene, la clave de API por sí sola basta para enviar mensajes, y precisamente por eso la clave es un secreto y no un identificador. Trátela como una contraseña: se muestra una sola vez y cualquiera que la tenga puede enviar mensajes a sus clientes.
const crypto = require('node:crypto')
const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()
const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
.update(timestamp + '.' + body)
.digest('hex')
await fetch('https://your-host/api/v1/external/messages/text', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': API_KEY,
'X-Timestamp': timestamp,
'X-API-Signature': signature,
},
body,
})
Endpoints
| Método | Ruta | Propósito |
|---|---|---|
POST | /messages/text | Envía un mensaje de texto sin formato. Solo funciona dentro de una ventana de conversación abierta de 24 horas. |
POST | /messages/template | Envía una plantilla suministrando usted mismo el array de componentes en bruto de Meta. |
POST | /messages/template/send | Envía una plantilla usando la asignación que configuró en el panel. Este es el que conviene usar. |
POST | /messages/interactive/list | Envía un mensaje de lista interactiva. |
POST | /messages/interactive/button | Envía hasta tres botones de respuesta. |
GET | /messages/:uuid | Consulta el estado de entrega de un mensaje que haya enviado. |
POST | /media/upload | Sube un PDF, una imagen o un vídeo a Meta y devuelve un media_id para usarlo en la cabecera de una plantilla. |
GET | /templates | Lista las plantillas disponibles para esta clave. |
GET | /templates/:name | Obtiene los detalles de una plantilla concreta. |
Envío de una plantilla asignada
Esta es la carga útil que se corresponde con la pestaña Templates. Las variables se envían por NOMBRE — los nombres que aparecen como chips en la tarjeta de la plantilla — y la plataforma ensambla por usted los componentes de Meta. Ese es todo el sentido de asignar una plantilla: su sistema de facturación no necesita saber nada del formato de componentes de Meta.
POST /api/v1/external/messages/template/send
{
"to": "+919876543210",
"template_name": "payment_failed_alert",
"language": "en",
"variables": {
"customer_name": "Priya Sharma",
"renewal_date": "12 Aug 2026",
"plan_name": "Wiz Pro"
},
"reference": "invoice-2026-0817"
}
Nota: Los nombres de las variables deben coincidir exactamente con la asignación: un nombre no reconocido se ignora y, si falta uno obligatorio, la solicitud se rechaza con un
400.referencees suyo: se devuelve en los webhooks para que pueda vincular un informe de entrega con un registro de su propio sistema.
Límites de frecuencia
Cada clave tiene sus propios límites, visibles en la pestaña Overview: 60 solicitudes por minuto y 1000 mensajes al día de forma predeterminada. Las respuestas incluyen el margen restante, así que reduzca el ritmo cuando se agote en lugar de reintentar contra un muro.