Envía y recibe SMS con la API
Envía un SMS o MMS desde tus propios sistemas, recibe los mensajes entrantes por webhook, consulta qué pasó con un mensaje enviado, revisa la capacidad de envío que te queda y programa una campaña masiva. Endpoints, encabezados, ejemplos con curl y las prácticas que cuidan tu número.
Qué puedes hacer
La API de Integraciones Privadas permite que tus propios sistemas envíen y reciban mensajes a través de tus números de Zonitel: enviar un SMS o un MMS, recibir los mensajes entrantes en el momento, consultar qué pasó con un mensaje que enviaste, revisar cuánta capacidad de envío te queda y programar una campaña masiva para una fecha futura. Todas las peticiones se hacen contra https://api.zonitel.com/api/v3.
Si todavía no has creado una credencial de acceso, empieza por la guía de Integraciones Privadas y luego vuelve aquí.
Antes de empezar
Cada petición lleva tu token y tu identificador de cliente, de la pestaña Credenciales en Configuración > Integraciones Privadas, como encabezados.
Authorization: Bearer TU_TOKEN
X-Client-Id: TU_CLIENT_ID
Accept: application/json
Escribe los números en formato internacional completo, como +13055550123. El detalle completo de parámetros y respuestas está en la referencia interactiva de la API, y en la pestaña Resumen de esa misma pantalla hay una colección de Postman.
Solo puedes enviar desde un número de tu cuenta habilitado para mensajería. /integrations/numbers lista tus números, y la pantalla de Números de Teléfono muestra cuáles llevan la etiqueta de SMS.
Envía un mensaje de texto
curl --request POST \
--url https://api.zonitel.com/api/v3/integrations/sms/send \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"from": "+13055550123", "to": "+17135550199", "text": "Tu cita está confirmada para el martes a las 10:00."}'
Tres campos: from es uno de tus números de mensajería, to es el destinatario y text es el contenido. Un mensaje largo lo dividen las operadoras en varios segmentos y consume más de uno de tu saldo, así que conviene ser breve en los mensajes transaccionales.
La respuesta de envío contiene data.id, data.segments y data.status. Guarda data.id para la consulta del mensaje que aparece abajo. Un estado sent por sí solo no confirma la entrega al destinatario.
Envía un mensaje con imagen
Añade un arreglo medias al mismo endpoint y el mensaje sale como MMS. Cada entrada es una URL pública que descargamos en el momento del envío, así que el archivo no puede estar detrás de un inicio de sesión.
curl --request POST \
--url https://api.zonitel.com/api/v3/integrations/sms/send \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"from": "+13055550123", "to": "+17135550199", "text": "Aquí tienes la cotización.", "medias": ["https://tusitio.com/archivos/cotizacion.jpg"]}'
Aquí text es opcional. Si lo omites, el destinatario recibe solo la imagen.
Recibe los mensajes entrantes
Los mensajes entrantes llegan a tu sistema por un webhook, igual que las llamadas. Registras una dirección y enviamos un evento a ella cuando llega un mensaje.
Desde el portal
Ve a Configuración > Integraciones Privadas y abre la pestaña Webhooks. Pega tu dirección en el campo de SMS y guarda. La URL tiene que estar activa y responder con HTTP 200 para que se acepte el guardado. Borra el campo y guarda de nuevo para dejar de recibir eventos.
Desde la API
curl --request PUT \
--url https://api.zonitel.com/api/v3/integrations/sms/webhooks \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"url": "https://tusitio.com/webhook/sms"}'
La misma ruta responde a GET, que devuelve la dirección registrada, y a DELETE, que la elimina. Tu servidor debe confirmar con HTTP 200 de inmediato y procesar después, y debe tolerar que el mismo evento llegue dos veces. Recibes dos tipos de evento — uno cuando entra un mensaje y otro con el estado de entrega de un mensaje que enviaste — y ambos están detallados campo por campo en SMS Webhooks.
Para las opciones actuales de autenticación del receptor, consulta SMS Webhooks.
Consulta un mensaje que enviaste
El envío devuelve un identificador del mensaje. Úsalo para revisar después qué pasó con él.
curl --request GET \
--url https://api.zonitel.com/api/v3/integrations/sms/messages/UUID_MENSAJE \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Accept: application/json'
Guarda ese identificador junto a tu propio registro. Es la única forma de relacionar una fila de tu sistema con un mensaje concreto aquí.
Los valores documentados de status en la consulta incluyen created, sent, received, delivered, read y failed. Procesa el valor devuelto; no supongas que todos los canales proporcionan confirmación de lectura.
Revisa la capacidad que te queda
Los mensajes se cuentan por segmentos, no por envíos, y un mensaje largo consume varios. Antes de una campaña, revisa lo que queda en lugar de descubrir el límite a mitad de camino.
curl --request GET \
--url https://api.zonitel.com/api/v3/integrations/sms/stock \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Accept: application/json'
GET /integrations/sms/destinations devuelve los números SMS de la cuenta en data, con uuid, number y label. Es una consulta de números de la cuenta, no una lista de áreas de cobertura internacional. La consulta de saldo anterior devuelve el total restante en data.total.
Campañas masivas y programadas
Un mensaje de grupo llega a una lista de destinatarios en una sola petición, de inmediato o en la fecha que elijas. Cada destinatario lleva un nombre, de modo que el mensaje puede personalizarse.
curl --request POST \
--url https://api.zonitel.com/api/v3/integrations/sms/groups \
--header 'Authorization: Bearer TU_TOKEN' \
--header 'X-Client-Id: TU_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{"from": "+13055550123", "to": [{"name": "Ana", "number": "+13055550001"}, {"name": "Luis", "number": "+13055550002"}], "text": "Nuestra oficina cierra el lunes.", "sendDate": "07/05/2027 12:00"}'
sendDate usa día, mes, año y hora de veinticuatro horas, como en el ejemplo. Omítelo para enviar de inmediato. /integrations/sms/groups también responde a GET para listar tus campañas, y /integrations/sms/groups/ID_GRUPO devuelve una de ellas con su detalle.
Las peticiones de grupo también aceptan medias; proporciona texto o al menos un archivo multimedia. Al revisar un grupo, comprueba cada entrada de data.report: sentAt, recipient, status, errorCode, errorMessage y errorExplanation. Una misma campaña puede tener resultados distintos por destinatario.
Buenas prácticas
- Envía solo a quien aceptó recibir tus mensajes, y respeta de inmediato una respuesta que pide parar. El tráfico de mensajería desde un número de negocio está registrado ante las operadoras, y las quejas ponen en riesgo ese registro.
- Usa una credencial por sistema, y revócala en lugar de compartirla.
- Reintenta un envío fallido con una espera creciente. No repitas en bucle ni reenvíes a ciegas, o el destinatario recibirá el mismo texto dos veces.
- Guarda juntos el identificador del mensaje y el destinatario, para poder responder después a una consulta de soporte.
- Prueba con tu propio teléfono antes de apuntar nada a una lista de clientes.
Las llamadas tienen su propia guía: Sincroniza tus llamadas con la API.
¿Necesitas ayuda?
Llamada/Texto/WhatsApp: (833) 966-4835
Email: info@zonitel.com