Sinch Status Documentación Tecnica Ir a Messaging

API de SMS

Documentación técnica: SMS API.

Términos importantes

TermoSignificadoDescriçã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.

CampoDetalhesData 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

CampoDetalles

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

CampoDetallesTipo

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:

GrupoDescrição

2xx

Éxito

4xx

error del cliente

5xx

Error del Servidor

CódigoDescriçã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çãoStatus 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)

CampoDescriçã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

CampoDescriçã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:

CampoDetallesTipo

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:

CampoDetalhesTipo

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": "customer.support@sinch.com"
     }
   }

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.

PerfilPermissã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": "customer.support@sinch.com"
      }
    },
    {
      "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": "customer.support@sinch.com"
      }
    }
  ]
}

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:

CampoDetallesTipo

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:

CampoDetalhesTipo

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ódigoMensajeSignificado

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ódigoMensajeSignificado

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ónDetalles

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.

CampoDetallesData 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": ["+55(19)997712322", "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 +55(19)999999999 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:

CampoDetallesTipo

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.

PreviousGlosario - IntegracionesNextEnvío de SMS a través de SFTP

Last updated