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
curl -X POST \
  https://api-messaging.wavy.global/v1/send-sms \
  -H 'authenticationtoken: <authenticationtoken>' \
  -H 'username: <username>' \
  -H 'content-type: application/json' \
  -d '{"destination": "5511900000000" , "messageText": "linha\nquebrada"}'
​
Al hacer el envió usted recibirá un JSON informando el id que fue generado para este mensaje (Response o Respuesta sincrona de Wavy):
[
  {
  "id":"9cb87d36-79af-11e5-89f3-1b0591cdf807",
  "correlationId":"myId"
  }
]
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
curl --request POST \
  --url https://api-messaging.wavy.global/v1/send-bulk-sms \
  --header 'authenticationtoken: <Token de autenticação>' \
  --header 'username:<Usuário Movile Messaging>' \
  --header 'content-type: application/json' \
  --data "{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}"
​
Al hacer el envió, retornara un objeto JSON con un UUID del lote e de los mensajes individuales :
​
  {
  "id": "ce528d70-013b-11e7-98f2-e27c463c8809",
  "messages": [
    {
      "id": "ce528d71-013b-11e7-98f2-e27c463c8809"
    },
    {
      "id": "ce528d72-013b-11e7-98f2-e27c463c8809"
    }
  ]
}
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:
{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    },
    {
      "destination":"5519900003333"
    }
  ],
  "defaultValues":{
    "messageText":"Default message"
  }
}
Exemplo 2:
{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    }
  ],
  "timeZone":"America/Sao_Paulo",
  "scheduledDate": "2017-01-28T02:30:43",
  "timeWindow": [12, 15, 20],
  "defaultValues":{
    "messageText":"Default message"
  }
}
Exemplo 3:
`
{
  "messages":[
    {
      "destination":"5519900001111",
    },
    {
      "destination":"5519900002222"
    }
  ],
  "defaultValues":{
    "messageText":"Default message",
    "flashSMS":"true"
  }
}
Ejemplo 4, com flowId y params:
{
  "messages":[
    {
      "destination":"5519900001111",
      "params": {
        "param1": "other_value1",
        "param2": "other_value2"
      }
    },
    {
      "destination":"5519900002222"
    }
  ],
  "defaultValues":{
    "params": {
      "param1": "value1",
      "param2": "value2"
    }
  },
  "flowId": "14f8142d-e731-4971-8220-5a76a12c413f"
}
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)
POST https://example.com/callback/
Content-Type: application/json
​
{
  "id":"f9c100ff-aed0-4456-898c-e57d754c439c",
  "correlationId":"client-id",
  "carrierId":1,
  "carrierName":"VIVO",
  "destination":"5511900009999",
  "sentStatusCode":2,
  "sentStatus":"SENT_SUCCESS",
  "sentAt":1266660300000,
  "sentDate":"2010-02-20T10:05:00Z",
  "campaignId":"64",
  "extraInfo":"",
}
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)
{
  "id":"8f5af680-973e-11e4-ad43-4ee58e9a13a6",
  "correlationId":"myId",
  "carrierId":5,
  "carrierName":"TIM",
  "destination":"5519900001111",
  "sentStatusCode":2,
  "sentStatus":"SENT_SUCCESS",
  "sentStatusAt":1420732929252,
  "sentStatusDate":"2015-01-08T16:02:09Z",
  "deliveredStatusCode":4,
  "deliveredStatus":"DELIVERED_SUCCESS",
  "deliveredAt":1420732954000,
  "deliveredDate":"2015-01-08T16:02:34Z",
  "campaignId":1234
}
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)
{
     "id": "25950050-7362-11e6-be62-001b7843e7d4",
     "subAccount": "iFoodMarketing",
     "campaignAlias": "iFoodPromo",
     "carrierId": 1,
     "carrierName": "VIVO",
     "source": "5516981562820",
     "shortCode": "28128",
     "messageText": "Eu quero pizza",
     "receivedAt": 1473088405588,
     "receivedDate": "2016-09-05T12:13:25Z",
     "mt": {
       "id": "8be584fd-2554-439b-9ba9-aab507278992",
       "correlationId": "1876",
       "username": "iFoodCS",
       "email": "[email protected]"
     }
   }
​
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:
{
  "total": 1,
  "start": "2016-09-04T11:12:41Z",
  "end": "2016-09-08T11:17:39.113Z",
  "messages": [
    {
      "id": "25950050-7362-11e6-be62-001b7843e7d4",
      "subAccount": "iFoodMarketing",
      "campaignAlias": "iFoodPromo",
      "carrierId": 1,
      "carrierName": "VIVO",
      "source": "5516981562820",
      "shortCode": "28128",
      "messageText": "Eu quero pizza",
      "receivedAt": 1473088405588,
      "receivedDate": "2016-09-05T12:13:25Z",
      "mt": {
        "id": "8be584fd-2554-439b-9ba9-aab507278992",
        "correlationId": "1876",
        "username": "iFoodCS",
        "email": "[email protected]"
      }
    },
    {
      "id": "d3afc42a-1fd9-49ff-8b8b-34299c070ef3",
      "subAccount": "iFoodMarketing",
      "campaignAlias": "iFoodPromo",
      "carrierId": 5,
      "carrierName": "TIM",
      "source": "5519987565020",
      "shortCode": "28128",
      "messageText": "Meu hamburguer está chegando?",
      "receivedAt": 1473088405588,
      "receivedDate": "2016-09-05T12:13:25Z",
      "mt": {
        "id": "302db832-3527-4e3c-b57b-6a481644d88b",
        "correlationId": "1893",
        "username": "iFoodCS",
        "email": "[email protected]"
      }
    }
  ]
}
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
Solicitud buscar MO (search)
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


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.

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.


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

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

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)

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

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.

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