GETTING STARTED - MENU
Créditos e Limites
Personalização
Componentes Status Page
Inbox

SMS API

Documentação técnica: API de SMS.

Termos importantes

Termos Importantes

MT

Mobile Terminated

É o termo utilizado para mensagens que possuem o usuário (aparelho) como destino. Ou seja, mensagens que foram originadas por sua empresa, com destino ao usuário (aparelho)

MO

Mobile Originated

É o termo utilizado para mensagens que possuem sua empresa como destino. Ou seja, mensagens que foram originadas pelo usuário (aparelho). É utilizado por exemplo, em fluxos de pergunta e respostas via SMS, quando é necessário uma confirmação por parte do usuário.

Response

Resposta sincrona da Wavy

É a resposta imediata de uma requisição feita em nossa API, onde informamos se a mensagem foi aceita ou não por nossa plataforma.

Callback

Sent status ou status de envio

É o primeiro status de envio que retornamos, onde informamos se foi possível, ou não, fazer a entrega da mensagem para a operadora.

LA

Short Code

Número curto de 5 ou 6 dígitos, utilizado para envio e recebimento de mensagens SMS. São designados pelas operadoras para integradores homologados (Wavy), e possuem regras anti-fraude e anti-spam

DR ou DLR

Delivery Receipt

É o segundo status de envio que retornamos, onde informamos se foi possível, ou não, fazer a entrega para o aparelho. As operadoras enviam para a Wavy esta informação, e nós repassamos para o cliente. O tempo de entrega é variável, por exemplo, se o aparelho estava desligado no momento do envio, e o usuário ligou 2 horas depois, este status DLR será entregue para o cliente, com duas horas de atraso.

Esta confirmação de entrega no aparelho existirá somente para os casos em que a mensagem foi entregue com sucesso na operadora, ou seja, o primeiro status (callback) foi de sucesso.

É muito importante ressaltar, que, infelizmente, as operadoras OI e Sercomtel não possuem esta funcionalidade, ou seja, não nos retornam a informação de entrega no aparelho. Os envios feitos para números destas operadoras, terão somente a informação de entrega na operadora (callback)

Fluxo de Mensagem

Fluxo simplificado: MT, Callback, DLR, MO

API HTTPS

Esta API permite que você automatize as requisições de envios de mensagens, únicas ou em lote, e a recuperação dos status de envio através de consultas. Ela utiliza o protocolo HTTP com TLS e aceita os métodos GET, com a passagem de parâmetros na query string, ou POST, com parâmetros em JSON.

Autenticação

Para efetuar envios e consultas em nossa API é necessária a autenticação por meio de usuário ou e-mail, em conjunto com um token.

Campo

Detalhes

Data Type

UserName

Seu usuário ou email

String

AuthenticationToken

Seu token de autenticação. Verifique aqui e leia as descrições de usuários abaixo.

String

Tipo

Detalhes

Administrador

Usuário administrador de sua empresa, é utilizado para criar/editar/inativar subcontas e outros usuários, e pode visualizar relatórios de toda a empresa. Este usuário não faz envios de mensagens, nem pelo portal, nem via integração API.

Usuário

Usuário utilizado para envio de mensagens via API e portal, pode visualizar relatórios específicos de sua subconta. Um usuário é sempre relacionado a uma única subconta. Uma subconta pode conter múltiplos usuários. Cada subconta é um centro de custo em nossa plataforma, as mensagens são descriminadas em relatórios e financeiramente, por subconta, e não por usuário.

templateID

Identificador de modelo de SMS. O texto da mensagem será recuperado e deve ser criado primeiro por meio do Portal do Messaging.

Long

templateName

Nome do modelo de SMS. Pode não ser exclusivo, resultando em erro se mais de um modelo for encontrado para o nível de acesso do usuário. O texto da mensagem será recuperado e deve ser criado primeiro por meio do Portal do Messaging

String

Detalhes de conexão

Hostname

api-messaging.wavy.global

APIs

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

Codificação (encoding)

O Padrão de codificação utilizado é o UTF-8, todo conteúdo das mensagens deve seguir esse padrão.

É possível escapar os caracteres caso deseje ou codificar utilizando o formato HTTP.

Ao lado estão alguns exemplos de codificação

“messageText”:“A combinação foi perfeita :)”

Ou você pode escapar os caracteres caso queira:

“messageText”:“A combina\u00e7\u00e3o foi perfeita :)”

