Introducción

La API SMS programable de Vox le permite enviar y recibir mensajes SMS desde y hacia cualquier país del mundo a través de una sencilla API REST.

Inicio

Para poder utilizar la API de Vox, necesita tener una cuenta con Vox, por favor contacte con su representante de Vox.

Autenticación

La API de Vox utiliza el nombre de usuario y la contraseña para autenticar las solicitudes. Puede crear, recuperar y gestionar sus credenciales API poniéndose en contacto con su gestor de cuenta de Vox.
Cada llamada API requiere sus credenciales API como parte del cuerpo JSON:

username: string
password: string

Punto final de la API de SMS

La API de Vox utiliza verbos HTTP para saber si desea crear (POST) un objeto.

El formato de la solicitud debe ser JSON:

POST https://:8002/api

Referencia API

Esta sección proporciona información detallada sobre la solicitud y los parámetros de respuesta, los códigos de estado de la solicitud y los estados de entrega de los mensajes devueltos en los informes de entrega.

Parámetros requeridos

Si el mensaje contiene caracteres fuera del rango de las tablas GSM Standard y Extended, la codificación de caracteres se establecerá en 8 – UCS2 (dataCoding=8 como parámetro de consulta).

Parámetros de respuesta

Nota: La respuesta se devuelve en formato de datos JSON.

Parámetros de consulta de devolución de llamada

Estos son los parámetros de la API Callback con los que puede recuperar información sobre un SMS enviado. Se admiten los métodos GET y POST. Para configurar y dar formato a los parámetros de la API Callback, póngase en contacto con el gestor de su cuenta para que lo configure en su cuenta.

Informes de entrega

Los informes de entrega relacionados con los mensajes SMS enviados están disponibles a través de devoluciones de llamada a una URL de devolución de llamada dedicada. La URL de devolución de llamada es individual para cada cliente de Vox – y puede ser configurada con su Gestor de Cuenta Vox.

Los informes de entrega también pueden consultarse y enviarse como respuesta de la API.

La solicitud GET se utiliza para consultar el informe de entrega y deben incluirse los siguientes parámetros:

Todos los parámetros son obligatorios.

Estado de entrega del mensaje

Estos son los estados devueltos en los informes de entrega:

Uso de la API

Esta sección muestra cómo utilizar la API SMS de Vox.

Enviar SMS

Este ejemplo muestra cómo enviar un SMS diciendo «¡Hola, soy Vox!» con la codificación de caracteres por defecto

al destinatario +381 63 XXXXXXX:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"message":"Hello, this is Vox!"
}'

Respuesta:

{
    "message_id": "9be2ea-32028-e8cb8-11552-36b84-24825"
}

Enviar SMS masivos

Este ejemplo muestra cómo enviar un SMS A GRANEL diciendo «¡Hola, soy Vox 123!» con la codificación de caracteres predeterminada a varios destinatarios:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX, 38164YYYYYYY",
"message":"Hello, this is Vox!"
}'

Respuesta:

[{"dnis":"38163XXXXXXX ","message_id":"5b4c46a8-8dc9-34b4-f55f-3bef56819305"},
{"dnis":"38164YYYYYYY ","message_id":"5b4c46a8-46bc-7uu6-4a16-7d4e5a0d14af"}]

Codificación del mensaje

Este ejemplo muestra cómo enviar un SMS con caracteres Unicode:

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"dataCoding":"8",
"message":"Hello, this is Vox ❤️ !"
}'

Enviar mensajes largos

Este ejemplo muestra cómo enviar un SMS con un texto que supera el número máximo de caracteres permitido (160 para UTF-8, 70 para Unicode).

curl --location 'https://XXXXXXXXX:8002/api' \
--header 'Content-Type: application/json' \
--data '{
"username":"xxxxxx",
"password":"yyyyy",
"command":"submit",
"ani":"Vox SMS",
"dnis":"38163XXXXXXX",
"longMessageMode":"single_id_split",
"message":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum"
}'

Respuesta:

Response:
{
    "message_id": "1175d2-11575-48a3a-03818-eedf2-16692"
}

Protocolo SMPP

Esta sección proporciona los detalles técnicos necesarios para que los arquitectos y desarrolladores de software puedan crear clientes Short Message Peer-to-Peer (SMPP) que se integren con la interfaz SMPP de Vox. Estos detalles incluyen los requisitos de integración, los métodos admitidos, los tipos de enlace, los requisitos de autenticación, los esquemas de codificación de datos, los temporizadores, los informes de entrega, los códigos de error y otros detalles de los mensajes.

Importante: Vox es compatible con la versión 3.4

Introducción

El SMPP es un protocolo abierto y estándar de la industria (véase la definición en Wikipedia) diseñado para simplificar las interconexiones entre varias entidades. El SMPP también permite enviar y recibir mensajes cortos de texto (SMS) a través de Internet.

Conectarse a Vox utilizando el protocolo SMPP requiere un conocimiento profundo de SMPP. Para saber más antes de seguir leyendo sobre las particularidades de la integración SMPP de Vox, visite smpp.org. Allí también podrá encontrar documentos de referencia para la v3.4 de la especificación (las versiones que soporta Vox).

Configuración SMPP requerida

En cada ESME debe configurarse lo siguiente:

PDU compatibles

