API de SMS

Documentación técnica: SMS API.

Términos importantes

Termo	Significado	Descrição
MT	Mobile Terminated	Mensajes enviados por su empresa al usuario final.
MO	Mobile Originated	Es el término utilizado para los mensajes que tienen como destino su empresa. Es decir, mensajes originados por el usuario (Dispositivo). Se utiliza, por ejemplo, en flujos de preguntas y respuestas vía SMS, cuando se requiere confirmación del usuario.
Response	Resposta síncrona da Sinch	Es una respuesta inmediata a una solicitud realizada en nuestra API, donde te informamos si el mensaje fue aceptado o no por nuestra plataforma.
Callback	Sent status ou status de envio	Es el primer estado enviado que te devolvemos, en el que te informamos si fue posible o no entregar el mensaje. para el operador.
LA	Short Code	Número corto de 5 o 6 dígitos que se utiliza para enviar y recibir mensajes SMS. Son designados por operadores para integradores certificados (Sinch), y cuentan con normas antifraude y antispam.
DR | DLR	Delivery Receipt	Es el segundo estado de envío que le devolvemos, donde le informamos si fue posible o no entregar el dispositivo. Los operadores envían esta información a Sinch y nosotros se la entregamos al cliente. El tiempo de entrega es variable, por ejemplo, si el dispositivo se apagó en el momento del envío y el usuario lo encendió 2 horas después, este estado de DLR se entregará al cliente con 2 horas de retraso. Obs1: Esta confirmación de entrega en el dispositivo solo existirá para los casos en que el mensaje haya sido entregado con éxito al operador. Es decir, el primer estado (Callback) fue exitoso. Obs2: Es muy importante señalar que lamentablemente los operadores OI y Sercomtel no cuentan con esta funcionalidad, es decir, no devuelven la información de entrega al dispositivo. Los envíos realizados a números de estos operadores solo tendrán los datos de entrega del operador (callback).

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	Detalhes	Data Type
UserName	Su nombre de usuario o correo electrónico	String
Authentication Token	Tu token de autenticación. Consulta aquí cómo generar un usuario del sistema.	String
TemplateID	Identificador de plantilla de SMS. El texto del mensaje se recuperará y debe crearse primero a través del Portal de mensajería.	Long
TemplateName	Nombre de la plantilla de SMS. Puede que no sea único, lo que genera un error si se encuentra más de un modelo para el nivel de acceso del usuario. El texto del mensaje se recuperará y debe crearse primero a través del Portal de mensajería	String

Detalles de conexión

Campo	Detalles
Hostname	api-messaging.wavy.global
API's	Envios individuais /v1/send-sms Envios em lote /v1/send-bulk-sms
Porta	443 (https)
Protocolo	HTTPS (encriptação TLS)
Autenticação	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 Sinch):