Envio de mensagens (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"}'

Ao fazer o envio, você receberá um JSON informando o id que foi gerado para esta mensagem (Response ou Resposta síncrona da Wavy):

[
{
"id":"9cb87d36-79af-11e5-89f3-1b0591cdf807",
"correlationId":"myId"
}
]

Via método GET, é possível realizar o envio de uma mensagem passando todos os parâmetros como query string.

URL para envios unitários com método GET

GET https://api-messaging.wavy.global/v1/send-sms?destination=..

Via método POST, é possível realizar o envio de uma mensagem passando todos os parâmetros no body.

URL para envios unitários com método POST

POST https://api-messaging.wavy.global/v1/send-sms - Content-Type: application/json

Parâmetros da Requisição

* Campo obrigatório

Campo

Detalhes

Tipo

destination*

Telefone para qual será enviada a mensagem (incluindo código de país). Exemplo: 5511900000000

String

messageText*

Texto da mensagem que será enviada (max 1280 chars).

String

correlationId

Um ID único definido por você para batimento com os status de envio (callback e DLR). Este parâmetro é opcional, e você pode utilizar o ID gerado pela Wavy para este batimento (max 64 chars).

String

extraInfo

Qualquer informação extra que você deseja adicionar a mensagem (max 255 chars).

String

timeWindow

Mensagens serão enviadas apenas no horário especificado. Por exemplo, Se você configurar uma janela [11, 12, 18], as mensagens serão enviadas entre 11:00 e 11:59, 12:00 e 12:59 e 18:00 e 18:59, este parâmetro deve ser definido na raiz do objeto JSON

Integer[]

expiresAt

A mensagem não será enviada após esta data. O formato utilizado é o Unix time . Obs: Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

Long

expiresInMinutes

A mensagem será expirada após o tempo informado neste campo. O tempo passa a ser ontabilizado assim que a mensagem é recebida pela Wavy. Obs: Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

Long

expiresDate

A mensagem não será enviada após esta data. O campo aceita o seguinte formato yyyy-MM-dd’T'HH:mm:ss. Obs: Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

String

scheduledAt

A mensagem não será enviada após esta data. IMPORTANTE! É possível realizar o agendamento apenas em um período superior a 30 minutos, pois é processado por um fluxo diferenciado do envio sem agendamento. O formato utilizado é o Unix time. Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

Long

delayedInMinutes

Minutos depois que a requisição é feita que a mensagem será enviada. Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

Long

scheduledDate

A mensagem não será enviada antes desta data. O campo suporta o seguinte formato yyyy-MM-dd’T'HH:mm:ss. Obs: Os campos expiresAt, expiresInMinutes e expiresDate são mutuamente exclusivos (use somente um deles)

String

timeZone

Especifica o timezone que será utilizado diretamente nos campos: expiresDate, scheduledDate and timeWindow (que será modificado caso seja utilizado timezones dinâmicos, como os com horário de verão). Se o timezone não estiver presente na requisição o sistema irá verificar o timezone do usuário - se presente - ou o timezone do país do usuário em último caso. Se nenhuma das opções estiverem presentes, o sistema irá utlizar o horário UTC

String

campaignAlias

Identificação de campanha criada previamente. Clique aqui para registar uma nova campanha, este parâmetro deve ser definido na raiz do objeto JSON

String

flashSMS

Flash SMS, use esta opção para enviar uma mensagem pop-up no telefone do usuário. Para enviar uma mensagem Flash passe o parametro true.

Boolean

flowId

Identificador do fluxo de Bot. O texto da mensagem virá do fluxo selecionado

String

subAccount

Referência da subconta. Ela só pode ser utilizada por usuários Administradores

String

params

Mapa de placeholders que serão substituídos no texto da mensagem. Se um ou mais parâmetros estiverem incorretos, a mensagem será marcada como inválida, mas o envio não será cancelado. É necessário enviar o flowId para utilizar os parâmetros

Map

Para cada usuário existe um token de autenticação único

Envio por método POST - Individual ou em 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" }}"

Existe um limite de 1000 mensagens por requisição

Ao fazer o envio, será retornado um objeto JSON com o UUID do lote e das mensagens individuais :

{
"id": "ce528d70-013b-11e7-98f2-e27c463c8809",
"messages": [
{
"id": "ce528d71-013b-11e7-98f2-e27c463c8809"
},
{
"id": "ce528d72-013b-11e7-98f2-e27c463c8809"
}
]
}

Permite o envio de mensagens em lote ou individuais passando os parametros em um objeto JSON Existe um limite de 1000 mensagens por requisição

Requisição HTTP Method POST

Exemplo 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"
}
}

Exemplo 4, com flowId e 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"
}

Exemplo 5, com templateId/templateName (possível com qualquer um ou ambos) e os parâmetros:

{
"messages":[
{
"destination":"5519900001111",
"params": {
"param1": "other_value1",
"param2": "other_value2"
}
},
{
"destination":"5519900002222"
}
],
"defaultValues":{
"params": {
"param1": "value1",
"param2": "value2"
}
},
"templateId": 0,
"templateName": 'name'
}

HTTP Status Code Response

Códigos de status HTTP mais comuns:

Grupo

Descrição

2xx

Sucesso

4xx

Erro Cliente

5xx

Erro Servidor

Código

Descrição

200

Sucesso

400