Vox soporta los siguientes comandos de unidad de datos de protocolo (PDU):

Tipos de sesión admitidos

Vox permite tres tipos de sesiones iniciadas por ESME:

• Transmisor (TX)
• Receptor (RX)
• Transceptor (TRX)

Los clientes pueden habilitar hasta los tres tipos de sesión, aunque se prefieren los enlaces TRX persistentes. Póngase en contacto con su representante de Vox para habilitar y configurar estas sesiones.

Información de conexión

Dirección de la pasarela SMPP: sms.voxcarrier.com

Puerto: 2876
Dirección IP: 163.172.233.79

Autenticación

Cada ESME que solicite enlazarse a la Vox debe proporcionar un nombre de usuario para identificarse y una contraseña para autenticarse.

Obtenga estas credenciales rellenando el formulario de interconexión SMPP de Vox. Su representante de Vox le comunicará la última versión. Una vez creada su cuenta, le proporcionarán su nombre de usuario (ID del sistema) y su contraseña.

Las contraseñas SMPP no pueden ser recuperadas para usted por Vox.

Restablecimiento de la contraseña – Puede restablecer la contraseña del SMPP pidiendo a su representante de Vox que lo haga por usted.

Requisitos operativos

Los clientes deben seguir estos requisitos operativos cuando se conecten a Vox a través de SMPP, con el fin de que Vox proporcione el máximo nivel de calidad, seguridad y conectividad.

Los clientes deben:

• Disponga de un número suficiente de enlaces para soportar el 100% del tráfico de clientes.
• Asegúrese de que el campo con la dirección de la pasarela SMPP es configurable. Ocasionalmente Vox puede cambiar la dirección de la pasarela SMPP.
• Disponga de una lógica de conmutación por error automática para redirigir el tráfico a los enlaces activos disponibles en cada momento.
• Implemente la encriptación Transport Layer Security (TLS) 1.2 para todas las comunicaciones SMPP.

Enviar SMS

1. Establecer una sesión mediante una solicitud bind

Tras introducir los parámetros de conectividad proporcionados por Vox (IP, puerto, nombre de usuario, contraseña) en el cliente SMPP, se establecerá una conexión entre su sistema y Vox mediante una de las operaciones bind descritas anteriormente.

Si desea poder enviar SMS salientes y recibir los DLR, necesita una sesión de transceptor o una sesión de emisor y otra de receptor.

Dispondrá del mismo ancho de banda independientemente del número de sesiones que establezca.

2. Acuso de recibido de la solicitud de enlace

Después de que Vox reciba una solicitud bind con los parámetros de autenticación correctos, se emitirá un bind_resp y la sesión estará disponible para la comunicación.

3. Enviar un mensaje

Los mensajes se envían a Vox utilizando la operación submit_sm. La operación submit_sm y la PDU se describen detalladamente en la documentación de SMPP 3.4.

4. Acuso de recibido del mensaje enviado

Después de que Vox reciba una solicitud submit_sm correcta, se emitirá un submit_sm_resp. El submit_sm_resp contiene el ID del mensaje en el parámetro message_id, que es un identificador único para cada mensaje. Puede variar en formato y longitud.

El envío del mensaje a Vox se finaliza con la emisión del submit_sm_resp. Los mensajes se almacenan en el SMSC de Vox y serán entregados al receptor. Si el primer intento de entrega no tiene éxito – por ejemplo, el teléfono móvil receptor está apagado – se realizarán nuevos intentos de entrega del mensaje. El mensaje se conservará en el SMSC de Vox hasta 48 horas, transcurridas las cuales caducará.

5. Envío de un recibo de entrega (DLR), opcional

Una vez que un mensaje alcanza un estado final (entregado, no se puede entregar, caducado), Vox crea un acuso de de recibido si así se solicita en el submit_sm inicial. El DLR se le enviará a través de una sesión de receptor o transceptor existente mediante la operación deliver_sm. El propio acuse de recibo se incluye en el parámetro de texto de la PDU deliver_sm.

6. Acuso de recibido del DLR presentado

Debe acusar recibo de un deliver_sm con un deliver_sm_resp, de lo contrario Vox seguirá reenviando el deliver_sm.

Recibir SMS

1. Establecer una sesión mediante una solicitud bind

Tras introducir los parámetros de conectividad proporcionados por Vox (IP, puerto, nombre de usuario, contraseña) en el cliente SMPP, se establecerá una conexión entre su sistema y Vox mediante una de las operaciones de enlace descritas anteriormente. Para recibir SMS de Vox, se necesita una sesión de receptor o transceptor. La sesión debe permanecer abierta para que podamos entregarle los mensajes.

2. Acuso de recibido de la solicitud de enlace

Después de que Vox reciba una solicitud bind con la autenticación correcta, se emitirá un bind_resp y la sesión estará disponible para la comunicación.

3. Recepción de un mensaje

Cuando Vox recibe un mensaje en uno de los números de entrada que le han sido asignados, éste es retransmitido a su plataforma mediante la operación deliver_sm. Para más detalles sobre la operación deliver_sm y la PDU, consulte la documentación de SMPP 3.4.

4. Acuso de recibido del mensaje recibido

Tras recibir un deliver_sm, deberá acusar recibo respondiendo con un deliver_sm_resp. De lo contrario, le volveremos a enviar el deliver_sm.