SMS API

1. Introducción

La API Bulk SMS de Airtime permite a los clientes enviar mensajes de texto masivos a través de HTTP/HTTPS, con soporte para informes de entrega (DLRs) mediante el mismo protocolo.

  • Los mensajes se envían desde el cliente hacia la API.
  • Los informes de entrega se devuelven a la URL de Callback DLR especificada por el cliente.

2. Tipos de mensajes

Puedes enviar tres tipos de mensajes:

  1. GSM:

    • Mensajes de texto simples (hasta 160 caracteres).
    • Ideales para notificaciones y promociones.

  2. Unicode:

    • Mensajes con caracteres especiales o de otros alfabetos (hasta 70 caracteres).
    • Recomendado para idiomas internacionales o caracteres acentuados.

  3. WSI:

    • Mensajes que incluyen enlaces a contenido web o servicios.
    • Perfecto para promociones con contenido adicional.

3. Envío de SMS

Esta sección explica los pasos y elementos necesarios para enviar mensajes SMS a través de la API.

Los mensajes se envían utilizando el método HTTP POST a las URLs proporcionadas junto con las credenciales de la cuenta. Es importante que el contenido del mensaje esté codificado en un archivo JSON y utilice la codificación UTF-8.

3.1. Campos JSON en el mensaje enviado

A continuación se describen los campos en formato JSON que se deben incluir en el mensaje enviado, comunes para todos los tipos:

NombreTipoDescripción
typestringTipo de mensaje. Puede ser: text o wsi.
Para type='text':
– text: Texto codificado en UTF-8 con el contenido del mensaje.
– dcs: Codificación del mensaje, puede ser gsm (para mensajes GSM) o ucs (para mensajes Unicode).
Para type='wsi':
– url: URL que se mostrará en el mensaje WSI.
– title: Título del mensaje WSI.
senderstringDirección del remitente del SMS, puede ser alfanumérica o numérica.
receiverstringDirección de destino del SMS, debe ser numérica.
dlrMaskintegerMáscara de DLR que representa los reportes de entrega (DLRs) que el cliente desea recibir. Este campo es opcional, y el valor por defecto es 19.
dlrUrlstringURL donde se enviarán los callbacks de los DLRs. Este campo es opcional. Si no se proporciona, se usará la URL configurada en los ajustes de la cuenta en la plataforma.
customobjectObjeto JSON personalizado que se enviará como parte de cada DLR. Este campo es opcional, y su valor predeterminado es vacío.
authobjectObjeto de autenticación que contiene dos campos:
– username: Nombre de usuario de la cuenta.
– password: Contraseña de la cuenta.

3.2. URLs de envío

  • HTTP: http://sms.ejemplo.org/bulk/sendsms

  • HTTPS: https://sms.ejemplo.org/bulk/sendsms

NOTA: En lugar de ‘sms.ejemplo.org’, por favor utiliza las URLs proporcionadas en el archivo Excel con los datos de tu cuenta.

3.3. Mensajes de texto en codificación GSM

				
					{
    "type": "text",
    "auth": {"username": "user", "password": "password"},
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "GSM",
    "text": "Este es un mensaje de prueba",
    "dlrMask": 19,
    "dlrUrl": "http://my-server.com/dlrjson.php"
}

3.4. Mensajes de texto Unicode

				
					{
    "type": "text",
    "auth": {"username": "user", "password": "password"},
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "UCS",
    "text": "Este es un mensaje de prueba con al gunos caracteres UTF-8 üöä€ ",
    "dlrMask": 19,
    "dlrUrl": "http://my-server.com/dlrjson.php"
}

3.5. Mensajes WSI

				
					{
    "type": "wsi",
    "auth": {"username": "user", "password": "password"},
    "sender": "BulkTest",
    "receiver": "41787078880",
    "url": "https://www.ejemplo.com/es/",
    "title": "EJEMPLO",
    "dlrMask": 19,
    "dlrUrl": "http://my-server.com/dlrjson.php"
}

3.3. Respuesta HTTP al enviar un SMS

Si el mensaje es aceptado tiene un status HTTP 200 y el siguiente formato JSON de respuesta:

				
					{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "numParts": 2
}

Dónde:

  • msgId: ID del mensaje, formateado como UUID, utilizado para hacer referencia a este mensaje posteriormente, por ejemplo, en el DLR.
  • numParts: número de partes si el mensaje está concatenado. Si el mensaje se puede enviar como una sola parte de SMS (sin concatenación), numParts será 1.

Si el mensaje es rechazado el status HTTP puede tener varios códigos dependiendo el error.

				
					{
    "error": {
        "code": "107",
        "message": "Invalid sender"
    }
}

4. Recepción de DLRs

Los reportes de entrega (DLR) se envían al cliente a la URL proporcionada en el campo JSON «dlrUrl» al enviar un SMS. Esto es lo que se muestra en formato como respuesta de DLR siguiendo el mismo formato:

				
					{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "partNum": 0,
    "numParts": 1,
    "accountName": "user",
    "sendTime": 0,
    "dlrTime": 2
}

El JSON anterior es un ejemplo de DLR para un mensaje que no está concatenado (numParts=1), por lo tanto, partNum es 0.

Campos en el DLR:

Nombre Tipo Descripción
msgId string ID del mensaje, utilizado para hacer referencia al mensaje, por ejemplo, en el DLR.
event string Uno de los siguientes eventos: DELIVERED, UNDELIVERED, REJECTED, BUFFERED, SENT_TO_SMSC.
errorCode integer Código de error que indica el motivo del fallo de entrega. Cero representa que no hubo error. Consulta la lista de códigos de error de DLR.
errorMessage string Mensaje asociado al código de error.
numParts integer Número total de partes concatenadas. Si el mensaje no está concatenado, será 1.
partNum integer Número de la parte del mensaje. Puede ser un valor dentro del intervalo [0..numParts-1].
sendTime integer Segundos transcurridos desde que el SMS fue enviado hasta que el servicio de Bulk SMS lo envió exitosamente.
dlrTime integer Segundos transcurridos desde que el SMS fue enviado a la ruta hasta que se recibió el reporte de entrega (DLR).

Dependiendo de la configuración de la cuenta, el DLR puede contener campos adicionales:

  • mcc: Código de país móvil (Mobile Country Code) descubierto para el número de destino.
  • mnc: Código de red móvil (Mobile Network Code) descubierto para el número de destino.
  • country: Código ISO2 del país donde está registrado el número de destino.
  • price: El precio del SMS (esta información es informal y puede estar sujeta a cambios).
  • currency: La moneda del precio.

Si el SMS se envía con el campo «custom», el DLR tendrá:

  • custom: El mismo objeto enviado de vuelta en cada DLR.

Cuando un mensaje es concatenado, el cliente lo envía como una sola solicitud, y luego el servicio de Bulk lo divide en las partes necesarias de SMS. Los DLRs se envían a la URL de Callback para cada parte del SMS de manera independiente.