Requisição errada

401

Sem autorização

403

Proibido

404

Não encontrado

429

Muitas Requisições Realizadas

500

Erro Interno do Servidor

503

Serviço indisponível

504

Gateway Timeout

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

Status de envio (Callback e DLR)

Existem duas maneiras de obter os status de envio das mensagens, são elas:

  • Webhook - Receber os status em um webservice de sua empresa (recomendado)

Assim que entregamos a mensagem na operadora, ou assim que a operadora nos informa se entregou a mensagem no aparelho, a informação é repassada instantaneamente para você.

  • API de consulta - Fazer requisições de consulta em nossa API sms-status.

Os status ficam disponíveis por 3 dias, e podem ser consultados pelo UUID que a Wavy retornou ao receber a mensagem de sua empresa, ou pelo ID que sua empresa recebeu ao entregar a mensagem para a Wavy.

A desvantagem desta opção de Observe que nos exemplos acima, alguns campos “destination” não possuem um “messageText” atribudo direto a eles, nestes casos, o texto da mensagem será o “messageText” dentro de “defaultValues”. Essa função é útil quando é necessário o envio da mesma mensagem para vários números diferentes consultas ao invés de webhook, é que você fará requisições de consulta de um ID que pode ainda não ter sido entregue na operadora ou no aparelho, neste caso, uma série de requisições desnecessárias serão feitas. Por exemplo, se um usuário estava com o aparelho desligado quando você enviou uma mensagem para ele, e ligou 2 horas depois, você ficará consultando este ID inúmeras vezes por duas horas. E no caso da utilização de um webhook, esta informação seria enviada para você assim que fosse entregue no aparelho, sem requisições vazias.

As consultas de status possuem rate-limit de 1 requisição por segundo por endereço IP. Requisições além deste limite são respondidas com o código de status HTTP 429.

Status via webhook (entrega em seu webservice)

Para configurar o envio dos Callbacks e DRs (dúvida sobre os termos consulte a aba Termos Importantes) primeiramente é necessário logar no Wavy Messaging nas configurações da API, no formulário de configuração você poderá fornecer as URLs para onde serão enviado os status de envio (Callbacks) e os status de confirmação do aparelho (DRs)

Após a inclusão de seu webhook no portal acima, as configurações serão replicadas para nossa plataforma em até 10 minutos, e chamaremos sua URL quando as seguintes ações ocorrem:

Ação

Status de retorno enviado

Depois que uma mensagem for entregue ou não, na operadora

API de status de envio (callback)

Quando uma mensagem for entregue ou não, no aparelho do cliente

API de Delivery Report (DRs)

