Envíe su primer SMS por API
Esta guía muestra cómo enviar un SMS con la API de demostración, leer los segmentos y la codificación, y seguir los estados. El SMS es simulado mientras no haya un proveedor configurado.
Actualizado el
Antes de empezar
- Una clave de prueba ficticia: tq_test_EXEMPLE.
- Un número remitente y un destinatario en formato E.164 sin espacios. Aquí: +33199001234 y +33199005678, de un rango ficticio.
- Claridad sobre la naturaleza del mensaje: transaccional (ligado a una acción de la persona) o de marketing (comunicación comercial).
Enviar el mensaje
- Redacte el texto. Un SMS largo se divide en varios segmentos, y cada segmento es facturable según su contrato.
- Elija la naturaleza: transactional o marketing. Un mensaje de marketing se rige por reglas propias de cada país, en particular sobre el consentimiento y las listas de exclusión.
- Envíe POST /messages con una Idempotency-Key. Añada scheduled_at y timezone para programar el envío.
curl -X POST https://api.example.test/v1/messages \
-H "Authorization: Bearer tq_test_EXEMPLE" \
-H "Idempotency-Key: 8d4e6b10-2c9a-47f3-b5e1-0a7c3d9f2e64" \
-H "Content-Type: application/json" \
-d '{"from":"+33199001234","to":"+33199005678","text":"Su codigo de prueba es 4821.","nature":"transactional"}'Leer la respuesta
La respuesta indica el estado queued: el mensaje fue aceptado, aún no entregado. Los campos segments y encoding muestran cómo se dividió el texto. La codificación es GSM-7 o UCS-2.
Un solo carácter fuera del alfabeto GSM-7 puede hacer que todo el mensaje pase a UCS-2, lo que reduce el tamaño de cada segmento y puede aumentar su número. Revise el campo segments antes de enviar a gran escala.
{
"id": "msg_EXEMPLE_001",
"status": "queued",
"segments": 1,
"encoding": "GSM-7",
"simulated": true
}Programar un envío
Añada scheduled_at (fecha y hora) y timezone (zona horaria) al cuerpo de la solicitud. Indique siempre la zona horaria: la misma hora no es el mismo momento en París y en Ciudad de México.
{
"from": "+33199001234",
"to": "+33199005678",
"text": "Recordatorio: su cita es manana.",
"nature": "transactional",
"scheduled_at": "2026-11-09T09:00:00",
"timezone": "Europe/Paris"
}Entender los estados
Recibe estos estados mediante los eventos message.sent, message.delivered y message.undelivered, a través de un webhook firmado.
| Estado | Significado |
|---|---|
| queued | Aceptado por la plataforma, aún no transmitido. |
| sent | Transmitido a la red. No es una entrega. |
| delivered | Entregado al dispositivo del destinatario. No significa leído. |
| undelivered | No entregado. La causa no siempre está disponible. |
| unknown | Estado final desconocido. Puede no cambiar nunca: no lo trate ni como fallo ni como éxito. |
Errores frecuentes
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| 400 invalid_request | Número mal formado, nature ausente o distinta de transactional y marketing, texto vacío. | Corrija el campo indicado en el mensaje de error. |
| 409 idempotency_conflict | Misma Idempotency-Key con un texto distinto. | Use una clave nueva para un mensaje nuevo. |
| 429 rate_limited | Ritmo de envío demasiado alto. | Respete Retry-After y reintente. |
| Más segmentos de los previstos | Un carácter especial pasó el mensaje a UCS-2. | Lea encoding y segments y simplifique el texto si hace falta. |
Lo que esta guía no hace
- No envía ningún SMS real mientras no haya un proveedor configurado.
- No promete entrega: un estado delivered no está garantizado, y delivered no significa que el mensaje se haya leído.
- No trata la recepción de SMS. Las respuestas entrantes exigen un número y un país compatibles.
- No sustituye la revisión de sus obligaciones (consentimiento, listas de exclusión, identidad del remitente), que se determinan según el servicio, el país y su papel real.
Preguntas frecuentes
¿Por qué mi SMS cuenta como varios segmentos?
Porque el texto supera el tamaño de un segmento, o porque un carácter especial impuso la codificación UCS-2. El campo segments de la respuesta le da el número exacto antes de cualquier envío real.
¿Puedo enviar a cualquier país?
No. Las capacidades de SMS dependen del país, del proveedor elegido y del contrato. Consulte el catálogo de países y solicite un presupuesto para su alcance.