[
  {
  "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 Sinch 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 Sinch. 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

Para cada usuario hay un token de autenticación único. Para evitar problemas con la eliminación de usuarios, cree un usuario del sistema para sus integraciones.

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

IMPORTANTE! Para cada usuario existe un token de autenticacion único

HTTP Status Code Response

Códigos de estado HTTP más comunes:

Grupo	Descrição
2xx	Éxito
4xx	error del cliente
5xx	Error del Servidor

Código	Descrição
200	Éxito
400	Solicitud incorrecta
401	Sin autorización
403	Prohibido
404	No encontrado
429	Muchas solicitudes cumplidas
500	Error Interno del Servidor
503	Servicio no disponible
504	tiempo de espera de la puerta de enlace

O limite de máximo é de 700 requisições por segundo por IP.

Estado del envío (devolución de llamada y DLR)

Hay dos formas de obtener el estado de envío de los mensajes, son:

• Webhook: Recibe estados en el webservice de tu empresa (recomendado).

Tan pronto como entreguemos el mensaje al operador, o tan pronto como el operador nos informe si ha entregado el mensaje al dispositivo, la información se le transmitirá instantáneamente.

• API de consulta: realice solicitudes de consulta en nuestra API de estado de sms.

Los estados están disponibles por 3 días, y pueden ser consultados por el UUID que Sinch devolvió al recibir el mensaje de su empresa, o por el ID que recibió su empresa al entregar el mensaje a Sinch.

La desventaja de esta opción Tenga en cuenta que en los ejemplos anteriores, algunos campos de "destino" no tienen un "messageText" directamente asignado a ellos, en estos casos, el texto del mensaje será el "messageText" dentro de "defaultValues". Esta función es útil cuando es necesario enviar el mismo mensaje a varios números de consulta diferentes en lugar de un webhook, ya que estará realizando solicitudes de consulta de una ID que quizás aún no se haya entregado al operador o al dispositivo, en este caso. , se realizarán una serie de solicitudes innecesarias. Por ejemplo, si un usuario tenía su dispositivo apagado cuando le envió un mensaje y lo llamó 2 horas después, consultará esta identificación innumerables veces durante dos horas. Y en el caso de usar un webhook, esta información se le enviaría tan pronto como se entregue al dispositivo, sin solicitudes vacías.

Las consultas de estado tienen un límite de velocidad de 1 solicitud por segundo por dirección IP. Las solicitudes que superan este límite se responden con el código de estado HTTP 429.

Estado a través de webhook (entregado a su servicio web)

Para configurar el envío de Callbacks y DRs (duda sobre los términos, consulte la pestaña de Términos Importantes) primero es necesario iniciar sesión en Sinch Messaging en la configuración de la API, en el formulario de configuración puede proporcionar las URL donde estarán los estados de envío enviados (devoluciones de llamada) y estados de confirmación del dispositivo (DR)

Después de agregar su webhook al portal anterior, la configuración se replicará en nuestra plataforma en 10 minutos y llamaremos a su URL cuando ocurran las siguientes acciones:

Ação	Status de retorno enviado
Después de que se entregue o no un mensaje, en el transportista	API de estado de envío (devolución de llamada)
Cuándo se entrega o no un mensaje, en el dispositivo del cliente	API de informes de entrega (DR)

Ejemplo de estado de envío JSON (devolución de llamada - entrega del transportista)

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 de respuesta de devolución de llamada (estado enviado)

Campo	Descrição
id	UUID generado del mensaje
correlationId	Su ID para este mensaje
carrierId	identificador del transportista
carrierName	Nombre de la operadora
destination	Número de teléfono del mensaje enviado
sentStatusCode	Código de estado generado por Sinch para el mensaje que indica el estado del envío. Consulte los códigos de estado para obtener más información.
sentStatus	descripción del estado del envío. Consulte los códigos de estado para obtener más información.
sentAt	Hora de envío, el formato utilizado es Unix_time
sentDate	Fecha en que se envió el mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ
campaignId	Identificador de campaña si lo hay
extraInfo	Cualquier información extra añadida por el cliente al enviar el mensaje

Informes de entrega de respuesta (DR) de campos JSON

Campo	Descrição
id	UUID generado del mensaje
correlationId	Su ID para este mensaje
carrierId	identificador del transportista
carrierName	Nombre de la operadora
destination	Número de teléfono del mensaje enviado
sentStatusCode	Código de estado generado por Sinch para el mensaje que indica el estado del envío. Consulte los códigos de estado para obtener más información.
sentStatus	descripción del estado del envío. Consulte los códigos de estado para obtener más información.
sentAt	Hora de envío, el formato utilizado es Unix_time
sentDate	Fecha en que se envió el mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ
campaignId	Identificador de campaña si lo hay
extraInfo	Cualquier información extra añadida por el cliente al enviar el mensaje

Consulta de estado a través de solicitud HTTP

Para comprobar el estado de los últimos mensajes enviados, es necesario realizar una solicitud POST a la siguiente URL, enviando el(los) UUID(s) y/o el(los) correlación(es) obtenidos en la respuesta de envío:

POST 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 solo los estados aún no consultados:

GET https://api-messaging.wavy.global/v1/sms/status/list

Tenga en cuenta que este punto final solo devuelve estados que este punto final aún no ha devuelto.

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

Campos JSON de respuesta:

Campo	Detalhes	Tipo
id	UUID generado en la solicitud del mensaje	String
correlationId	Mismo ID de correlación que la solicitud	String
carrierId	ID del transportista, para más información ver código de error	Long
carrierName	Nombre de la compañía	String
destination	Número de teléfono del mensaje enviado	String
sentStatusCode	Código de estado enviado.	Long
sentStatus	Enviar estado.	String
sentStatusAt	Cuándo se envió el mensaje. es una fecha de epoca	Long
sentStatusDate	Cuándo se envió el mensaje. Formato aaaa-MM-dd'T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601)	String
deliveredStatusCode	Código de estado entregado.	Long
deliveredStatus	Estado entregado.	String
deliveredAt	Cuándo se entregó el mensaje. es una fecha de epoca	Long
deliveredDate	Cuándo se entregó el mensaje. Formato aaaa-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 adicional establecida por el usuario cuando se envió el mensaje	String

Ejemplo de informe de entrega JSON (DR o DLR: entrega al dispositivo 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 le permite automatizar el proceso de recuperación de las respuestas enviadas por los clientes en respuesta a los mensajes que les envió. Todas las solicitudes utilizan el método GET y las respuestas se envían en formato JSON. ¡IMPORTANTE! La recepción de MO está habilitada por defecto solo para las LA 27182 y 28149, si es necesario recibir mensajes a través de otras LA, será necesario contactar a soporte para evaluar.

También es posible configurar los MO para que se reenvíen a medida que llegan a una API de cliente, esta es la forma más eficiente ya que no es necesario realizar ninguna llamada, solo manejar los envíos a medida que llegan. Para que esta configuración se lleve a cabo es necesario abrir un ticket con nuestro equipo de soporte técnico a través del correo electrónico de soporte, pasando la url que recibirá los MOs. Pudimos enviar los MO tanto a través del método GET (cadena de consulta) como a través del método POST (JSON).

Ejemplo de JSON enviado a su API (método POST)

{
     "id": "25950050-7362-11e6-be62-001b7843e7d4",
     "subAccount": "Marketing",
     "campaignAlias": "Promo",
     "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": "[e-mail]"
     }
   }

Cada solicitud realizada devolverá los MO de los últimos 3 días, hasta un límite de 1.000 MO. Para fechas anteriores o cantidades mayores, comuníquese con nuestro equipo de soporte a través de nuestro Centro de Servicio.

El comportamiento de la consulta List MO será diferente para cada usuario autenticado debido al nivel de permiso de cada usuario.

Recomendamos el método de envío de MO a la API, cada MO enviado se enviará automáticamente a la API, ya que de esta manera las respuestas se pueden manejar inmediatamente después de recibirlas.

Perfil	Permissão
Regular	cada solicitud realizada en la API de MO solo devolverá los MO correspondientes a la subcuenta a la que pertenece el usuario. No es posible que un usuario normal recupere MO de otras subcuentas.
Administrador	el comportamiento predeterminado para el usuario administrador es recuperar todos los MO para todas las subcuentas. si un administrador quiere recuperar los MO de solo una de las subcuentas, es necesario especificar la subcuenta en el parámetro subAccount con la identificación de la subcuenta deseada.

Formato de respuesta MO

Ejemplo de llamada de respuesta JSON Sinch API:

{
  "total": 1,
  "start": "2016-09-04T11:12:41Z",
  "end": "2016-09-08T11:17:39.113Z",
  "messages": [
    {
      "id": "25950050-7362-11e6-be62-001b7843e7d4",
      "subAccount": "Marketing",
      "campaignAlias": "Promo",
      "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": "[e-mail]"
      }
    },
    {
      "id": "d3afc42a-1fd9-49ff-8b8b-34299c070ef3",
      "subAccount": "Marketing",
      "campaignAlias": "Promo",
      "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": "CS",
        "email": "[e-mail]"
      }
    }
  ]
}