Exemplo JSON Status de Envio (callback - entrega na 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 resposta Callbacks (sent status)

Campo

Descrição

id

UUID gerado da mensagem

correlationId

Sua identificação desta mensagem

carrierId

Identificador da operadora

carrierName

Nome da operadora

destination

Número de telefone da mensagem enviada

sentStatusCode

Código de status gerado pelo Wavy para mensagem indicando o status de envio. Verifique em códigos de status para mais informações

sentStatus

descrição do status de envio. Verifique em códigos de status para mais informações

sentAt

Hora do envio, formato utilizado é o Unix_time

sentDate

Data que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ

campaignId

Identificador de campanha caso exista

extraInfo

Qualquer informação extra adicionada pelo cliente no envio da mensagem

Campos JSON resposta Delivery Reports (DRs)

Campo

Descrição

id

UUID gerado da mensagem

correlationId

Sua identificação desta mensagem

carrierId

Identificador da operadora

carrierName

Nome da operadora

destination

Número de telefone da mensagem enviada

sentStatusCode

Código de status gerado pela Wavy para mensagem indicando o status de envio. Verifique em códigos de status para mais informações

sentStatus

descrição do status de envio. Verifique em códigos de status para mais informações

sentAt

Hora do envio, formato utilizado é o Unix_time

sentDate

Data que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ

deliveredStatusCode

Código de status gerado pela Wavy para mensagem indicando o status de envio. Verifique em códigos de status para mais informações

deliveredStatus

descrição do status de envio. Verifique em códigos de status para mais informações

deliveredAt

Hora do envio, formato utilizado é o Unix_time

deliveredDate

Data que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ

campaignId

Identificador de campanha caso exista

extraInfo

Qualquer informação extra adicionada pelo cliente no envio da mensagem

Consulta Status via requisição HTTP

Para consultar o status das últimas mensagens enviadas é necessário fazer uma requisição POST na URL abaixo enviando o(s) UUID(s) e/ou o(s) correlationId(s) obtidos na resposta do envio:

POST https://api-messaging.wavy.global/v1/sms/status/search

{ "ids": ["918F3591-9AD6-11E7-9C9B-E255B01A8B1A","234F3591-6AD6-11E7-9C9B-E255B01A8B1A"], "correlationIds": ["2468"] }

Também é possível obter apenas os status ainda não consultados:

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

Observe que este endpoint retorna apenas os status ainda não retornados por este endpoint.

Resposta

Campos JSON de resposta:

Campo

Detalhes

Tipo

id

UUID gerado na requisição para a mensagem

String

correlationId

Mesmo correlationId da requisição

String

carrierId

ID da operadora, para mais informações consulte código de erro

Long

carrierName

Nome da operadora

String

destination

Número de telefone da mensagem enviada

String

sentStatusCode

Sent status code. Check Sent Status Codes for more information

Long

sentStatus

Sent status. Check Sent Status Codes for more information

String

sentStatusAt

When the message was sent. It is an Epoch Date

Long

sentStatusDate

When the message was sent. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone (ISO 8601)

String

deliveredStatusCode

Delivered status code. Check Delivered Status Codes for more information

Long

deliveredStatus

Delivered status. Check Delivered Status Codes for more information

String

deliveredAt

When the message was delivered. It is an Epoch Date

Long

deliveredDate

When the message was delivered. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone (ISO 8601)

String

campaignId

Campaign Identifier

Long

extraInfo

Any extra info set by the user when the message was sent

String

Exemplo JSON Delivery Report (DR ou DLR - Entrega no aparelho do usuário)

{
"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
}

Resposta do usuário (MO)

A API de MO permite a automação do processo de recuperação de respostas enviadas pelos clientes em resposta as mensagens que voce enviou a eles. Todas as requisições usam o método GET e as respostas são enviadas no formato JSON. IMPORTANTE! O recebimento de MOs esta habilitado por padrão apenas para os LAs 27182 e 28149, caso seja necessário receber as mensagens através de outros LAs será necessário entrar em contato com o suporte para avaliar.

É possível também a configuração para que as MOs sejam encaminhadas conforme chegaram para uma API do cliente, essa é a forma mais eficiente pois não é necessário realizar nenhuma chamada, so tratar os envios conforme chegaram. Para que esta configuração seja realizada é necessário abrir um ticket com nosso time de suporte técnico através do email customer.service@wavy.global passando a url que receberá os MOs. Conseguimos enviar os MOs tanto via método GET (query string) como via método POST (JSON)

Exemplo JSON enviado para sua 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": "customer.support@ifood.com"
}
}

Cada requisição feita irá retornar os MOs dos últimos 3 dias, até um limite de 1.000 MOs. Para datas anteriores ou quantidades maiores favor entrar em contato com nosso time de suporte através do email customer.service@wavy.global

O comportamento da query List MO será diferente para cada usuário autenticado devido ao nível de permissão de cada usuário.

Recomendamos o método de envio das MOs para API, toda MO enviada será automaticamente enviada para API pois desta forma as respostas podem ser tratadas imediatamente após o recebimento

Perfil

Permissão

Regular

cada requisição realizada na MO API só irá retornar os MOs correspondentes a subconta que o usuário pertence. Não é possível a um usuário regular recuperar MOs de outras subcontas.

Administrador

o comportamento padrão para o usuário administrador é recuperar todos os MOs de todas as subcontas. se um admin desejar recuperar os MOs de apenas uma das subcontas é necessário especificar a subconta no parametro subAccount com o id da subconta desejada.

Formato de resposta padrões de MO

Exemplo de JSON de resposta chamada API Wavy:

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

Tanto as requisições de listagem (list) e a função de busca (search) retornam um objeto JSON com os campos abaixo:

Campo

Detalhes

Tipo

total

O número total de MOs retornadas pela requisição

Integer

start

O limite minimo da query

String

end

O limite máximo da query

String

messages

Listagem dos objetos

List

Cada mensagem do campo messages possui a seguinte estrutura:

Campo

Detalhes

Tipo

id

Id da mensagem

String

subAccount

subconta responsável por enviar a mensagem que gerou a resposta

String

carrierId

Id da operadora

Integer

carrierName

Nome da operadora

String

source

Número de telefone que enviou a mensagem de resposta

String

shortCode

O shortcode da mensagem que originou a resposta e pelo qual a resposta foi enviada

String

messageText

Texto da mensagem de resposta

String

receivedAt

hora de recebimento

Long

receivedDate

Data e hora de recebimento em formato UTC

String

campaignAlias

Alias da campanha que originou a resposta

String

mt

MT original que gerou a resposta

MT

MTs tem a seguinte estrutura:

Campo

Detalhes

Tipo

id

Id da MT

String

correlationId

CorrelationID enviado na MT

String

username

Username do usuário responsavel por enviar a MT

String

email

Email do responsavel por enviar a MT

String

Requisição listar MO (list)

A Listagem irá retornar todos os MOs recebidos desde a última chamada de acordo com a resposta padrão descrita acima. Uma vez que esta chamada é realizada ela será consumida e não irá retornar as chamadas seguintes.

