SMS API
Documentación técnica: API de SMS.

Términos importantes

MT
Mobile Terminated
Es un termino utilizado para mensajes que poseen el usuario (Aparato) como destino. O sea, mensajes que fueron originados por su empresa con destino al usuario (Aparato).
Response
Respuesta sincronica de Wavy
Es una respuesta inmediata de una solicitud hecha en nuestra API, donde informamos si el mensaje fue aceptado o no por nuestra plataforma
Callback
Sent status o Estatus de envió
Es el primer status de envió que retornamos, en el informamos si fue posible, o no, hacer la entrega del mensaje. para la operadora.
DR ou DLR
Delivery Receipt
Es el segundo status de envió que retornamos, donde informamos si fue posible, o no, hacer la entrega para el aparato. Las operadoras envían para Wavy esta información y nosotros la entregamos al cliente. El tiempo de entrega es variable, por ejemplo si el aparato estaba apagado en el momento del envió y el usuario lo encendió 2 horas después este status DLR sera entregado al cliente con 2 horas de atraso. Obs1: Esta confirmación de entrega en el aparato, existirá solamente para casos en que el mensaje fue entregado con éxito en la operadora. O sea, el primer status (Callback) fue de exito. Obs2: Es muy importante resaltar que infelizmente las operadoras OI y Sercomtel no poseen esta funcionalidad, o sea, no nos retornan la información de entrega en el aparato. Los envíos realizados para números de estas operadoras tendrán solamente la informacion de entrega en la operadora (callback)
MO
Mobile Originated
Es el termino utilizado para mensajes que poseen su empresa como destino. O sea, mensajes que fueron originados por el usuario (Aparato). Y utilizado por ejemplo en flujos de preguntas y respuestas vía SMS, cuando es necesario una confirmación por parte del usuario.
LA
Short Code
Numero corto de 5 o 6 digitos, utilizados para envio y recibimiento de mensajes SMS. Son designados por las operadoras para integradores homologados (Wavy), y poseen reglas anti-fraude y anti-spam.

Flujo de Mensajes

Flujo simplificado: MT, Callback, DLR, MO

API HTTPS

Esta API permite que usted automatice las solicitudes de envíos de mensajes únicas o en lotes, y la recuperación de los estatus de envíos a travez de consultas. Ella utiliza el protocolo HTTP con TLS y acepta los métodos GET con parámetros query string o POST con parámetros en JSON.

Autenticacion

Para efectuar envíos y consultas en nuestra API es necesaria una autenticacion por medio de usuario o e-mail, en conjunto con un token.
Campo
Detalles
Data Type
UserName
Su usuário o email
String
AuthenticationToken
Su token de autenticacion. Verifique aqui y lea las siguientes descripciones de usuarios.
String
Tipo
Detalles
Administrador
Usuario administrador de su empresa, es utilizado para crear/editar/desactivar sub cuentas y otros usuarios y visualizar informes de toda la empresa. Este usuario no hace envíos de mensajes ni por el portal ni vía integración API.
Usuario
Usuario utilizado para envió de mensajes via API y portal, puede visualizar informes especificos de su sub cuenta. Un usuario es siempre relacionado a una única sub cuenta. Una sub cuenta puede contener multipes usuarios. Cada sub cuenta es un centro de costo en nuestra plataforma, los mensajes son discriminados en informes y financieramente por sub cuenta y no por usuario.

Detalles de conexión

Hostname
api-messaging.wavy.global
APIs
Envíos individuales /v1/send-sms Envíos en lote /v1/send-bulk-sms
Puerta
443 (https)
Protocolo
HTTPS (encriptacion TLS)
Autenticacion
username + token
Portal
messaging.wavy.global

Codificación (encoding)

El estándar de codificación utilizado es UTF-8, todo el contenido de los mensajes deben seguir ese estándar.
Es posible escapar los caracteres caso desee codificar utilizando el formato HTTP
A seguir algunos ejemplos de codificación
“messageText”:“La combinación fue perfecta :)”
O usted puede escapar los caracteres en el caso que quiera:
“messageText”:“La combina\u00e7\u00e3o fue perfecta :)”

Envió de mensajes (MT)

Envio por método GET - Individual