Tanto las solicitudes de listado (lista) como la función de búsqueda (buscar) devuelven un objeto JSON con los campos a continuación:

Cada mensaje en el campo de mensajes tiene la siguiente estructura:

Campo	Detalles	Tipo
id	identificación del mensaje	String
subAccount	subcuenta responsable de enviar el mensaje que generó la respuesta	String
carrierId	identificación del operador	Integer
carrierName	Nombre de la compañía	String
source	Número de teléfono que envió el mensaje de respuesta	String
shortCode	El código abreviado del mensaje que originó la respuesta y a través del cual se envió la respuesta	String
messageText	Texto del mensaje de respuesta	String
receivedAt	tiempo de recibo	Long
receivedDate	Fecha y hora del recibo en formato UTC	String
campaignAlias	Alias ​​de la campaña que originó la respuesta	String
mt	MT original que gerou a resposta	MT

Los MT tienen la siguiente estructura:

Campo	Detalhes	Tipo
id	Identificación de MT	String
correlationId	CorrelationID enviado en MT	String
username	Nombre de usuario del usuario responsable de enviar el MT	String
email	Correo electrónico del responsable del envío del 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	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 Sinch

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 Sinch 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 Soporte.

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 nuestro soporte.

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.
REJECTD	301	301	INTERNAL_ERROR	Ocurrio un error en la plataforma de Sinch.
UNKNOWN	301	301	INTERNAL_ERROR	Ocurrio un error en la plataforma de Sinch.

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.