Como um usuário regular, para recuperar todas MOs de uma subconta use:

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

Como usuário administrador, para recuperar TODAS as MOs de TODAS subcontas use:

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

Como usuário administrador. para recuperar as MOs de uma subconta com a referencia “referencia_subconta”, use:

GET https://api-messaging.wavy.global/v1/sms/receive/list?subAccount=referencia_subconta

A requisição de busca (search request) irá retornar cada MO recebido num determinado periodo de tempo. Voce precisa definir os parametros start and end para especificar um periodo de tempo, deverá ser utilizado o formato ISO-8601. START por padrão é definido 5 dias antes da data atual e END por padrão é definido na data atual. Não é possivel recuperar MOs anteriores a 5 dias.

Como um usuário regular, para recuperar todas MOs de uma subconta use:

GET https://api-messaging.wavy.global/v1/sms/receive/search

Como usuário administrador, para recuperar TODAS as MOs de TODAS subcontas use:

GET https://api-messaging.wavy.global/v1/sms/receive/search

Como usuário administrador. para recuperar as MOs de uma subconta com a referencia “referencia_subconta”, use:

GET https://api-messaging.wavy.global/v1/sms/receive/search?subAccount=referencia_subconta

Busca 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

Somente com START especificado (utilizando END padrão, data atual)

GET https://api-messaging.wavy.globalv1/sms/receive/search?start=2016-09-12T00:00:00

Somente com END especificado (utilizando START padrão, 5 dias antes da data atual)

GET https://api-messaging.wavy.global/v1/sms/receive/search?end=2016-09-15T00:00:00

Usado valores padrão para START e END e especificado subconta

GET https://api-messaging.wavy.global/v1/sms/receive/search?subAccount=iFoodMarketing

Códigos de Status de Envio

Existem dois níveis de status, que são enviados independentemente.

1 - Primeiro status (sent_status - Status de envio = Callback)

Status de entrega na operadora, este é o primeiro status que retornamos, e todas as operadoras possuem.

Código

Mensagem

Significado

2

SENT_SUCCESS

Entregue na operadora com sucesso (Este é o status que deve ser considerado para efeito de cobrança.)

101

EXPIRED

Expirado antes de ser entregue ao aparelho

102

CARRIER_COMMUNICATION_ERROR

Erro de comunicação com a operadora

103

REJECTED_BY_CARRIER

Operadora rejeitou a mensagem

201

NO_CREDIT

O limite de mensagens setado pelo administrador de sua empresa, para sua conta ou sub conta, foi excedido. Ou, caso sua empresa utilize o modelo pré-pago de créditos, ele terminou.

202

INVALID_DESTINATION_NUMBER

O número de destino é inválido (Não é um número de celular válido).

203

BLACKLISTED

O número de destino está na lista bloqueada, e foi inserido manualmente por sua empresa.

204

DESTINATION_BLOCKED_BY_OPTOUT

O número de destino solicitou opt-out, e não quer receber mais mensagens desta sub conta. (Este status é específico para contas de mobile marketing).

205

DESTINATION_MESSAGE_LIMIT_REACHED

O número de destino já recebeu a quantidade máxima de mensagens que uma mesma empresa pode enviar, dentro de um período de tempo. (Este status é específico para contas de Mobile Marketing, e esta é uma regra das operadoras).

207

INVALID_MESSAGE_TEXT

O texto da mensagem contém palavras que não são aceitas pela operadora. Estas palavras podem ser de baixo calão, ou, caso sua conta seja de Mobile Marketing, podem ser de grandes marcas.

301

INTERNAL_ERROR

Ocorreu um erro na plataforma da Wavy.

2 - Segundo status (delivered_status - Delivery Report Callback)

Status de entrega no aparelho, este é o segundo status que retornamos e só existe para os casos em que o primeiro status acima foi de sucesso, ou seja, a mensagem foi entregue na operadora com sucesso. Neste status informamos se a mensagem foi ou não entregue no aparelho. As operadoras Oi e Sercomtel não possuem este segundo nível de status, para estas operadoras, o máximo de informação que existe, é o primeiro status, ou seja, se a operadora aceitou a mensagem ou não.

Código

Mensagem

Significado

4

DELIVERED_SUCCESS

Entregue no aparelho com sucesso.

104

NOT_DELIVERED

A operadora aceitou a mensagem, mas não conseguiu entregar no aparelho. Possíveis causas: Aparelho desligado ou fora de área de serviço por tempo determinado (normalmente 24 horas, mas algumas operadoras, como a Vivo, este tempo é de tentativa é de 8 horas). Número válido, mas inativo (algumas operadoras retornam este tipo de erro somente neste segundo nível de status).

API SMPP

Todos os serviços providos pela Wavy devem obrigatoriamente ser encriptados, e o protocolo SMPP não possui encriptação nativa. Neste caso, disponibilizamos duas opções para integração:

Opção 1 - SMPP over TLS + IP whitelist (Opção recomendada)

Esta é a opção que recomendamos. Caso seu sistema não possua esta funcionalidade, clique AQUI para obter ajuda na configuração de um proxy TLS.

Além da encriptação que será feita pelo TLS, o acesso será autorizado somente para o IP público de seu servidor. (Aceitamos múltiplos IPs e ranges) Esta informação deve ser enviada para o e-mail customer.service@wavy.global

Caso seja necessária a liberação de saída de tráfego em seu firewall, recomendamos que seja liberado qualquer IP de destino, na porta 2444, se isto não for possível, deve-se incluir regras com as liberações abaixo: 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

Opção 2 - SMPP over VPN

A encriptação e a liberação de acesso será feita via VPN.

Caso escolha esta opção, configure as VPNs utilizando os peers e hosts abaixo, já com as propostas de fase 1 e 2 que deseja. Envie o formulário de VPN de sua empresa preenchido para customer.service@wavy.global

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

Por razões de alta disponibilidade e balanceamento de carga, é obrigatório o estabelecimento das 2 VPNs acima, e a utilização do domínio smpp-messaging.wavy.global.com como destino de seu cliente SMPP, ao invés de IPs.

Detalhes de conexão

Informação

Detalhes

Hostname

smpp-messaging.wavy.global Ao configurar seu sistema SMPP, é obrigatório a utilização do domínio como destino, ao invés de IPs. Este domínio possui 4 proxies de entrada com round robin DNS e health check, e multiplos servidores backend. Baseado no volume de mensagens que sua empresa trafegará, vamos aumentar o número de binds(conexões) permitidos simultâneamente.

Porta

2444 (SMPP over TLS) ou 2443 (VPN)

Versão SMPP

3.4

Número de binds

Mínimo 4. O estabelecimento de pelo menos 4 binds é mandatório para obtenção de alta-disponibilidade e balanceamento de carga.

Codificação dos caracteres

GSM7 - Default (data_coding = 0) (GSM3.38 extended table is not supported by carriers.) LATIN1 (data_coding = 1) UCS2 (data_coding=8). Atenção: Verifique AQUI detalhes de caracteres e cobranças.

Flash SMS

Supported data_coding=0x10 para GSM7 e data_coding 0x18 para UCS2 Quando recebemos mensagens flashSMS de nossos clientes, elas são enviadas para as operadoras como flahsSMS, se a operadora não suportar flashSMS, ela é entregue como um SMS normal.

Enquire-link

Minimo: 30 segundos / Máximo: 59 segundos.

Concatenação

UDH 8-bit e 16-bit são suportados / UDH Headers.

Default addr_ton

1

Default addr_npi

1

window size

10

2way

Suportado

SMPP bind type

Transceiver(Recomendado). Binds transmit/receiver separados também são aceitos.

SMPP system_type

MovileSMSC

SMPP source addr (senderID)

Quando seu serviço necessitar respostas de usuários (MO), o source address deve ser igual ao system_id, ou seja, o nome do usuário. Quando o serviço não precisar de MOs, você pode utilizar qualquer coisa neste campo.

Max MO vazão

80 por bind

Max MT vazão

80 por bind

Server Timezone

UTC

Formato de ID

UUID

Default validity_period

24 hours

Status de envio (Callback e DLR)

1 - Primeiro status (sent_status - Status de envio = Callback)

Status de entrega na operadora, este é o primeiro status que retornamos, e todas as operadoras possuem.

stat

err

TLV (0x1403)

TLV (0x1404)

Significado

ACCEPTD

000

2

SENT_SUCCESS

Entregue na operadora com sucesso (Este é o status que deve ser considerado para efeito de cobrança.)

EXPIRED

101

101

EXPIRED

Expirado antes de ser entregue ao aparelho.

REJECTD

102

102

CARRIER_COMMUNICATION_ERROR

Erro de comunicação com a operadora.

REJECTD

103

103

REJECTED_BY_CARRIER

Operadora rejeitou a mensagem.

REJECTD

201

201

NO_CREDIT

O limite de mensagens setado pelo administrador de sua empresa, para sua conta ou sub conta, foi excedido. Ou, caso sua empresa utilize o modelo pré-pago de créditos, ele terminou.

REJECTD

202

202

INVALID_DESTINATION_NUMBER

O número de destino é inválido (Não é um número de celular válido).

REJECTD

203

203

BLACKLISTED

O número de destino está na lista bloqueada, e foi inserido manualmente por sua empresa.

REJECTD

204

204

DESTINATION_BLOCKED_BY_OPTOUT

O número de destino solicitou opt-out, e não quer receber mais mensagens desta sub conta. (Este status é específico para contas de mobile marketing).

REJECTD

205

205

DESTINATION_MESSAGE_LIMIT_REACHED