1
curl -X POST \
2
https://api-messaging.wavy.global/v1/send-sms \
3
-H 'authenticationtoken: <authenticationtoken>' \
4
-H 'username: <username>' \
5
-H 'content-type: application/json' \
6
-d '{"destination": "5511900000000" , "messageText": "linha\nquebrada"}'
7
Copied!
Al hacer el envió usted recibirá un JSON informando el id que fue generado para este mensaje (Response o Respuesta sincrona de Wavy):
1
[
2
{
3
"id":"9cb87d36-79af-11e5-89f3-1b0591cdf807",
4
"correlationId":"myId"
5
}
6
]
Copied!
Vía método GET, es posible realizar el envió de un mensaje pasando todos los parámetros como query string

URL para envíos unitarios via GET

GET https://api-messaging.wavy.global/v1/send-sms?destination=..
Vía método POST, es posible realizar el envió de un mensaje pasando todos los parámetros como body
URL para envíos unitarios via POST
POST https://api-messaging.wavy.global/v1/send-sms - Content-Type: application/json

Parametros

* Campo obligatorio
Campo
Detalles
Tipo
destination*
Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000
String
messageText*
Texto del mensaje que sera enviado (max 1280 chars).
String
correlationId
Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Wavy para coincidencia (max 64 chars).
String
extraInfo
Cualquier información extra que usted desee adicionar al mensaje (max 255 chars).
String
timeWindow
Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59, este parámetro se debe definir en la raíz del objeto JSON
Integer[]
expiresAt
Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
expiresInMinutes
El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Wavy. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
expiresDate
El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
String
scheduledAt
El mensaje no sera enviado después de esta fecha. ¡IMPORTANTE! Es posible realizar una agenda solo en un período superior a 30 minutos, un proceso por el cual fluxo diferenciado do envio sem agendamento. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
delayedInMinutes
Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
scheduledDate
El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
String
timeZone
Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC
String
campaignAlias
Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña, este parámetro se debe definir en la raíz del objeto JSON
String
flashSMS
Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true.
Boolean
flowId
Identificador del flujo del bot. El mensaje de texto provendrá del flujo
String
subAccount
Referencia de subcuenta. Solo puede ser utilizado por Administradores.
String
params
Mapa de marcadores de posición que serán reemplazados en el mensaje. Si uno o más parámetros son incorrectos, el mensaje se marcará como no válido, pero el envío no se cancelará. Es necesario enviar el flowId para utilizar los parámetros
Map
IMPORTANTE! Para cada usuario existe un token de autenticacion único

Envio por método POST - Individual o e lote

1
curl --request POST \
2
--url https://api-messaging.wavy.global/v1/send-bulk-sms \
3
--header 'authenticationtoken: <Token de autenticação>' \
4
--header 'username:<Usuário Movile Messaging>' \
5
--header 'content-type: application/json' \
6
--data "{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}"
7
Copied!
Al hacer el envió, retornara un objeto JSON con un UUID del lote e de los mensajes individuales :
1
2
{
3
"id": "ce528d70-013b-11e7-98f2-e27c463c8809",
4
"messages": [
5
{
6
"id": "ce528d71-013b-11e7-98f2-e27c463c8809"
7
},
8
{
9
"id": "ce528d72-013b-11e7-98f2-e27c463c8809"
10
}
11
]
12
}
Copied!
Permite el envió de mensajes en lote o individuales pasando los parámetros de un objeto JSON Existe um limite de 1000 mensajes por solicitud
Existe um limite de 1000 mensajes por solicitud

Solicitud HTTP Method POST