stat	err	TLV (0x1403)	TLV (0x1404)	TLV (0x1405)	TLV (0x1406)	Significado
DELIVRD	000	2	SENT_SUCCESS	4	DELIVERED_SUCCESS	Entregado en el aparato con éxito.
UNDELIV	104	2	SENT_SUCCESS	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).

IMPORTANTE! el estado de entrega en el aparato, operadora y MOs son encolados si ocurre algún problema de conectividad, pero el plazo es de 8hs, después de este período no será posible obtener los status por SMPP

Proxy TLS - Linux

El proxy es necesario en el caso que la conexión no sea vía VPN. Como fue explicado anteriormente, el protocolo SMPP no posee encriptacion TLS nativa, en este caso indicamos el siguiente proxy:

HAProxy

Configuración haproxy

global
    #    local2.*                       /var/log/haproxy.log
    log         127.0.0.1 local2

    chroot      /var/lib/haproxy
    pidfile     /var/run/haproxy.pid
    ssl-server-verify       none
    maxconn     4000
    user        haproxy
    group       haproxy
    daemon
    # turn on stats unix socket
    stats socket /var/lib/haproxy/stats

resolvers dns
    nameserver google 8.8.8.8:53
    hold valid 1s

defaults
    log                     global
    option                  redispatch
    retries                 3
    timeout http-request    10s
    timeout queue           1m
    timeout connect         10s
    timeout client          1m
    timeout server          1m
    timeout http-keep-alive 10s
    timeout check           10s
    maxconn                 3000

frontend movile
  bind *:2444
  mode tcp
  option tcplog
  use_backend movile

backend movile
    mode tcp
    server smpp-messaging.wavy.global smpp-messaging.wavy.global:2444 ssl resolvers dns check inter 15000

• Instalación haproxy servidores (red-hat / centos):

$sudo yum install -y openssl-devel haproxy

• Instalación haproxy servidores (debian / ubuntu)

$sudo apt-get install -y openssl-devel haproxy

• Despues de la Instalación, substituya todo el contenido del archivo /etc/haproxy/haproxy.cfg por el contenido al lado ->