O número de destino já recebeu a quantidade máxima de mensagens que uma mesma empresa pode enviar, dentro de um período de tempo. (Este status é específico para contas de Mobile Marketing, e esta é uma regra das operadoras).

REJECTD

207

207

INVALID_MESSAGE_TEXT

O texto da mensagem contém palavras que não são aceitas pela operadora. Estas palavras podem ser de baixo calão, ou, caso sua conta seja de Mobile Marketing, podem ser de grandes marcas.

REJECTD

301

301

INTERNAL_ERROR

Ocorreu um erro na plataforma da Wavy.

UNKNOWN

301

301

INTERNAL_ERROR

Ocorreu um erro na plataforma da Wavy.

2 - Segundo status (delivered_status - Delivery Report Callback)

Status de entrega no aparelho, este é o segundo status que retornamos e só existe para os casos em que o primeiro status acima foi de sucesso, ou seja, a mensagem foi entregue na operadora com sucesso. Neste status informamos se a mensagem foi ou não entregue no aparelho. As operadoras Oi e Sercomtel não possuem este segundo nível de status, para estas operadoras, o máximo de informação que existe, é o primeiro status, ou seja, se a operadora aceitou a mensagem ou não.

stat

err

TLV (0x1403)

TLV (0x1404)

TLV (0x1405)

TLV (0x1406)

Significado

DELIVRD

000

2

SENT_SUCCESS

4

DELIVERED_SUCCESS

Entregue no aparelho com sucesso.

UNDELIV

104

2

SENT_SUCCESS

104

NOT_DELIVERED

A operadora aceitou a mensagem, mas não conseguiu entregar no aparelho. Possíveis causas: Aparelho desligado ou fora de área de serviço por tempo determinado (normalmente 24 horas, mas algumas operadoras, como a Vivo, este tempo é de tentativa é de 8 horas). Número válido, mas inativo (algumas operadoras retornam este tipo de erro somente neste segundo nível de status).

Os status de entrega no aparelho, operadora e MOs são enfileirados caso ocorra algum problema de conectividade, porém o prazo é de 8h, após este período não será possível obter os status por SMPP.

Proxy TLS - Linux

O proxy é necessário caso a conexão não seja via VPN. Como explicado anteriormente, o protocolo SMPP não possui encriptação TLS nativa, neste caso indicamos o proxy abaixo:

HAProxy

Instalando HAProxy

Debian Like

Em distribuições Debian like através do repositorio: sudo apt-get install haproxy

RedHat Like

Como não há, até o momento, o pacote do HAProxy com suporte à TLS já no repositorio, é possível baixar atraés do site oficial: http://www.haproxy.org/

Ao lado um script para instalação

sudo yum install wget gcc pcre-static pcre-devel -y
wget http://www.haproxy.org/download/1.6/src/haproxy-1.6.3.tar.gz -O ~/haproxy.tar.gz
tar xzvf ~/haproxy.tar.gz -C ~/
cd ~/haproxy-1.6.3
make TARGET=linux2628 USE_LINUX_TPROXY=1 USE_ZLIB=1 USE_REGPARM=1 USE_OPENSSL=1 USE_PCRE=1
sudo make install
sudo cp /usr/local/sbin/haproxy /usr/sbin/
sudo cp ~/haproxy-1.6.3/examples/haproxy.init /etc/init.d/haproxy
sudo chmod 755 /etc/init.d/haproxy
sudo mkdir -p /etc/haproxy
sudo mkdir -p /run/haproxy
sudo mkdir -p /var/lib/haproxy
sudo touch /var/lib/haproxy/stats
sudo useradd -r haproxy
sudo haproxy -vv

Configuração 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.movile.com smpp-messaging.wavy.global.com:2444 ssl resolvers dns check inter 15000
  • Instalação haproxy servidores (red-hat / centos):

$sudo yum install -y openssl-devel haproxy

  • Instalação haproxy servidores (debian / ubuntu)

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

  • Após a instalação, substitua todo conteudo do arquivo /etc/haproxy/haproxy.cfg pelo o conteudo ao lado ->

IMPORTANTE: Configure seu sistema (cliente SMPP) para utilizar como endereço destino 127.0.0.1:2444

Proxy TLS - Windows

configuração 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.com;
}
server {
listen 2444;
proxy_pass $backend:2444;
proxy_ssl on;
}
}

É possível utilizar o nginx como proxy TLS em servidores windows para realizar a encriptação dos dados

Faça o download da versão abaixo (importante utilizar esta versão pois as versões antigas resolvem o nome apenas na primeira request)

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

Extrai o arquivo .zip no local desejado e substitua o conteudo do arquivo conf/nginx.conf com os dados ao lado

API SFTP

Detalhes de conexão

Hostname

ftp-messaging.wavy.global

Porta

2222

Protocolo

SFTP (transferência sobre ssh, provendo criptografia entre cliente-servidor)

Autenticação

username + senha (fornecido pelo suporte)

