Endpoint y Método

URL:
Método: POST

Requisitos de Autenticación

• Encabezado X-API-KEY obligatorio.
• La API Key debe estar vigente y contar con el permiso send_sms.
• La API Key se puede generar y gestionar desde la plataforma en la sección de configuración de cuenta.
• Respuestas: 401 Unauthorized si la clave no es válida; 403 Forbidden si carece de permisos.

Modos de Envío

Envía un SMS al número indicado. Existen dos modos mutuamente excluyentes:

1. Mensaje directo: usar messageBody.
2. Basado en Journey BETA: usar journeyID, templateID y templateParams.

Encabezados requeridos

• Content-Type: application/json
• X-API-KEY: tu-api-key-aquí

Parámetros

Parámetro	Tipo	Descripción
recipient	string	Obligatorio. Número móvil en formato internacional, ej. +573001234567.
messageBody	string	Condicional. Texto del SMS. Requerido si no se usa Journey. La longitud máxima depende de la codificación y de caracteres especiales (por ej. GSM vs. UCS2).
journeyID	string	Condicional. GUID del flujo automatizado BETA. Requiere templateID y templateParams. No usar con messageBody.
templateID	string	Condicional. GUID de la plantilla. Obligatorio si se usa Journey.
templateParams	object	Condicional. Variables para la plantilla, ej.: { "name": "María López", "order": "78910" }
programmedDate	string	Opcional. Fecha y hora UTC para envío programado (ISO 8601), ej. 2025-07-11T09:00:00Z. Si se omite, se envía inmediatamente.
flashMessage	boolean	Opcional. Si true, se envía como SMS Flash (no almacenado). Default false.

Notas

• Los mensajes basados en Journey están en estado BETA y pueden cambiar.
• La longitud de messageBody varía según la codificación y caracteres especiales.
• Los mensajes Flash no quedan almacenados en el dispositivo receptor.
• No incluir Journey-fields al usar mensaje directo.

Ejemplos de uso

1. Directo - Solo campos obligatorios

{
  "recipient": "+573001234567",
  "messageBody": "Hola Juan, tu código de acceso es 4572."
}

Respuesta 200:

{
  "smsId": "64ccdfb4ddf40404f498e5b2",
  "status": "Queued"
}

2. Directo - Con programación

{
  "recipient": "+573001234567",
  "messageBody": "Recordatorio: tu cita médica es mañana a las 10:00 AM.",
  "programmedDate": "2025-07-10T08:00:00Z"
}

Respuesta 200:

{
  "smsId": "73dde2b5eedf50405f499e6c3",
  "status": "Queued",
  "scheduledFor": "2025-07-10T08:00:00Z"
}

3. Directo - Mensaje Flash

{
  "recipient": "+573001234567",
  "messageBody": "Alerta de seguridad: se detectó un inicio de sesión desde un dispositivo desconocido.",
  "flashMessage": true
}

Respuesta 200:

{
  "smsId": "82eef3c6ffe060506f500f7d4",
  "status": "Queued"
}

4. Journey BETA - Sin programación

{
  "recipient": "+573001234567",
  "journeyID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "templateID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "templateParams": {
    "customerName": "María López",
    "orderNumber": "78910",
    "deliveryDate": "2025-07-11"
  }
}

Respuesta 200:

{
  "smsId": "91ff04d7a00f710607f511e85",
  "status": "Queued"
}

5. Journey BETA - Con programación y Flash

{
  "recipient": "+573001234567",
  "programmedDate": "2025-07-11T09:00:00Z",
  "journeyID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "templateID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "templateParams": {
    "customerName": "María López",
    "orderNumber": "78910",
    "trackingLink": "https://tracking.example.com/78910"
  },
  "flashMessage": true
}

Respuesta 200:

{
  "smsId": "a2gg15e8b11g820708g622f96",
  "status": "Queued",
  "scheduledFor": "2025-07-11T09:00:00Z"
}

Ejemplos de Respuestas de Error

Las descripciones de error siempre se entregan en inglés.

400 Bad Request

{
  "error": "The 'messageBody' field is required when 'journeyID' is not specified."
}

401 Unauthorized

{
  "error": "API Key is missing or invalid."
}

403 Forbidden

{
  "error": "API Key does not have permission to send SMS."
}

500 Internal Server Error

{
  "error": "Internal server error. Please contact support."
}

{
  "recipient": "+573001234567",
  "messageBody": "Hello John, your access code is 4572."
}

{
  "smsId": "64ccdfb4ddf40404f498e5b2",
  "status": "Queued"
}

{
  "recipient": "+573001234567",
  "messageBody": "Reminder: your medical appointment is tomorrow at 10:00 AM.",
  "programmedDate": "2025-07-10T08:00:00Z"
}

{
  "smsId": "73dde2b5eedf50405f499e6c3",
  "status": "Queued",
  "scheduledFor": "2025-07-10T08:00:00Z"
}

{
  "recipient": "+573001234567",
  "messageBody": "Security alert: a login was detected from an unknown device.",
  "flashMessage": true
}

{
  "smsId": "82eef3c6ffe060506f500f7d4",
  "status": "Queued"
}

{
  "recipient": "+573001234567",
  "journeyID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "templateID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "templateParams": {
    "customerName": "Sarah",
    "orderNumber": "78910",
    "deliveryDate": "2025-07-11"
  }
}

{
  "smsId": "91ff04d7a00f710607f511e85",
  "status": "Queued"
}

{
  "recipient": "+573001234567",
  "programmedDate": "2025-07-11T09:00:00Z",
  "journeyID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "templateID": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "templateParams": {
    "customerName": "Sarah",
    "orderNumber": "78910",
    "trackingLink": "https://tracking.example.com/78910"
  },
  "flashMessage": true
}

{
  "smsId": "a2gg15e8b11g820708g622f96",
  "status": "Queued",
  "scheduledFor": "2025-07-11T09:00:00Z"
}

{
  "error": "The 'messageBody' field is required when 'journeyID' is not specified."
}

{
  "error": "API Key is missing or invalid."
}

{
  "error": "API Key does not have permission to send SMS."
}

{
  "error": "Internal server error. Please contact support."
}