Ejemplo de JSON para envio em Lote:
Exemplo 1:
1
{
2
"messages":[
3
{
4
"destination":"5519900001111",
5
"messageText":"First message"
6
},
7
{
8
"destination":"5519900002222"
9
},
10
{
11
"destination":"5519900003333"
12
}
13
],
14
"defaultValues":{
15
"messageText":"Default message"
16
}
17
}
Copied!
Exemplo 2:
1
{
2
"messages":[
3
{
4
"destination":"5519900001111",
5
"messageText":"First message"
6
},
7
{
8
"destination":"5519900002222"
9
}
10
],
11
"timeZone":"America/Sao_Paulo",
12
"scheduledDate": "2017-01-28T02:30:43",
13
"timeWindow": [12, 15, 20],
14
"defaultValues":{
15
"messageText":"Default message"
16
}
17
}
Copied!
Exemplo 3:
1
`
2
{
3
"messages":[
4
{
5
"destination":"5519900001111",
6
},
7
{
8
"destination":"5519900002222"
9
}
10
],
11
"defaultValues":{
12
"messageText":"Default message",
13
"flashSMS":"true"
14
}
15
}
Copied!
Ejemplo 4, com flowId y params:
1
{
2
"messages":[
3
{
4
"destination":"5519900001111",
5
"params": {
6
"param1": "other_value1",
7
"param2": "other_value2"
8
}
9
},
10
{
11
"destination":"5519900002222"
12
}
13
],
14
"defaultValues":{
15
"params": {
16
"param1": "value1",
17
"param2": "value2"
18
}
19
},
20
"flowId": "14f8142d-e731-4971-8220-5a76a12c413f"
21
}
Copied!
Observe que en los ejemplos de arriba, algunos campos “destination” no tienen un “messageText” atribuido directamente para ellos, en este caso, el texto del mensaje sera el “messageText” dentro de “defaultValues”. Esa función es útil cuando es necesario el envió del mismo mensaje para varios números diferentes.
POST https://api-messaging.wavy.global/v1/send-bulk-sms Content-Type: application/json
El cuerpo de la solicitud necesita contener el objeto JSON con las informaciones conforme los campos abajo:
* Campo obligatorio
Campo
Detalles
Tipo
destination*
Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000
String
messageText*
Texto del mensaje que sera enviado (max 1280 chars).
String
correlationId
Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Wavy para coincidencia (max 64 chars).
String
extraInfo
Cualquier información extra que usted desee adicionar al mensaje (max 255 chars).
String
timeWindow
Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59
Integer[]
expiresAt
Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
expiresInMinutes
El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Wavy. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
expiresDate
El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
String
scheduledAt
El mensaje no sera enviado después de esta fecha. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
delayedInMinutes
Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
Long
scheduledDate
El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos)
String
timeZone
Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC
String
campaignAlias
Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña
String
flashSMS
Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true.
Boolean
flowId
Identificador del flujo del bot. El mensaje de texto provendrá del flujo
String
subAccount
Referencia de subcuenta. Solo puede ser utilizado por Administradores.
String
params
Mapa de marcadores de posición que serán reemplazados en el mensaje. Si uno o más parámetros son incorrectos, el mensaje se marcará como no válido, pero el envío no se cancelará. Es necesario enviar el flowId para utilizar los parámetros
Map
IMPORTANTE! Para cada usuario existe un token de autenticacion único

Respuestas de mensajes en lote

La respuesta de envíos en lote contendrá un archivo JSON con las informaciones necesarias para su rastreamiento, sera generado un id para todo el lote y un id y correlationid individual para cada mensaje:
Campo
Detalles
Tipo
id
UUID generado para este lote
String
messages
Este campo es un array con las respuestas de los mensajes individuales del lote, contiene el id y el correlationid de cada mensaje enviado.
SingleSMSResponse[]

Respuesta del código de estado HTTP

Código de estado de respuesta HTTP común:
Grupo
Descripción
2xx
El éxito
4xx
Error del cliente
5xx
Error del servidor
Código
Descripción
200
El éxito
400
Mal pedido
401
No autorizado
403
Prohibido
404
No encontrado
429
Muchas solicitudes hechas
500
Error interno del servidor
503
Servicio no disponible
504
Tiempo de espera
El límite máximo es de 700 solicitudes por segundo por IP.

Estatus de envio (Callback e DLR)

Existen dos maneras de obtener los estatus de envíos de los mensajes, son ellas:
    Webhook - Recibir los estatus en un webservice de su empresa (recomendado)
Cuando entregamos el mensaje en la operadora, o en el momento que la operadora nos informa que se entrego el mensaje en el aparato, la información es pasada instantáneamente para usted.
    API de consulta - Hacer solicitudes de consulta en nuestra API sms-status.
Los estatus quedan disponibles por 3 días, e pueden ser consultados por el UUID que Wavy retorno al recibir el mensaje de su empresa, o por el ID que su empresa paso al entregar el mensaje para Wavy. La desventaja de esta opción de consulta al revés de webhook, es que usted hará solicitudes de consulta de un ID que puede todavía no haber sido entregado en la operadora o en el aparato, en este caso, una serie de solicitudes innecesarias serán realizadas. Por ejemplo, si un usuario estaba con el aparato apagado cuando envio un mensaje para el y lo encendió dos horas después, usted consultara este ID innumerables veces por dos horas. En el caso de la utilización de webhook, esta información seria enviada para usted en el momento que el mensaje fuese entregado en el aparato, sin solicitudes vaciás.
¡IMPORTANTE! Las consultas de estado tienen un límite de 1 solicitud por segundo por dirección IP. Las solicitudes, más allá de este límite, seran respondidas con el código de estado HTTP 429.

Estatus via webhook (entrega en su webservice)

Para configurar el envió de los Callbacks y DRs primeramente es necesario loguear en Wavy messaging las configuraciones de la API, en el formulario de configuración usted podrá proveer las URLs para donde serán enviados los estatus de envió (Callbacks) y los estatus de confirmación de entrega en el aparato (DRs)
Después de la inclusión de su webhook en el portal arriba, las configuraciones serán replicadas para nuestra plataforma en hasta 10 minutos, y llamaremos su URL cuando las siguientes acciones ocurran:
Accion
Estatus de retorno enviado
Después que un mensaje fue entregado o no, en la operadora
API de estatus de envió (callback)
Cuando un mensaje fue entregado o no, en el aparato del cliente
API de Delivery Report (DRs)
Ejemplo JSON Estatus de Envio (callback - entrega en la operadora)
1
POST https://example.com/callback/
2
Content-Type: application/json
3
4
{
5
"id":"f9c100ff-aed0-4456-898c-e57d754c439c",
6
"correlationId":"client-id",
7
"carrierId":1,
8
"carrierName":"VIVO",
9
"destination":"5511900009999",
10
"sentStatusCode":2,
11
"sentStatus":"SENT_SUCCESS",
12
"sentAt":1266660300000,
13
"sentDate":"2010-02-20T10:05:00Z",
14
"campaignId":"64",
15
"extraInfo":"",
16
}
Copied!

Campos JSON respuesta Callbacks (sent status)

Campo
Descripción
id
UUID generado del mensaje
correlationId
Su identificación de este mensaje
carrierId
Identificador de la operadora
carrierName
Nombre de la operadora
destination
Número de telefone da mensagem enviada
sentStatusCode
Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus
descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones.
sentAt
Hora do envió, el formato utilizado es Unix_time.
sentDate
Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
campaignId
Identificador de campaña en el caso que exista.
extraInfo
Cualquier información extra adicionada por el cliente en el envió del mensaje

Campos JSON respuesta Delivery Reports (DRs)

Campo
Descripción
id
UUID generado del mensaje
correlationId
Su identificación de este mensaje
carrierId
Identificador de la operadora
carrierName
Nombre de la operadora
destination
Número de telefone da mensagem enviada
sentStatusCode
Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus
descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones.
sentAt
Hora do envió, el formato utilizado es Unix_time.
sentDate
Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
deliveredStatusCode
Código de estatus generado por Wavy para un mensaje indicando el estatus de envió. Verifique en el código de estatus para mas informaciones
deliveredStatus
descripción de estatus de envió. Verifique en código de estatus para mas informaciones.
deliveredAt
Hora do envió, el formato utilizado es Unix_time.
deliveredDate
Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ
campaignId
Identificador de campaña en el caso que exista.
extraInfo
Cualquier información extra adicionada por el cliente en el envió del mensaje

Consulta Estatus via solicitud HTTP

Para consultar el estatus del ultimos mensaje enviado es necesario hacer una solicitud GET en la URL abajo pasando como parámetro el UUID(s) o el correlationId(s) obtenido en la respuesta del envió.
GET https://api-messaging.wavy.global/v1/sms/status/search
{ "ids": ["918F3591-9AD6-11E7-9C9B-E255B01A8B1A","234F3591-6AD6-11E7-9C9B-E255B01A8B1A"], "correlationIds": ["2468"] }
También es posible obtener sólo el estado aún no consultado:
GET https://api-messaging.wavy.global/v1/sms/status/list
Observe que este endpoint devuelve sólo el estado que no se devuelve por este punto final.

Respuesta

Campos JSON de respuesta:
Campo
Detalles
Tipo
id
UUID generado en la solicitud para el mensaje
String
correlationId
Mismo correlationId de la solicitud
String
carrierId
ID de la operadora, para mas informaciones consulte el código de error
Long
carrierName
Nombre da la operadora
String
destination
Número de telefono del mensaje enviado
String
sentStatusCode
sentStatusCode
Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones.
sentStatus
Descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones.
String
sentStatusAt
Cuando el mensaje fue enviado. Es un Epoch Date
Long
sentStatusDate
Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601)
String
deliveredStatusCode
Código de estatus indicando el estatus de envió. Verifique en el código de estatus para mas informaciones.
Long
deliveredStatus
Descripción de estatus de envió. Verifique en código de estatus para mas informaciones.
String
deliveredAt
Cuando el mensaje fue enviado. Es un Epoch Date
Long
deliveredDate
Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601)
String
campaignId
Identificador de campaña
Long
extraInfo
Cualquier información extra adicionada por el cliente en el envió del mensaje
String
Ejemplo JSON Delivery Report (DR ou DLR - Entrega en el aparato del usuario)
1
{
2
"id":"8f5af680-973e-11e4-ad43-4ee58e9a13a6",
3
"correlationId":"myId",
4
"carrierId":5,
5
"carrierName":"TIM",
6
"destination":"5519900001111",
7
"sentStatusCode":2,
8
"sentStatus":"SENT_SUCCESS",
9
"sentStatusAt":1420732929252,
10
"sentStatusDate":"2015-01-08T16:02:09Z",
11
"deliveredStatusCode":4,
12
"deliveredStatus":"DELIVERED_SUCCESS",
13
"deliveredAt":1420732954000,
14
"deliveredDate":"2015-01-08T16:02:34Z",
15
"campaignId":1234
16
}
Copied!

Respuesta del usuario (MO)

La API de MO permite la automatización del proceso de recuperación de respuestas enviadas por los clientes a los mensajes que usted le envió a ellos. Todas las solicitudes usan el método GET y las respuestas son enviadas en formato JSON
IMPORTANTE! El recibimiento de MOs esta habilitado y estandarizado solo para los LAs 27182 y 28149, en el caso que sea necesario recibir los mensajes a través de otros LAs sera necesario entrar en contacto con el soporte para evaluar.
Es posible también la configuración para que los MOs sean encaminados conforme llegan, para una API del cliente. Esa es la forma mas eficiente ya que no es necesario realizar ninguna llamada, solo se tratan los envíos conforme van llegando. Para que esta configuración sea realizada es necesario abrir un ticket con nuestro equipo de soporte técnico a través del e-mail [email protected] pasando la URL que recibirán los MOs
Hemos podido enviar los MOs tanto vía método GET (query string) como vía método POST (Json)
Ejemplo JSON enviado a su API (método POST)
1
{
2
"id": "25950050-7362-11e6-be62-001b7843e7d4",
3
"subAccount": "iFoodMarketing",
4
"campaignAlias": "iFoodPromo",
5
"carrierId": 1,
6
"carrierName": "VIVO",
7
"source": "5516981562820",
8
"shortCode": "28128",
9
"messageText": "Eu quero pizza",
10
"receivedAt": 1473088405588,
11
"receivedDate": "2016-09-05T12:13:25Z",
12
"mt": {
13
"id": "8be584fd-2554-439b-9ba9-aab507278992",
14
"correlationId": "1876",
15
"username": "iFoodCS",
16
"email": "[email protected]"
17
}
18
}
19
Copied!
Cada solicitud realizada retornara los MOs de los últimos 3 días, hasta un limite de 1.000 MOs. Para las fechas anteriores o cantidades mayores por favor entrar en contacto con nuestro equipo de soporte a través del e-mail [email protected]
El comportamiento de Query List MO sera diferente para cada usuario autenticado debido al nivel de permisos de cada usuario.
Recomendamos el metodo de envio de los MOs para la API, todo MO enviado será automaticamente enviada para la API ya que de esta forma las respuestas pueden ser tratadas inmediatamente despues de recibidas
Perfil
Permisos
Regular
Cada solicitud realizada en la MO API solo retornara los MOs correspondientes a la subcuenta a la que el usuario pertenece. No es posible para un usuario regular recuperar los MOs de otras subcuentas.
Administrador
El comportamiento estándar para el usuario administrador es recuperar todos los MOs de todas las subcuentas. Si un admin desea recuperar los MOs de apenas una de las subcuentas es necesario especificar la subcuenta en el parámetro subAccount con el id de la subcuenta deseada.

Fomato de respuesta estandar de MO

Ejemplo JSON de respuesta:
1
{
2
"total": 1,
3
"start": "2016-09-04T11:12:41Z",
4
"end": "2016-09-08T11:17:39.113Z",
5
"messages": [
6
{
7
"id": "25950050-7362-11e6-be62-001b7843e7d4",
8
"subAccount": "iFoodMarketing",
9
"campaignAlias": "iFoodPromo",
10
"carrierId": 1,
11
"carrierName": "VIVO",
12
"source": "5516981562820",
13
"shortCode": "28128",
14
"messageText": "Eu quero pizza",
15
"receivedAt": 1473088405588,
16
"receivedDate": "2016-09-05T12:13:25Z",
17
"mt": {
18
"id": "8be584fd-2554-439b-9ba9-aab507278992",
19
"correlationId": "1876",
20
"username": "iFoodCS",
21
"email": "[email protected]"
22
}
23
},
24
{
25
"id": "d3afc42a-1fd9-49ff-8b8b-34299c070ef3",
26
"subAccount": "iFoodMarketing",
27
"campaignAlias": "iFoodPromo",
28
"carrierId": 5,
29
"carrierName": "TIM",
30
"source": "5519987565020",
31
"shortCode": "28128",
32
"messageText": "Meu hamburguer está chegando?",
33
"receivedAt": 1473088405588,
34
"receivedDate": "2016-09-05T12:13:25Z",
35
"mt": {
36
"id": "302db832-3527-4e3c-b57b-6a481644d88b",
37
"correlationId": "1893",
38
"username": "iFoodCS",
39
"email": "[email protected]"
40
}
41
}
42
]
43
}
Copied!
Tanto las solicitudes de listado (list) como la funcion de busqueda (search) retornan un objeto JSON con los campos abajo:
Campo
Detalles
Tipo
total
Numero total de MOs retornados por la solicitud
Integer
start
Limite minimo de la query
String
end
Limite máximo de la query
String
messages
Listado de los objetos
List
Cada mensaje del campo messages posee la siguiente estructura:
Campo
Detalles
Tipo
id
Id del mensaje
String
subAccount
subcuenta responsable por enviar el mensaje que genero la respuesta
String
carrierId
Id de la operadora
Integer
carrierName
Nombre de la operadora
String
source
Numero de telefono que envio el mensaje de respuesta
String
shortCode
O shortcode del mensaje que origino la respuesta y por el cual la respuesta fue enviada.
String
messageText
Texto del mensaje de respuesta.
String
receivedAt
hora de recebido
Long
receivedDate
Fecha y hora de recibimiento en formato UTC
String
campaignAlias
Alias da campaña que origino la respuesta
String
mt
MT original que genero la respuesta
MT
MTs tienen la siguinte estructura
Campo
Detalles
Tipo
id
Id del MT
String
correlationId
CorrelationID enviado en el MT
String
username
Username del usuário responsable por enviar el MT
String
email
Email del responsable por enviar el MT
String

Solicitud listar MO (list)

El listado ira a retornar todos los MOs recibidos desde la ultima llamada de acuerdo con la respuesta estándar descripta encima. Una vez que esta llamada es realizada sera consumida y no retornara las llamadas siguientes.
Como un usuario regular, para recuperar todos los MOs de una subcuenta use:
GET https://api-messaging.wavy.global/v1/sms/receive/list
Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:
GET https://api-messaging.wavy.global/v1/sms/receive/list
Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:
GET https://api-messaging.wavy.global/v1/sms/receive/list?subAccount=referencia_subconta
La solicitud de búsqueda (search request) retornara cada MO recibido en un determinado periodo de tiempo. Usted necesita definir los parámetros START y END para especificar un periodo de tiempo, deberá ser utilizado el formato ISO-8601. START es definido 5 días antes de la fecha actual y END es definido en la fecha actual. No es posible recuperar MOs anteriores a 5 días.
Como um usuario regular, para recuperar todos los MOs de una subcuenta use:
GET https://api-messaging.wavy.global/v1/sms/receive/search
Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:
GET https://api-messaging.wavy.global/v1/sms/receive/search
Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:
GET https://api-messaging.wavy.global/v1/sms/receive/search?subAccount=referencia_subconta
Busqueda com START e END definidos:
GET https://api-messaging.wavy.global/v1/sms/receive/search?start=2016-09-12T00:00:00&end=2016-09-15T00:00:00
Solamente con START especificado (utilizando END estandar, fecha actual)
GET https://api-messaging.wavy.global/v1/sms/receive/search?start=2016-09-12T00:00:00
Solamente con END especificado (utilizando START standar, 5 dias antes de la fecha atual)
GET https://api-messaging.wavy.global/v1/sms/receive/search?end=2016-09-15T00:00:00
Usado valores estandar para START y END especificando subconta
GET https://api-messaging.wavy.global/v1/sms/receive/search?subAccount=iFoodMarketing

Códigos de Estatus de Envió

Existen dos niveles de estatus, que son enviados independientemente.
1 - Primer estatus (sent_status - Estatus de envió = Callback)
Estatus de entrega en la operadora, este es el primer estatus que retornamos, y todas las operadoras poseen.
Código
Mensaje
Significado
2
SENT_SUCCESS
Entregado en la operadora con éxito (Este es un estatus que debe ser considerado para efecto de cobro.)
101
EXPIRED
Expirado antes de ser entregado al aparato.
102
CARRIER_COMMUNICATION_ERROR
Error de comunicación con la operadora.
103
REJECTED_BY_CARRIER
Operadora rechazo el mensaje.
201
NO_CREDIT
El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
202
INVALID_DESTINATION_NUMBER
El numero de destino es invalido (No es un numero de celular valido).
203
BLACKLISTED
El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
204
DESTINATION_BLOCKED_BY_OPTOUT
El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
205
DESTINATION_MESSAGE_LIMIT_REACHED
El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
207
INVALID_MESSAGE_TEXT
El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.
301
INTERNAL_ERROR
Ocurrio un error en la plataforma de Wavy.
2 - Segundo estatus (delivered_status - Delivery Report Callback)
Estatus de entrega en el aparato, este es el segundo estatus que retornamos y solo existe para los casos en que el primer estatus de arriba fue de éxito, o sea, el mensaje fue entregado en la operadora con éxito. En este estatus informamos si el mensaje fue o no entregado en el aparato. Algunas operadoras no poseen este segundo nivel de estatus, para estas operadoras, lo máximo de información que existe es el primer estatus o sea, si la operadora acepto el mensaje o no.
Código
Mensaje
Significado
4
DELIVERED_SUCCESS
Entregado en el aparato con éxito.
104
NOT_DELIVERED
La operadora acepto el mensaje, pero no consiguió entregarlo en el aparato. Posibles causas: Aparato apagado o fuera del área de servicio por tiempo determinado (normalmente 24 horas, pero para algunas operadoras, este tiempo de tentativa es de 8 horas). Número válido, pero inactivo (algunas operadoras retornan este tipo de error solamente en este segundo nivel de estatus).

API SMPP

Todos los servicios provistos por el Wavy deben obligatoriamente ser encriptados, y el protocolo SMPP no posee encriptacion nativa. En este caso disponibilizamos dos alternativas para integración

Opción 1 - SMPP over TLS + IP whitelist (Opción recomendada)

Esta es la opción que recomendamos. En el caso que su sistema no tenga esta funcionalidad, clique aqui para obtener ayuda en la configuracion de un proxy TLS.
Mas allá de la encriptacion que será realizada por TLS, el acceso será autorizado solamente para la IP publica de su servidor. (Aceptamos múltiples IPs e rangos) Esta información debe ser enviada para el e-mail [email protected]
En el caso que sea necesaria la liberación de salida de trafico en su firewall, recomendamos que sea liberado cualquier IP de destino en la puerta 2444. Si esto no es posible, se deberán incluir las siguientes reglas de liberación:
200.219.220.8:2444 200.219.220.193:2444 200.189.169.8:2444 189.36.59.86:2444 45.236.179.18:2444 45.236.179.19:2444

Opcion 2 - SMPP over VPN

La encriptacion y la liberación de acceso sera realizada vía VPN.
En el caso que elija esta opción, configure las VPNs utilizando los siguientes peers y hosts con las propuestas de fase 1 y 2 que desea. Llene y envié el formulario de VPN de su empresa para [email protected]
peer 200.155.0.250 hosts 200.219.220.8 and 200.219.220.193 port 2443
peer 200.143.57.150 hosts 200.189.169.8 and 189.36.59.86 port 2443
peer 45.236.178.12 hosts 45.236.179.18 and 45.236.179.19 port 2443
Obs: Por razones de alta disponibilidad y balanceamiento de carga, es obligatorio el establecimiento de las 2 VPNs definidas arriba.

Detalles de conexión

Información
Detalles
Hostname / IP Address
smpp-messaging.wavy.global Al configurar su sistema SMPP, es obligatorio utilizar el dominio como destino, y no las IPs. Este dominio posee 4 proxys de entrada con round robin DNS y health check, y múltiples servidores backend. Basado en el volumen de mensajes que su empresa traficara, vamos a aumentar el numero de binds (conexiones) permitidas simultáneamente.
Puerta
2444 (SMPP over TLS) o 2443 (VPN)
Version SMPP
3.4
Numero de binds
Mínimo 4. Establecer por lo menos 4 binds es mandatario para obtener alta-disponibilidad y balanceamiento de carga.
Codificación de los caracteres
GSM7 - Default (data_coding = 0) (GSM3.38 extended table is not supported by carriers.) LATIN1 (data_coding = 1) UCS2 (data_coding=8).
Flash SMS
Soporta data_coding=0x10 para GSM7 y data_coding 0x18 para UCS2 Cuando recibamos un flashSMS de nuestro cliente, el mismo sera enviado a la operadora como flashSMS, en el caso que la operadora no acepte flashSMS, este será entregado como un SMS regular.
Enquire-link
Minimo: 30 segundos / Máximo: 59 segundos.
Concatenación
UDH de 8 bits y 16 bits son compatibles / UDH Headers
Default addr_ton
1
Default addr_npi
1
window size
10
System IDs
SystemIDs can NOT contain the underscore _ character
Passwords
De acuerdo con la especificación del protocolo versión 3.4, no puede contener mas que 8 caracteres.
2way
Soportado
SMPP bind type
Transceiver(Recomendado). Binds transmit/receiver separados también son aceptados.
SMPP system_type
MovileSMSC
SMPP source addr (senderID)
Cuando su servicio necesite respuestas de usuarios (MO), el source addres debe ser igual al system_id, o sea, el nombre de usuario. Cuando el servicio no necesita de MOs usted puede utilizar cualquier cosa en este campo.
Max flujo de MO
80 por bind
Max flujo de MT
80 por bind
Server Timezone
UTC
Formato de ID
UUID
Default validity_period
24 hours

Estatus de envio (Callback e DLR)

1 - Primer estatus (sent_status - Estatus de envio = Callback)
Estatus de entrega en la operadora, este es el primeir estatus que retornamos, y todas las operadoras poseen.
stat
err
TLV (0x1403)
TLV (0x1404)
Significado
ACCEPTD
000
2
SENT_SUCCESS
Entregado en la operadora con éxito. (Este es un estatus que debe ser considerado para efecto de cobro.)
EXPIRED
101
101
EXPIRED
Expirado antes de ser entregado al aparato.
REJECTD
102
102
CARRIER_COMMUNICATION_ERROR
Error de comunicación con la operadora.
REJECTD
103
103
REJECTED_BY_CARRIER
Operadora rechazo el mensaje.
REJECTD
201
201
NO_CREDIT
El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
REJECTD
202
202
INVALID_DESTINATION_NUMBER
El numero de destino es invalido (No es un numero de celular valido).
REJECTD
203
203
BLACKLISTED
El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
REJECTD
204
204
DESTINATION_BLOCKED_BY_OPTOUT
El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
REJECTD
205
205
DESTINATION_MESSAGE_LIMIT_REACHED
El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
REJECTD
207
207
INVALID_MESSAGE_TEXT
El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.