IMPORTANTE: Configure su sistema (cliente SMPP) para utilizar como direccion de destino 127.0.0.1:2444

Proxy TLS - Windows

configuracion nginx

worker_processes  2;

events {
    worker_connections  1024;
}

stream {
  resolver 8.8.8.8 valid=1s;
  map $remote_addr $backend {
    default smpp-messaging.wavy.global;
  }
  server {
    listen 2444;
    proxy_pass $backend:2444;
    proxy_ssl  on;
  }
}

Es posible utilizar nginx como proxy TLS en servidores windows para realizar la encriptacion de los dados

Descargue la versión abajo (importante utilizar esta versión porque las versiones antiguas resuelven el nombre apenas en el primer request)

http://nginx.org/download/nginx-1.12.1.zip

Extraiga el archivo .zip en la carpeta deseada y sustituya el contenido del archivo conf/nginx.conf con los datos al lado.

API SFTP

Detalles de conexión

Hostname	ftp-messaging.wavy.global
Puerta	2222
Protocolo	SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor)
Autenticación	username + senha (provisto por soporte)
Portal	messaging.wavy.global

Es necesaria la liberación de sus IPs en el firewalls de Sinch Si fuera necesario liberación del firewall para salida sentido puerta 2222, usted debe liberar los DNS, o las IPs 200.219.220.54, 200.189.169.53 e 45.236.179.22

Envio de mensajes via SFTP

Para realizar el disparo de mensajes vía SFTP es necesario generar un archivo en formato TXT, el formato debe seguir el siguiente ejemplo:

numero;texto;correlationId(opcional); 5511900000000;mensaje 1;; 5519900000000;mensaje 2;; 5521900000000;mensaje 3;; EOF

El nombre del archivo a ser enviado debe seguir el siguiente formato:

<ID_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA> ou <NOME_DE_REFERÊNCIA_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA>

Las sub cuentas (projectos) pueden ser creadas por el propio cliente en el portal. En el caso que no sea seguida la nomenclatura arriba, el envío será realizado por la sub cuenta default del cliente.

Ejemplo:

3486.20170101.01.txt ou PROJETO1.20170101.01.txt

Es importante seguir la nomenclatura definida para que los mensajes sean debitados de la sub cuenta correcta.

Después deberá ser realizado el envió del archivo para el servidor sftp en el directorio upload. El archivo será movido para el directorio success después de procesado, en el caso que aparezca un error el archivo será movido para el directorio error.

API Validación de números

Esta API permite realizar consultas en lote de números retornando la operadora a la que esos números pertenecen y consecuentemente los números inválidos (si un número no pertenece a ninguna operadora por lo tanto es inválido). Ella utiliza el protocolo HTTP con TLS y el metodo POST con parámetros en JSON. La consulta permite saber si determinado número pertenece a la operadora pero no es posible verificar si este número se encuentra activo.

IMPORTANTE: Las consultas de carrier lookup poseen una tarifacion diferenciada de los envíos de SMS, antes de realizar la consulta verifique con el responsable del equipo comercial sobre las tarifaciones

Autenticacion

Para efectuar envíos y consultas en nuestra API es necesaria la autenticacion por medio de usuario o e-mail, en conjunto con un token.

Campo	Detalles	Data Type
UserName	Su usuario o email	String
AuthenticationToken	Su token de autenticacion. Verifique aqui y lea las descripciones de usuarios abajo.	String

Detalles de conexión

Hostname	api-messaging.wavy.global
APIs	Consulta en lote /v1/carrier/lookup
Puerta	443 (https)
Protocolo	HTTPS (encriptacion TLS)
Autenticacion	username + token
Portal	messaging.wavy.global

Requisicion HTTP Method POST

curl --request POST \
  --url https://api-messaging.wavy.global/v1/carrier/lookup \
  --header 'authenticationtoken: <authenticationtoken>' \
  --header 'username: <username>' \
  --header 'Content-Type: application/json' \
  --data '{
    "destinations": ["[phone]", "5519997712322", "2312312"]
}'