Portal

messaging.wavy.global

É necessária a liberação de seus IPs no firewalls da Wavy Se for necessário liberação de firewall para saída sentido a porta 2222, você deve liberar o DNS, ou os IPs 200.219.220.54, 200.189.169.53 e 45.236.179.22

Envio de mensagem via SFTP

Para realizar o disparo de mensagens via SFTP é necessário gerar um arquivo em formato TXT, a formatação deve seguir o exemplo abaixo:

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

O nome do arquivo a ser enviado deve seguir o seguinte formato:

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

As subcontas(projetos) podem ser criadas pelo próprio cliente no portal. Caso não seja seguida a nomenclatura acima, o envio será feito pela subconta padrão do cliente.

Exemplo:

3486.20170101.01.txt ou PROJETO1.20170101.01.txt

É importante seguir a nomenclatura definida para que o envio seja as mensagens sejam debitadas da subconta correta.

Após deverá ser realizado o envio do arquivo para o servidor sftp no diretório upload. O arquivo será movido para o diretório success após o término, caso seja apresentando algum erro o arquivo será movido para o diretório error.

API Validação de número

API para validação de números de telefone, onde retornamos a operadora atual dos números consultados (incluindo números portados), ou se o número não é válido, ou seja, não é um número de celular.

IMPORTANTE: As consultas de number lookup possuem uma tarifação diferenciada dos envios de SMS, antes de realizar a consulta verifique com o responsável do time comercial

Autenticação

Para efetuar envios e consultas em nossa API é necessária a autenticação por meio de usuário ou e-mail, em conjunto com um token.

Campo

Detalhes

Data Type

UserName

Seu usuário ou email

String

AuthenticationToken

Seu token de autenticação. Verifique aqui e leia as descrições de usuários abaixo.

String

Detalhes de conexão

Hostname

api-messaging.wavy.global

APIs

/v1/carrier/lookup

Porta

443 (https)

Protocolo

HTTPS (encriptação TLS)

Autenticação

username + token

Portal

messaging.wavy.global

Requisição 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 a consulta basta adicionar no body da requisição um json com o array de números. É possivel fazer a consulta utilizando os formatos +55(19)999999999 e 5519999999999

Resposta consulta

Resposta chamada em 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"
}
}
]
}

O último número do exemplo trata-se de um número inválido para demonstrar como a consulta retorna o JSON nesses casos.

A resposta da consulta em lote conterá um arquivo JSON com as informações individuais sobre cada número consultado:

Campo

Detalhes

Tipo

id

UUID gerado para este lote

String

destinations

Este campo é um array com as respostas das consultas individuais do lote, contém o id e o correlationId de cada número consultado

IndividualResponse[]

destination

Número de telefone consutado

Long

active

status do número na operadora (atualmente verificar apenas se o número pertence a operadora, não ativo / em uso)

Boolean

carrier

Operadora e país a qual pertece o número consultado

array[]

name

Nome da operadora

String

countryCode

Código do País

String

Acentos e caracteres especiais

Mensagens que possuem somente caracteres que estão na tabela abaixo, são cobradas a cada 160 caracteres. Caso a mensagem possua um ou mais caracteres que não estão na tabela abaixo, a cobrança é feita a cada 70 caracteres, conforme especificação do protocolo na rede das 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

Observações:

• A habilitação do uso de acentos e caracteres especiais deve ser solicitada ao suporte.

• No caso em que a operadora destino não aceita acentos e caracteres (Sercomtel), nossa plataforma faz automaticamente para os nossos clientes, a substituição dos mesmos, por exemplo: á para a, é para e, etc.

Textos grandes (concatenação)

O protocolo utilizado na rede das operadoras possui os limites de 70 ou 160 caracteres, para mensagens com ou sem caracteres especiais, respectivamente. Mas é possível enviar mensagens maiores com a utilização de concatenação, onde o aparelho reagrupa as mensagens ao recebê-las.

Para os clientes integrados via HTTPS, SFTP, ou MQ, não existe nenhum indicador adicional para ativar a concatenação, bastando enviar o texto da mensagem grande em uma única requisição.

Para os clientes integrados via SMPP, deve-se utilizar a funcionalidade de concatenação com indicadores no header (UDH), LINK.

É importante notar que, apesar de aparecerem no aparelho como uma única mensagem grande, as mensagens continuam trafegando na rede das operadoras individualmente, e neste caso, continuamos sendo cobrados e cobrando individualmente, a cada 63 ou 160 (dependendo dos caracteres utilizados). Lembrando que ao utilizar concatenação parte do caracteres (70 ou 160) são utilizados pelo header.

Observação: Nos casos de operadoras que não suportam a funcionalidade de concatenação (Exemplos: Sercomtel), a Wavy envia as mensagens separadamente, sem concatenar, e inclui indicadores de ordem automaticamente para nossos clientes. Ex: