Enviar mensajes de WhatsApp con la API
Comprueba el acceso a WhatsApp, elige un número del negocio y envía un mensaje o una plantilla aprobada mediante la API de Zonitel.
Utiliza la API de Zonitel para comprobar la disponibilidad de WhatsApp, elegir un número del negocio y enviar texto libre o plantillas aprobadas desde tu software. Zonitel resuelve automáticamente el hilo de conversación.
Antes de comenzar
Conecta primero WhatsApp en Zonitel Office siguiendo Conectar WhatsApp Business. El alta no puede completarse mediante la API. Tu cuenta necesita acceso activo a WhatsApp y un número del negocio disponible para enviar.
Crea una credencial de Zonitel desde Private Integrations. Todas las peticiones usan Authorization: Bearer YOUR_TOKEN y X-Client-Id: YOUR_CLIENT_ID. Conserva ambos valores en tu servidor.
Reemplaza los marcadores en mayúsculas antes de ejecutar los ejemplos. YOUR_WHATSAPP_NUMBER y RECIPIENT_NUMBER deben ser números internacionales completos en formato E.164, con el código de país. Utiliza un destinatario que haya aceptado recibir tus mensajes.
1. Comprueba si la cuenta puede enviar
curl --request GET \
--url https://api.zonitel.com/api/v3/integrations/whatsapp/status \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'Accept: application/json'Lee primero canSend. Una respuesta HTTP 200 con canSend: false es un resultado normal de disponibilidad. Revisa reason y message para saber qué falta. La respuesta también incluye onboarded, subscribed, accessUntil y usableNumbers.
Resuelve el motivo indicado en Office antes de intentar enviar. En la configuración de WhatsApp, utiliza Business config para el negocio conectado, Subscription para el acceso y Numbers & templates para los números y mensajes aprobados.
2. Elige el remitente y el tipo de mensaje
Con los mismos encabezados de autenticación, solicita GET https://api.zonitel.com/api/v3/integrations/whatsapp/numbers. Utiliza el number devuelto como from; no necesitas proporcionar el identificador interno del número en Meta. El resultado también muestra verifiedName, isDefault y receivesReplies.
- Ventana de conversación de 24 horas abierta: puedes enviar texto libre.
- Ventana cerrada: utiliza una plantilla aprobada para contactar al destinatario.
Para elegir una plantilla, solicita GET https://api.zonitel.com/api/v3/integrations/whatsapp/templates. Revisa name, language, body y paramsCount. Esta ruta lista las plantillas aprobadas. La cantidad y el orden de los valores deben coincidir con las variables de la plantilla.
3. Envía el mensaje
Para texto libre mientras la ventana de conversación está abierta:
curl --request POST \
--url https://api.zonitel.com/api/v3/integrations/whatsapp/send \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"from":"YOUR_WHATSAPP_NUMBER","to":"RECIPIENT_NUMBER","text":"Tu cita está confirmada."}'Para una plantilla aprobada, reemplaza APPROVED_TEMPLATE_NAME por un nombre devuelto para tu cuenta. Este ejemplo supone que la plantilla tiene exactamente dos variables en el cuerpo:
curl --request POST \
--url https://api.zonitel.com/api/v3/integrations/whatsapp/send \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"from":"YOUR_WHATSAPP_NUMBER","to":"RECIPIENT_NUMBER","template":{"name":"APPROVED_TEMPLATE_NAME","params":["CUSTOMER_NAME","APPOINTMENT_TIME"]}}'El esquema de envío también admite medias y buttonParams de la plantilla. Consulta su estructura y los parámetros que necesita tu plantilla aprobada en la referencia API.
Revisa el resultado antes de reintentar
Una respuesta correcta incluye id, conversationId, type, status, direction, from y to. Guarda los identificadores del mensaje y de la conversación junto a tu registro. sent confirma el resultado del envío; no demuestra que se haya entregado o leído.
- 400: revisa los campos obligatorios, el número remitente, la aprobación de la plantilla y la cantidad de variables.
- 401: revisa el token de Zonitel y el identificador del cliente.
- 403: consulta la disponibilidad y resuelve en Office el acceso o la conexión de WhatsApp que falta.
- 502: lee el mensaje de error. Si la ventana está cerrada, envía una plantilla aprobada en lugar de repetir texto libre. Otros fallos temporales pueden requerir un reintento posterior.
Si una petición agota el tiempo de espera, revisa la conversación antes de reenviar para evitar duplicados. Comienza con un destinatario de prueba autorizado antes de automatizar mensajes a clientes.