POST https://api-messaging.wavy.global/v1/carrier/lookup Content-Type: application/json

Para realizar la consulta basta adicionar en el body de la requisicion un json con el array de números. Es posible hacer la consulta utilizando los formatos [phone] y 5519999999999

Respuesta a la consulta

Respuesta a la llamada en formato JSON

{
    "id": "aadb5130-7dd7-11e7-baac-a6aabe61edb5",
    "destinations": [
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "2312312",
            "active": false,
            "carrier": {
                "name": "UNKNOWN"
            }
        }
    ]
}

El ultimo numero de ejemplo se trata de un numero invalido para demostrar como la consulta retorna el JSON en este caso.

La respuesta de la consulta en lote contendrá un archivo JSON con las informaciones individuales sobre cada número consultado:

Campo	Detalles	Tipo
id	UUID generado para este lote	String
destinations	Este campo es un array con las respuestas de las consultas individuales del lote, contiene el id y el correlationId de cada número consultado	IndividualResponse[]
destination	Número de telefono consultado	Long
active	status del numero en la operadora (actualmente verifica apenas si el número pertenece a la operadora, no activo / en uso)	Boolean
carrier	Operadora y país a la cual pertenece el número consultado	array[]
name	Nombre de la operadora	String
countryCode	Codigo de País	String

Acentos y caracteres especiales

Mensajes que poseen solamente caracteres que están en la siguiente tabla, son cobrados cada 160 caracteres. En el caso que el mensaje tenga uno o mas caracteres que no están en la tabla el cobro sera realizado cada 70 caracteres, conforme la especificación del protocolo en la red de las operadoras.

Space	(	0	8	@	H	P	X	`	h	p	x
!	)	1	9	A	I	Q	Y	a	i	q	y
“	*	2	:	B	J	R	Z	b	j	r	z
#	+	3	;	C	K	S	{	c	k	s	~
$	,	4	<	D	L	T	\	d	l	t
%	-	5	=	E	M	U	}	e	m	u
&	.	6	>	F	N	V	^	f	n	v
‘	/	7	?	G	O	W	_	g	o	w

Comentarios:

• La habilitación del uso de acentos y caracteres especiales debe solicitarse al soporte.

• En caso de que el operador de destino no acepte acentos y caracteres (Oi y Sercomtel), nuestra plataforma los reemplaza automáticamente para nuestros clientes, por ejemplo: á por a, é por e, etc.

• Cuando agregamos un contenido en la codificación GSM-7 (160 caracteres), se cuentan como dos caracteres cada uno: \ ^ ~ [ ] { } | €.

• Cuando se utiliza la codificación UCS-2/Unicode (70 caracteres), el conteo se realiza normalmente.

Textos grandes (concatenación)

A pesar que el protocolo utilizado en la red de las operadoras tenga limite de 70 o 160 caracteres, para mensajes con o sin caracteres especiales respectivamente, es posible enviar mensajes grandes con la utilización de concatenación, donde los mensajes son reagrupados por los aparatos al recibirlos.

Clientes integrados vía HTTPS, SFTP, o MQ, no existe ningún indicador adicional para activar la concatenación, basta solo enviar el texto del mensaje grande entero de una sola vez.

Clientes integrados vía SMPP, deben utilizar la funcionalidad de concatenación con indicadores en el header (UDH), LINK

Es importante notar que, a pesar de aparecer en el aparato como un único mensaje grande, los mensajes continúan traficando en la red de operadora individualmente, en este caso, continúan siendo cobrados individualmente cada 70 o 160 (dependiendo de los caracteres utilizados). Recordando que al utilizar concatenación parte de los caracteres (70 o 160) son utilizados por el encabezado.

Observación: En los casos de operadoras que no soportan la funcionalidad de concatenación, Sinch enviá los mensajes separadamente, sin concatenar incluyendo automáticamente para nuestros clientes, indicadores de orden.