Introdução
Seja bem vindo a nossa documentação para desenvolvedores. Aqui você encontrará tudo que precisa para integrar sua empresa à nossa plataforma de mensagens.
É possível fazer a integração através das seguintes formas:
| API HTTPS | Permite o envio e recebimento de mensagens e status através do protocolo HTTPS utilizando os métodos GET ou POST |
| API SMPP | Protocolo especifico para troca de mensagens SMS, permite manter uma conexão ativa constante com nosso servidor SMPP, e é indicado para clientes com tráfego superior a 5 milhões de mensagens por mês |
| API SFTP | Protocolo utilizado para transferência de arquivos, é indicado para envios de mensagens em massa (lote). Os arquivos são transferidos pelo cliente para nossos servidores, e são imediatamente processados |
| Websphere MQ | Utilizado para transferência de mensagens entre servidores Websphere MQ, é indicado para clientes com tráfego superior a 30 milhões de mensagens por mês, principalmente para bancos financeiros, onde o cliente já possui este sistema em funcionamento para mensagens internas. Esta opção de integração possui um valor de setup e manutenção de ambiente, fixados em R$50.000,00 e R$2.000,00 respectivamente |
SMS API
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). |
| 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. |
| 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. Obs1: 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. Obs2: É 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) |
| 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. |
| 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 |
Fluxo de mensagem
Fluxo simplificado - MT, Callback, DLR, e 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. |
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.
É possivel 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
require 'uri'
require 'net/http'
url = URI("https://api-messaging.wavy.global/v1/send-sms")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = "{\"destination\": \"5511900000000\" , \"messageText\": \"linha\\nquebrada\"}"
response = http.request(request)
puts response.read_body
import requests
url = "https://api-messaging.wavy.global/v1/send-sms"
payload = "{\"destination\": \"5511900000000\" , \"messageText\": \"linha\\nquebrada\"}"
headers = {
'username': "<username>",
'authenticationtoken': "<authenticationtoken>",
'content-type': "application/json"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
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"}'
> sudo apt-get/yum install php5-curl
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-messaging.wavy.global/v1/send-sms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"destination\": \"5511900000000\" , \"messageText\": \"linha\\nquebrada\"}",
CURLOPT_HTTPHEADER => array(
"authenticationtoken: <authenticationtoken>",
"username: <username>",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
public class SendSms {
public static void main(String[] args) {
String url = "https://api-messaging.wavy.global/v1/send-sms";
String userName = "<username>";
String authenticationToken = "<authenticationtoken>";
String body = "{\"destination\": \"5511900000000\" , \"messageText\": \"linha\\nquebrada\"}";
String response = doPost(url, body, userName, authenticationToken);
System.out.println(response);
}
public static String doPost(String strUrl, String request, String userName, String authenticationToken) {
HttpURLConnection conn = null;
OutputStreamWriter wr = null;
BufferedReader br = null;
try {
URL url = new URL(strUrl);
conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setUseCaches(false);
conn.setInstanceFollowRedirects(true);
conn.setConnectTimeout(30000);
conn.setReadTimeout(30000);
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("UserName", userName);
conn.setRequestProperty("AuthenticationToken", authenticationToken);
// write the request
wr = new OutputStreamWriter(conn.getOutputStream());
wr.write(request);
wr.close();
// read the response
br = new BufferedReader(new InputStreamReader(conn.getInputStream()));
StringBuilder resp = new StringBuilder();
String line;
while ((line = br.readLine()) != null) {
resp.append(line).append("\n");
}
return resp.toString();
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
if (wr != null) {
wr.close();
}
if (br != null) {
br.close();
}
if (conn != null) {
conn.disconnect();
}
} catch (IOException e) {
e.printStackTrace();
}
}
return null;
}
}
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, é possivel 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, é possivel 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
Parametros da Requisição
* Campo obrigatório
| Campo | Detalhes | Tipo |
|---|---|---|
| destination* | Telefone para qual será enviada a mensagem (incluido 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! É possivel realizar o agendamento apenas em um periodo 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 dinamicos, 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 |
Envio por método POST - Individual ou em lote
require 'uri'
require 'net/http'
url = URI("https://api-messaging.wavy.global/v1/send-bulk-sms")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = '{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}'
response = http.request(request)
puts response.read_body
import requests
url = "https://api-messaging.wavy.global/v1/send-bulk-sms"
payload = '{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}'
headers = {
'username': "<username>",
'authenticationtoken': "<authenticationtoken>",
'content-type': "application/json"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
curl --request POST \
--url https://api-messaging.wavy.global/v1/send-bulk-sms \
--header 'authenticationtoken: <Token de autenticação>' \
--header 'username:<Usuário Wavy Messaging>' \
--header 'content-type: application/json' \
--data "{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}"
Mod: curl
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-messaging.wavy.global/v1/send-bulk-sms",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{ \"messages\":[{ \"destination\":\"5519999999999\", \"messageText\":\"First message\" }, { \"destination\":\"5519999999999\" }, { \"destination\":\"5519999999999\" }], \"defaultValues\":{\"messageText\":\"Default message\" }}",
CURLOPT_HTTPHEADER => array(
"authenticationtoken: <authenticationtoken>",
"content-type: application/json",
"username: <username>"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
public class SendSms {
public static void main(String[] args) {
String url = "https://api-messaging.wavy.global/v1/send-bulk-sms";
String userName = "<username>";
String authenticationToken = "<authenticationtoken>";
String body = "{ \"messages\":[{ \"destination\":\"5519999999999\", \"messageText\":\"First message\" }," +
" { \"destination\":\"5519999999999\" }, { \"destination\":\"5519999999999\" }]," +
" \"defaultValues\":{\"messageText\":\"Default message\" }}";
String response = doPost(url, body, userName, authenticationToken);
System.out.println(response);
}
public static String doPost(String strUrl, String request, String userName, String authenticationToken) {
HttpURLConnection conn = null;
OutputStreamWriter wr = null;
BufferedReader br = null;
try {
URL url = new URL(strUrl);
conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setUseCaches(false);
conn.setInstanceFollowRedirects(true);
conn.setConnectTimeout(30000);
conn.setReadTimeout(30000);
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("UserName", userName);
conn.setRequestProperty("AuthenticationToken", authenticationToken);
// write the request
wr = new OutputStreamWriter(conn.getOutputStream());
wr.write(request);
wr.close();
// read the response
br = new BufferedReader(new InputStreamReader(conn.getInputStream()));
StringBuilder resp = new StringBuilder();
String line;
while ((line = br.readLine()) != null) {
resp.append(line).append("\n");
}
return resp.toString();
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
if (wr != null) {
wr.close();
}
if (br != null) {
br.close();
}
if (conn != null) {
conn.disconnect();
}
} catch (IOException e) {
e.printStackTrace();
}
}
return null;
}
}
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
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"
}
Observe que nos exemplos acima, alguns campos “destination” não possuem um “messageText” atribuido 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
POST https://api-messaging.wavy.global/v1/send-bulk-sms Content-Type: application/json
O corpo da requisição precisa conter o objeto JSON com as informações conforme campos abaixo:
* Campo obrigatório
| Campo | Detalhes | Tipo |
|---|---|---|
| destination* | Telefone para qual será enviada a mensagem (incluido 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 | 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. 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 dinamicos, 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 | 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 |
Respostas de mensagens em lote
A resposta do envio em lote conterá um arquivo JSON com as informações necessárias para rastreio, será gerado um id para o lote todo e um id e correlationId individual para cada mensagem:
| Campo | Detalhes | Tipo |
|---|---|---|
| id | UUID gerado para este lote | String |
| messages | Este campo é um array com as respostas das mensanges individuais do lote, contém o id e o correlationId de cada mensagem enviada | SingleSMSResponse[] |
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 |
| 500 | Erro Interno do Servidor |
| 503 | Serviço indiponível |
| 504 | Gateway Timeout |
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 consulta 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.
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 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 |
| deliveredStatusCode | Código de status gerado pelo 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 obter uma lista dos status ainda não consultados, você pode fazer uma solicitação GET para o URL abaixo:
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.
É 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 nosso Service Center passando a url que receberá os MOs.
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 ultimos 5 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 nosso Service Center.
O comportamento da query List MO será diferente para cada usuário autenticado devido ao nivel de permissão de cada usuário.
| 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 é possivel 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. |
Fomato 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 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
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 exito (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 |
| 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). |
| 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. |
| 213 | COUNTRY_NOT_ALLOWED_FOR_CUSTOMER | O cliente não tem permissão para enviar mensagens para o país do número receptor desejado. |
| 214 | INVALID_CUSTOMER_CONFIGURATION | Algumas configurações do cliente estão inválidas ou faltando. |
| 215 | CUSTOMER_QUOTA_BLOCKED | O quota do cliente está bloqueado ou atingiu seu limite. |
| 301 | INTERNAL_ERROR | Um ou mais problemas ocorreram com a nossa plataforma, assim as mensagens não puderam ser processadas e enviadas. |
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). |
| 401 | MESSAGE_SPLIT | Ocorre quando a mensagem de SMS atinge seu formato válido; de 160 caractéres sem acento ou 70 sem acentuação. A mensagem final será formatada de acordo com o limite de caracteres, e aparecerá nos relatórios finais de acordo com essa formatação. |
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 nosso time de suporte através do nosso Service Center.
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:2444200.219.220.193:244445.236.179.18:244445.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 para o nosso time de suporte através do nosso Service Center.
peer 200.155.0.250hosts 200.219.220.8 e 200.219.220.193port 2443
peer 45.236.178.12hosts 45.236.179.18 e 45.236.179.19port 2443
Obs: 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 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). |
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.wavy.global smpp-messaging.wavy.global: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;
}
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 |
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
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.
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"]
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api-messaging.wavy.global/v1/carrier/lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}",
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"authenticationtoken: <authenticationtoken>",
"username: <username>"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
require 'uri'
require 'net/http'
url = URI("https://api-messaging.wavy.global/v1/carrier/lookup")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["authenticationtoken"] = '<authenticationtoken>'
request["username"] = '<username>'
request["Content-Type"] = 'application/json'
request.body = "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}"
response = http.request(request)
puts response.read_body
import requests
url = "https://api-messaging.wavy.global/v1/carrier/lookup"
payload = "{\n\t\"destinations\": [\"+55(19)997712322\", \"5519997712322\", \"2312312\"]\n}"
headers = {
'Content-Type': "application/json",
'authenticationtoken': "<authenticationtoken>",
'username': "<username>"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
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:
1 - A habilitação do uso de acentos e caracteres especiais deve ser solicitada ao suporte.
2 - 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 dos 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:
Inicio do texto…. (½)
……fim do texto (2/2)
F—
Wavy Messaging WhatsApp API
Esta documentação fornece informações sobre como sua aplicação poderá enviar as mensagens de Whatsapp via API utilizando a plataforma Wavy Messaging.
Você também encontrará aqui informações sobre Webhooks, que são retornos de chamada HTTP definidos pelo usuário, que são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, a API da Wavy coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) para URL fornecida pelo cliente, atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem do usuário final (MO).
A Wavy Messaging WhatsApp API permite o envio de mensagens únicas ou em lote. A API possui integração REST, utilizando o protocolo HTTP com TLS, suportando o método POST com os parâmetros enviados em formato JSON.
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). |
| 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 status de envio que retornamos, onde informamos se foi possível, ou não, fazer a entrega da mensagem para o WhatsApp, se foi entregue para o Usuário e se a mensagem foi lida. |
| MO | Mobile Originated | É o termo utilizado para mensagens que possuem sua empresa como destino. Ou seja, mensagens que foram originadas pelo usuário (aparelho). |
Fluxo de mensagem
Fluxo simplificado - MT, Callback e MO.
Pré Requisitos
- Para utilizar a API da Wavy Messaging, primeiro você deve ter uma conta ativa na plataforma Wavy messaging. Consulte a documentação sobre Conta e Configurações para obter mais informações sobre como fazer esse procedimento.
- Você também deverá ter usuário e token válidos associados a essa conta. Saiba como criar seu usuário no nosso guia Adicionar usuários.
- Com as credenciais acima, você ja poderá começar a utilizar a API da Wavy Messaging.
Detalhes da conexão
| Hostname | api-messaging.wavy.global |
| Porta | 443 (https) |
| Protocolo | HTTPS (TLS encryption) |
| Autenticação | UserName e AuthenticationToken |
| Encoding | UTF-8 |
Fazendo chamadas para a API da Wavy Messaging
Para fazer suas primeiras chamadas, recomendamos o uso do aplicativo “Postman” para realizar testes com requisições no formato JSON antes de realizar as configurações em produção.
Nota: Para enviar mensagens de teste, você precisa ter um modelo de mensagem aprovado na sua conta do WhatsApp Business. Consulte nossa documentação sobre Criação de modelo de mensagem WhatsApp para criar seus primeiros modelos.
Caso ainda não possua nenhum modelo de mensagem aprovado você ainda pode enviar mensagens teste, desde que o destinatário faça uma interação com o número de origem. Dessa forma, uma janela de atendimento ao cliente será ativada. Ela permite que você envie qualquer tipo de mensagem em uma janela de 24 horas. Se a mensagem chegar, significará que sua requisição à API da Wavy Messaging foi bem-sucedida. Caso contrário, verifique seu Webhook em busca de notificações que possam indicar algum problema.
Envio de Mensagens
As chamadas para a API Wavy Messaging devem ser realizadas para a URL https://api-messaging.wavy.global/v1/whatsapp/send no formato POST independentemente do tipo de mensagem, no entanto, o conteúdo do corpo da mensagem JSON varia para cada tipo de mensagem.
Os campos de autenticação no header também seguirão o mesmo formato, independente do tipo de mensagem:
| POST | /v1/whatsapp/send HTTP/1.1 |
| Host: | api-messaging.wavy.global |
| UserName: | user_name |
| AuthenticationToken: | aaaaaa-bbbbbbbbbbbbbXXXXX12 |
| Content-Type: | application/json |
A requisição precisa conter um objeto JSON no corpo com os seguintes campos:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| destinations | Sim | Lista de Destinos | Destino[] |
| message | Sim | Mensagem de Texto que será enviada a todos os destinos | Mensagem |
| flowId | Não | Identificador de Fluxo do Bot | String |
| defaultExtraInfo | Não | Dados adicionais que identifiquem o envio, serão vinculados a todos os destinatários que receberão a mensagem | String |
| campaignAlias | Não | ID da campanha, é linkado com todas as mensagens enviadas | String |
Destino:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| correlationId | Não | Id definido por voce que será retornado na configuração da mensagem (callback). Isto é útil em casos quando é necessário rastear os envios das mensagens, pois é possivel definir ids diferentes para diferentes mensagens. | String |
| destination | Sim | Número de telefone (código do país — 55 para Brasil — e DDD devem estar presentes) ou o WhatsApp group ID que receberá a mensagem. Exemplos:5519900001111, +5519900001111, +55(19) 900001111. | String |
| recipientType | No | Deve ser "individual" ou "group", dependendo se campo destination é um número de telefone ou um group ID. |
String |
Mensagem:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| messageText | Sim | Campo usado quando for necessário enviar uma mensagem personalizada em resposta a uma mensagem recebida. | text |
| image | Sim | Campo utilizado quando for necessário o envio de uma imagem. | Image |
| audio | Sim | Campo utilizado quando for necessário o envio de uma áudio. | Audio |
| document | Sim | Campo utilizado quando for necessário o envio de uma documento. | Document |
| location | Sim | Campo utilizado quando for necessário o envio de uma localização. | Location |
| contacts | Sim | Campo utilizado quando for necessário o envio de contato(s). | Contact[] |
| previewFirstUrl | Não | Controla a exibição no app da primeira URL enviada ao usuário | Boolean |
Exemplo de requisição com texto
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"messageText": "mensagem de teste"
}
}
Exemplo de requisição com Imagem (URL)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"url": "http://...jpg",
"caption": "image description"
}
}
}
Exemplo de requisição com Imagem (Base64)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"data": "ZmlsZQ=="
}
}
}
Exemplo de requisição com Audio (URL)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"url": "http://...mp3"
}
}
}
Exemplo de requisição com Audio (Base64)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"data": "ZmlsZQ=="
}
}
}
Exemplo de requisição com Documento (URL)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"url": "http://...pdf",
"caption": "pdf description"
}
}
}
Exemplo de requisição com Documento (Base64)
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"data": "ZmlsZQ=="
}
}
}
Exemplo de requisição de localização
{
"destination": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"location": {
"geoPoint": "-22.894180,-47.047960",
"name": "Wavy",
"address": "Av. Cel. Silva Telles"
}
}
}
Exemplo de requisição com Contatos
{
"destinations":[
{
"correlationId":"MyCorrelationId",
"destination":"5519900001111"
}
],
"message":{
"contacts":[
{
"addresses":[
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"1 Hacker Way",
"type":"HOME",
"zip":"94025"
},
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"200 Jefferson Dr",
"type":"WORK",
"zip":"94025"
}
],
"birthday":"2012-08-18",
"emails":[
{
"email":"test@fb.com",
"type":"WORK"
},
{
"email":"test@whatsapp.com",
"type":"WORK"
}
],
"name":{
"first_name":"John",
"formatted_name":"John Smith",
"last_name":"Smith"
},
"org":{
"company":"WhatsApp",
"department":"Design",
"title":"Manager"
},
"phones":[
{
"phone":"+1 (940) 555-1234",
"type":"HOME"
},
{
"phone":"+1 (650) 555-1234",
"type":"WORK",
"wa_id":"16505551234"
}
],
"urls":[
{
"url":"https://www.fb.com",
"type":"WORK"
}
]
}
]
}
}
Uma mensagem personalizada deve ser enviada somente quando a sessão de conversa estiver aberta, ou seja, quando o envio for uma resposta para uma mensagem enviada pelo usuário. Se a sessão não estiver aberta ou o usuário não enviar uma mensagem, um Template deverá ser utilizado no envio.
Texto:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| messageText | Sim | Texto que será enviado ao usuário |
Imagem:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| tipo | Sim | Tipo/extensão da imagem que será enviada na mensagem. Opções disponiveis: JPG, JPEG, PNG. | String |
| caption | Não | Texto que será apresentado ao usuário embaixo da imagem | String |
| url | Sim | URL que hospeda o arquivo a ser enviado. | String |
| data | Sim | conteúdo encodado em Base64 | String |
Audio:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| type | Sim | Tipo/extensão do audio que será enviado na mensagem. Opções disponiveis: AAC, MP4, AMR, MP3, OGG. | String |
| url | Sim | URL que hospeda o arquivo a ser enviado. | String |
| data | Sim | conteúdo encodado em Base64 | String |
Documento:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| type | Sim | Tipo/extensão do documento que será enviado na mensagem. Opções disponiveis: PDF. | String |
| caption | Não | Texto que será apresentado ao usuário embaixo do documento | String |
| url | Sim | URL que hospeda o arquivo a ser enviado. | String |
| data | Sim | conteúdo encodado em Base64 | String |
Contact:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| addresses | Não | Endereço(s) completo(s) do contato. | Address[] |
| birthday | Não | Data de aniversário com formato YYYY-MM-DD. | String |
| emails | Não | Endereço(s) de e-mail de contato. | Email[] |
| name | Não | Nome completo do contato. | Name |
| org | Não | Informações da organização do contato. | Org |
| phones | Não | Número(s) de telefone do contato. | Phone[] |
| urls | Não | URL(s) do contato. | Url[] |
Address:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| street | Não | Nome e número da rua. | String |
| city | Não | Nome da cidade. | String |
| state | Não | Sigla do Estado. | String |
| zip | Não | CEP. | String |
| country | Não | Nome completo do país. | String |
| country_code | Não | Abreviação de país (Duas letras). | String |
| type | Não | Valores Padrões: HOME, WORK. | String |
Email:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| Não | Endereço de e-mail. | String | |
| type | Não | Valores Padrões: HOME, WORK. | String |
Name:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| first_name | Não | Primeiro nome. | String |
| last_name | Não | Último nome. | String |
| middle_name | Não | Nome do meio. | String |
| name_suffix | Não | Sufixo do nome. | String |
| name_prefix | Não | Prefixo do nome. | String |
| formatted_name | Não | Nome completo como normalmente aparece. | String |
Org:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| company | Não | Nome da organização do contato. | String |
| department | Não | Nome do departamento do contato. | String |
| title | Não | Título corporativo do contato. | String |
Phone:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| phone | Não | Número de telefone formatado. | String |
| type | Não | Valores padrões: CELL, MAIN, IPHONE, HOME, WORK. | String |
| wa_id | Não | Identficador WhatsApp. | String |
Url:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| phone | Não | URL do contato. | String |
| type | Não | Valores padrões: HOME, WORK. | String |
Envio de Template
Exemplo de requisição de Template
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"template": {
"namespace" : "aaaaaaaa_bbbb_cccc_dddd_eeeeeeeeeeee",
"elementName" : "some_approved_image_hsm"
},
{
"languagePolicy": "DETERMINISTIC",
"languageCode": "pt_BR"
}
}
}
Exemplo de requisição de Template com Header e Parâmetros
{
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"template": {
"namespace" : "aaaaaaaa_bbbb_cccc_dddd_eeeeeeeeeeee",
"elementName" : "some_approved_image_hsm",
"header": {
"parameters": [
"header_parameter_1"
]
},
"bodyParameters": [
"https://upload.wikimedia.org/wikipedia/commons/c/c3/Arquivo.jpg"
],
"languagePolicy": "DETERMINISTIC",
"languageCode": "pt_BR"
}
}
}
Caso você ainda não possua um Template criado e aprovado para uso, consulte a documentação sobre Template de WhatsApp para obter mais informações sobre como fazer esse procedimento.
O corpo da requisição deve conter um objeto JSON com os seguintes campos:
| Field | Required | Details | Type |
|---|---|---|---|
| destinations | Sim | Detalhes sobre os identificadores do envio e destino | Destination[] |
| message | Sim | Detalhes sobre o objeto MESSAGE que será enviado | mensagem |
| defaultExtraInfo | Não | Dados adicionais que identificam a submissão que será relacioanda a todos que receberem a mensagem | String |
| campaignAlias | Não | Campaign ID, é relacionada a todas as mensagens enviadas | String |
destinations:
| Field | Required | Details | Type |
|---|---|---|---|
| correlationId | Não | Id definido pelo cliente que será retornado no status da mensagem (callback). Você pode usar esse id para rastrear envios de mensagens de maneira personalizada. | String |
| destination | Sim | Número de telefone que receberá a mensagem (código do país (55 para Brasil) e DDD são obrigatórios). Exemplos: 5519900001111, +5519900001111, +55(19) 900001111. | String |
message:
| Campo | Obrigatório | Detalhes | Type |
|---|---|---|---|
| template | Sim | Detalhes sobre o objeto TEMPLATE que será enviado. | Template |
template:
| Field | Required | Details | Type |
|---|---|---|---|
| namespace | Sim | ID do namespace que será usado. NOTA: Os parâmetros namespace e element_name devem corresponder ao Business Manager que o número de origem está associado, ou a mensagem terá falha no envio. | String |
| elementName | Sim | Nome do modelo cadastrado e aprovado. | String |
| header | Sim, quando o Template possuir parâmetro no header | Objetos do cabeçalho com seus parâmetros | Header |
| bodyParameters | Sim (caso o template use variáveis) | A soma de todos os caracteres do corpo, considerando campos fixos e dinâmicos, é limitada a 1024 caracteres se o modelo registrado tiver apenas o corpo. É limitado a 160 caracteres se você tiver um cabeçalho ou rodapé. | Lista de strings |
| languageCode | Sim, quando houver mais de um idioma cadastrado para o mesmo template. | Codes: pt_BR, en, es, en_US, en_GB, pt_PT, es_AR, es_ES, es_MX, it, fr | String |
header:
| Field | Required | Details | Type |
|---|---|---|---|
| parameters | Opcional | Lista de parâmetros que serão substituídos no texto do cabeçalho. Nota: Caso esteja presente, o cabeçalho não deve ter título nem nenhum elemento. | String |
| title | Opcional | O título deve ter até 60 caracteres | String |
| (element) | Sim | Opções: text (padrão), image, audio, document, video. | Object |
element:
| Field | Required | Details | Type |
|---|---|---|---|
| url | Sim | URL da mídia. Use somente com URLs HTTP/HTTPS. | String |
| type | Sim | Tipo da midia (JPEG, MP3, PDF, etc) | String |
Webhooks
Exemplo
{
"total": 1,
"data": [
{
"id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
"correlationId": "...",
"destination": "5519900000000",
"origin": "5519900000000",
"campaignId": 100,
"campaignAlias": "...",
"flowId": "...",
"extraInfo": "...",
"sent": true,
"sentStatusCode": 1,
"sentStatus": "sent status",
"sentDate": "2017-12-18T17:09:31.891Z",
"sentAt": 1513616971891,
"delivered": true,
"deliveredStatusCode": 1,
"deliveredStatus": "delivered status",
"deliveredDate": "2017-12-18T17:09:31.891Z",
"deliveredAt": 1513616971891,
"read": true,
"readDate": "2017-12-18T17:09:31.891Z",
"readAt": 1513616971891,
"updatedDate": "2017-12-18T17:09:31.891Z",
"updatedAt": 1513616971891,
"type": "MESSAGE"
}
],
"clientInfo": {
"customerId": 42,
"subAccountId": 1291,
"userId": 1
}
}
Webhooks (ou callbacks) são retornos de chamada de HTTP definidos pelo usuário, que são acionados por eventos específicos. Sempre que ocorrer um evento de acionamento, a API da Wavy coletará os dados e imediatamente enviará uma notificação (solicitação HTTP) a URL escolhida pelo cliente atualizando o status das mensagens enviadas ou indicando quando você receber uma mensagem.
Quando o cliente enviar uma mensagem a você, API da Wavy Messaging enviará uma notificação de solicitação HTTP POST à URL do Webhook com os detalhes.
É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações (em até 200 ms ou de maneira assíncrona). Caso contrário, a API da Wavy Messaging considerará essa notificação com falha e tentará novamente após um atraso.
Importante: A URL onde você irá receber os Webhooks precisa ser configurado por nosso time de suporte.
O formato do retorno seguirá a seguinte descrição:
| Campo | Detalhes | Tipo |
|---|---|---|
| total | Número de callbacks retornados. | String |
| data | Dados retornados no Callback. | Data[] |
| clientInfo | Informações do cliente. | ClientInfo |
data:
| Campo | Detalhes | Tipo |
|---|---|---|
| id | id da mensagem. | String |
| correlationId | Caso tenha sido específicado um correlationId no envio da mensagem, ele irá aparecer aqui. | String |
| destination | Número do telefone que a mensagem foi enviada (incluindo código de pais). Exemplo: 5511900000000. | String |
| origin | Número da Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. | String |
| campaignId | Caso tenha sido específicado um campaignID no envio da mensagem, ele irá aparecer aqui. | String |
| campaignAlias | Caso tenha sido específicado um campaignAlias no envio da mensagem, ele irá aparecer aqui. | String |
| extraInfo | Informação extra enviada com a mensagem original. | String |
| sent | Indica se a mensagem foi enviada. | Boolean |
| sentStatusCode | Código de Status gerado pela Wavy Messaging WhatsApp API para a mensagem indicando o status de envio. | Number |
| sentStatus | Descrição do status de envio. | Boolean |
| sentDate | Data em que a mensagem foi enviada. Formato: yyyy-MM-dd’T'HH:mm:ssZ. | String |
| sentAt | Horário em que a mensagem foi enviada, usando Unix_time format | Number |
| delivered | Indica se a mensagem foi entregue no destino. | Boolean |
| deliveredStatusCode | Código de Status gerado pela Wavy Messaging WhatsApp API indicando se a mensagem foi entregue. | Number |
| deliveredStatus | Descrição do status de entrega. | String |
| deliveredDate | Data em que a mensagem foi entregue. Formato:: yyyy-MM-dd’T'HH:mm:ssZ | String |
| deliveredAt | Horário em que a mensagem foi entregue, usando Unix_time format | Number |
| read | Indica se a mensagem foi lida pelo destinatário. | Boolean |
| readDate | Data em que a mensagem foi lida. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| readAt | Horário em que a mensagem foi lida, usando Unix_time format | String |
| updatedDate | Data em que o status da mensagem foi atualizado. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| updatedAt | Horário em que o status da mensagem foi atualizado, usando Unix_time format | String |
| type | O tipo de entidade a que se refere este objeto de status. Atualmente, a única opção disponível é “mensagem”. | String |
clientInfo:
| Campo | Detalhes | Tipo |
|---|---|---|
| customerId | Código de identificação do cliente. | Number |
| subAccountId | Código de identificação da subconta. | Number |
| userId | Código de identificação do usuário. | Number |
Status
Descrição dos Status que podem ser enviados no callback:
| Status | Descrição | Equivalente ao WhatsApp para dispositivos móveis |
|---|---|---|
| SENT_SUCCESS | Mensagem recebida pelo servidor do WhatsApp | Uma marca de seleção |
| DELIVERED_SUCCESS | Mensagem entregue para o destinatário | Duas marcas de seleção |
| READ_SUCCESS | Mensagem lida pelo destinatário | Duas marcas de seleção azuis |
Outros Status
Esses são os códigos retornados nos campos sentStatusCode e deliveredStatusCode.
| Código de envio | Código de entrega | Status | Significado |
|---|---|---|---|
| 102 | CARRIER COMMUNICATION ERROR | Erro ao fazer upload de mídia para o WhatsApp | |
| 103 | REJECTED_BY_CARRIER | Ocorreu erro de comunicação com o WhatsApp. | |
| 2 | 101 | EXPIRED | Mensagem expirada. |
| 2 | 104 | NOT_DELIVERED | Possíveis Causas: Limite atingido - muitos envios de mensagens tentados; Ou falha ao enviar mensagem porque o número de telefone de destino é parte de um experimento; Ou a estrutura do template não existe; Ou falhou ao enviar mensagem pois o número de destino está fora da janela de atendimento de 24h para receber mensagens de forma livre; Ou houve erro de upload de mídia (erro desconhecido); Ou falha ao enviar mensagem porque sua conta é inelegível no Facebook Business Manager; Ou houve falha temporária de upload. Tente novamente mais tarde. |
| 2 | 105 | WA_MO_MEDIA_UNRETRYABLE_EXCEPTION | |
| 202 | EXPIREDINVALID_DESTINATION_NUMBER | Contato de WhatsApp inválido. | |
| 204 | DESTINATION_BLOCKED_BY_OPTOUT | Destino bloqueado por Opt-Out. | |
| 207 | INVALID_MESSAGE_TEXT | Valor de parâmetro inválido. | |
| 209 | INVALID_CONTENT | Tipo de mensagem UNKNOWN inválido. | |
| 210 | INVALID_SESSION | Sessão ou janela de atendimento não está aberta e nenhum Template de fallback está configurado. | |
| 301 | INTERNAL_ERROR | Não foi possível verificar o contato na API do WhatsApp. | |
Erros
| HTTP Code | Description |
|---|---|
| 2xx | Success |
| 200 | Success (OK) |
| 201 | Successfully created (For POST requests) |
| 302 | Found |
| 4xx | Client Errors |
| 400 | Request was invalid |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not found |
| 405 | Method not allowed |
| 412 | Precondition failed |
| 429 | Too many requests |
| 5xx | Server Errors |
| 500 | Internal server error |
| 504 | Timeout |
Mensagens (MO)
Exemplo de mensagem de texto:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"type": "TEXT",
"messageText": "Olá, essa é uma mensagem do usuário."
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de mensagem com resposta de botão:
{
"total":1,
"data":[
{
"id":"ce425ffe-bc62-421f-9261-e6819a5eab43",
"source":"5511900000000",
"origin":"5511900000000",
"userProfile":{
"name":"username",
"whatsAppId":"5511900000000"
},
"correlationId":"...",
"messageId":"aae959ca-5944-405a-809a-75ff142bc234",
"message":{
"type":"BUTTON",
"messageText":"Sim",
"payload":"sim"
},
"receivedAt":1513616971473,
"receivedDate":"2020-07-22T14:24:41Z",
"session":{
"id":"06deff90-cc27-11ea-b94f-0050569e62ca",
"createdAt":1513616971473
}
}
],
"clientInfo":{
"customerId":10,
"subAccountId":0,
"userId":101010
}
}
Exemplo de mensagem de midia
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"type": "IMAGE",
"mediaUrl": "https://...",
"mimeType": "image/jpg",
"caption": "..."
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de mensagem de localização:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"location": {
"geoPoint": "-22.894180,-47.047960",
"name": "Wavy",
"address": "Av. Cel. Silva Telles"
}
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de mensagem de contato:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "nome do usuário"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"message": {
"contacts":[
{
"addresses":[
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"1 Hacker Way",
"type":"HOME",
"zip":"94025"
},
{
"city":"Menlo Park",
"country":"United States",
"country_code":"us",
"state":"CA",
"street":"200 Jefferson Dr",
"type":"WORK",
"zip":"94025"
}
],
"birthday":"2012-08-18",
"emails":[
{
"email":"test@fb.com",
"type":"WORK"
},
{
"email":"test@whatsapp.com",
"type":"WORK"
}
],
"name":{
"first_name":"John",
"formatted_name":"John Smith",
"last_name":"Smith"
},
"org":{
"company":"WhatsApp",
"department":"Design",
"title":"Manager"
},
"phones":[
{
"phone":"+1 (940) 555-1234",
"type":"HOME"
},
{
"phone":"+1 (650) 555-1234",
"type":"WORK",
"wa_id":"16505551234"
}
],
"urls":[
{
"url":"https://www.fb.com",
"type":"WORK"
}
]
}
]
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Exemplo de Extra Info(SegmentationList):
{
"segmentation_list":[
{
"id":26,
"customerId":42,
"subAccountId":0,
"name":"Wavy WhatsApp Segmentation List",
"active":true
},
{
"id":27,
"customerId":43,
"subAccountId":0,
"name":"Wavy WhatsApp Segmentation List 2",
"active":true
}
]
}
Exemplo de mensagem de texto com referral:
{
"total": 1,
"data": [
{
"id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
"source": "5519900000000",
"origin": "5519900000000",
"userProfile": {
"name": "name of the user"
},
"campaignId": 100,
"correlationId": "...",
"campaignAlias": "...",
"flowId": "....",
"extraInfo": "...",
"referral": {
"headLine": "...",
"body": "...",
"sourceType": "...",
"sourceId": "...",
"sourceUrl": "...",
"mediaType": "...",
"mediaUrl": "..."
},
"mtSentAt": 1513616971473,
"message": {
"type": "TEXT",
"messageText": "Hi, this is a message from the user"
},
"receivedAt": 1513616971473,
"receivedDate": "2017-12-18T17:09:31.473Z"
}
]
}
Quando o cliente enviar uma mensagem para você, a API da Wavy Messaging enviará uma notificação de solicitação HTTP POST à URL do Webhook com os detalhes. É importante que seu Webhook retorne uma resposta HTTPS 200 OK às notificações (em até 200 ms ou de maneira assíncrona). Caso contrário, a API da Wavy Messaging considerará essa notificação com falha e tentará novamente após um atraso.
Importante: A URL onde você irá receber os Webhooks precisa ser configurado por nosso time de suporte.
O formato do retorno seguirá a seguinte descrição:
| Campo | Detalhes | Tipo |
|---|---|---|
| total | Números de callbacks para a ligação. | String |
| data | Lista de mensagens Mobile Originated (MO). | Data[] |
| Campo | Detalhes | Tipo |
|---|---|---|
| id | Última identificação da mensagem | String |
| source | Número de telefone do remetente | String |
| origin | Número de telefone que identifica a Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. | String |
| userProfile | Perfil do usuario que enviou a mensagem | UserProfile |
| correlationId | Um ID unico definido por voce para comparar com o status da mensagem (Callback and DLR). Este parametro é opcional, e voce pode usar o ID gerado pelo Wavy Messaging para fazer a comparação. | String |
| campaignId | campaignID definido anteriormente. | String |
| campaignAlias | Campaign alias definido anteriormente. | String |
| message | Mensagem MO. | mensagem |
| receivedAt | Data em que a mensagem foi recebida. Format: yyyy-MM-dd’T'HH:mm:ssZ | String |
| receivedDate | Data em que a mensagem foi recebida, usando Unix_time format | String |
| extraInfo | Informação extra relacionada com a mensagem. Formato: Json | String |
| referral | Caso a mensagem tenha se iniciado por um click em alguma propaganda, o campo contém a informação do anúncio/publicação. Esse campo é opcional (pode ser nulo). | Referral |
| mtSentAt | O timestamp de data/hora em que o último MT foi enviada a este destinatário. | Long |
| session | Informação da sessão. | Session |
message:
| Campo | Detalhes | Tipo |
|---|---|---|
| type | Tipo de mensagem enviada pelo usuário final: TEXT - BUTTON - IMAGE - AUDIO - DOCUMENT | String |
| messageText | A mensagem de texto (MO) enviada pelo usuário final. | String |
| waGroupId | Grupo ao qual a mensagem foi enviada. | String |
| mediaUrl | Url para download da midia enviada pelo usuário final. | String |
| mimeType | Mime type do arquivo enviado pelo usuário final. | String |
| caption | Media label enviada pelo usuário final. | String |
| location | Localidade enviada pelo usuário final. | Location |
| contacts | Contatos enviados pelo usuário final. | Contact[] |
referral:
Todos os campos desse objeto são opcionais (podem ser nulos).
| Campo | Detalhes | Tipo |
|---|---|---|
| headLine | Título do ad que gerou a mensagem. | String |
| body | Corpo do ad que gerou a mensagem. | String |
| sourceType | Tipo da propaganda que o usuario clicou. Valores podem ser “ad”, “post” ou “unknown”. | String |
| sourceId | Identificador da propaganda no Facebook. | String |
| sourceUrl | Url da propaganda. Leva para a propaganda que o usuario clicou. | String |
| mediaType | Tipo mídia presente na propaganda. Pode ser “image” ou “video”. | String |
| mediaUrl | Url da mídia presente na propaganda. | String |
Session
| Field | Details | Type |
|---|---|---|
| sessionId | Id da sessão para este usuário. | String |
| createdAt | Timestamp de criação da sessão | Long |
UserProfile:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| name | Não | Nome de perfil do usuário | String |
Location:
| Campo | Detalhes | Tipo |
|---|---|---|
| name | Nome do local. | String |
| address | Endereço do local. | String |
| geoPoint | Geopoint enviado pelo usuário final. Formato: “latitude,longitude” | String |
Contact:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| addresses | Não | Endereço(s) completo(s) do contato. | Address[] |
| birthday | Não | Data de aniversário com formato YYYY-MM-DD. | String |
| emails | Não | Endereço(s) de e-mail de contato. | Email[] |
| name | Não | Nome completo do contato. | Name |
| org | Não | Informações da organização do contato. | Org |
| phones | Não | Número(s) de telefone do contato. | Phone[] |
| urls | Não | URL(s) do contato. | Url[] |
Address:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| street | Não | Nome e número da rua. | String |
| city | Não | Nome da cidade. | String |
| state | Não | Sigla do Estado. | String |
| zip | Não | CEP. | String |
| country | Não | Nome completo do país. | String |
| country_code | Não | Abreviação de país (Duas letras). | String |
| type | Não | Valores Padrões: HOME, WORK. | String |
Email:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| Não | Endereço de e-mail. | String | |
| type | Não | Valores Padrões: HOME, WORK. | String |
Name:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| first_name | Não | Primeiro nome. | String |
| last_name | Não | Último nome. | String |
| middle_name | Não | Nome do meio. | String |
| name_suffix | Não | Sufixo do nome. | String |
| name_prefix | Não | Prefixo do nome. | String |
| formatted_name | Não | Nome completo como normalmente aparece. | String |
Org:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| company | Não | Nome da organização do contato. | String |
| department | Não | Nome do departamento do contato. | String |
| title | Não | Título corporativo do contato. | String |
Phone:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| phone | Não | Número de telefone formatado. | String |
| type | Não | Valores padrões: CELL, MAIN, IPHONE, HOME, WORK. | String |
| wa_id | Não | Identficador WhatsApp. | String |
Url:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| url | Não | URL do contato. | String |
| type | Não | Valores padrões: HOME, WORK. | String |
extraInfo (Controle de Fluxo de MO- Listas de Segmentação)
A mensagem terá uma lista de listas de segmentação no campo de extraInfo. Nossos parceiros a utilizam para direcionar as mensagens para certos fluxos. O nome da chave é segmentation_lists e ela contém uma lista de SegmentationList.
| Campo | Detalhes | Tipo |
|---|---|---|
| id | Identificador da lista de segmentação | Integer |
| customerId | Identificador do cliente | Integer |
| subAccountId | Identificador da subconta | Integer |
| name | Nome da lista de segmentação | String |
| active | Status da lista de segmentação | Boolean |
API SFTP WhatsApp
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) |
Mensagem Template via SFTP
Template com mídia:
2020-01-21;16:00;16:00;TEMPLATE;chatclub_welcome;whatsapp:hsm:ecommerce:movile;pt_BR;DETERMINISTIC;nome|empresa
IMAGE;URL;https://upload.wikimedia.org/wikipedia/en/d/d2/Imagem_logo.png;PNG
phone;nome;empresa
5519981560597;Nome1;Wavy
| 1ª Linha |
|---|
| Data de envio (para casos de agendamento) |
| Hora inicial de envio (para casos de agendamento) |
| Hora final de envio (para casos de agendamento) |
| Tipo de mensagem deve ser: TEMPLATE |
| Nome (elementName) do Template |
| Namespace (namespace) do Template |
| Idioma (languageCode) do Template |
| Determinístico ou Fallback do idioma do Template (languagePolicy) |
| nome dos parâmetros do Template |
Observações para primeira linha:
1 - Os nomes dos parâmetros do Template devem coincidir com os nomes das colunas ou serão considerados como valores constantes
2 - As informações que não forem ser utilizadas podem ser deixadas em branco, porém devem manter o ponto e vírgula como separação. Exemplo de um caso que não utilizamos agendamento (os campos iniciais ficam entre ponto e vírgula e sem informação dentro): ; ; ; TEMPLATE;chatclub_welcome;whatsapp:hsm:ecommerce:movile;pt_BR;DETERMINISTIC;nome|empresa
3 - Por default (padrão) a languagePolicy será Determinístico.
4 - Os nomes dos parâmetros do Template devem ser separados por “ | ” e não por “ ; ”
| 2ª Linha | Exemplos |
|---|---|
| Tipo do Header suportado pelo template | IMAGE, AUDIO, VIDEO ou DOCUMENT |
| Tipo da fonte da mídia | URL ou PATH (diretório da mídia no servidor FTP) |
| Mídia | Url ou diretório do servidor FTP |
| Tipo da mídia | JPEG, PNG, JPG, PDF, DOC, MP4, MP3 |
Observações para segunda linha:
1 - O tipo de mídia deve ser um tipo aceito pelo WhatsApp
| Mídia | Content-Types suportados |
|---|---|
| documento | qualquer MIME-type válido |
| imagem | image/jpeg, image/png |
| audio | audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus |
| video | video/mp4, video/3gpp. Observação: Apenas H.264 video codec e AAC audio codec é suportado. |
| 3ª Linha |
|---|
| Nome das colunas |
| 4ª e demais linhas: |
|---|
| Destinatário e valores dos parâmetros do Template |
Templates customizados por destinatário:
Para envios customizados, como diferentes mídias por destinatário, entre em contato com o nosso time de suporte técnico para realizar a configuração e obter mais detalhes para o envio.
Consulta de sessões abertas via API
Exemplo de resposta:
{
"file_url": "https://chatclub-cdn.wavy.global/2019/02/13/633e33fc-3a3f-4ca5-a8b0-4b747fb67137/5bd46e2b-5990-4681-9b29-98ab6598960e"
}
Requisição
Para consultar as sessões abertas através de nossa API, é preciso fazer uma requisição do tipo GET para o endereço:
GET http://api-messaging.wavy.global/v1/session?customerId={customerId}&subAccountId={subAccountId}
O parâmetro customerId é obrigatório, enquanto o subAccountId é opcional.
Atenção: As chaves ‘{’ and ‘}’ também devem ser substituídas. Por exemplo, “={customerId}” se torna “=42”.
Ainda é necessário passar os seguintes headers:
| Header | Valor |
|---|---|
| Content-Type | application/json |
| authenticationToken | Token do Messaging1 |
| userName | Nome de usuário do Messaging1 |
O usuário e o token podem ser obtidos através da nossa plataforma do Messaging: https://messaging.wavy.global/
Resposta
Em caso de sucesso, se existirem sessões abertas para o customerId e o subAccountId especificados, a requisição retornará um JSON com o atributo:
| Atributo | Valor |
|---|---|
| file_url | Link para baixar um arquivo do tipo csv contendo os campos “source” e “session_created_at” de todos os destinations encontrados |
Caso não existam dados associados ao customerId e o subAccountId, o arquivo retornado estará vazio, apenas com o cabeçalho.
API de Campanhas
Esta documentação fornece as infomações necessárias para a integração com a plataforma Wavy Messaging para realizar o gerenciamento de campanhas. A API possui integração REST, utilizando o protocolo HTTP com TLS, suportando o método POST com os parâmetros enviados em formato JSON.
Autenticação
Para utilizar com sucesso a nossa API, é preciso apresentar um username válido (e-mail), associado com um token de autenticação. É necessário adicionar os seguintes headers à requisição:
| Campo | Detalhes | Data Type |
|---|---|---|
| userName | E-mail válido para autenticação no Wavy Messaging. | String |
| authenticationToken | Token de autenticação gerado por nossa plataforma. Encontre aqui ou consulte nosso suporte. | String |
Detalhes de conexão
| Hostname | apigw.wavy.global |
| Porta | 443 (https) |
| Protocolo | HTTPS (TLS encryption) |
| Autenticação | username + token |
| Encoding | UTF-8 |
Listar campanhas
Exemplo de listagem de campanhas
curl -X GET \
'https://apigw.wavy.global/api/v1/campaigns?name=MyCampaign&page=1&page_size=10' \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>'
Resposta
HEADERS:
page-number: 1
per-page: 10
total: 2
total-pages: 1
{
"status": {
"error": false
},
"campaigns": [
{
"name": "My first campaign",
"id": 1,
"alias": "first"
},
{
"name": "My second campaign",
"id": 2,
"alias": "second"
}
]
}
Listagem das campanhas já cadastradas na plataforma. É possível paginar os resultados ou filtrar pelo nome da campanha.
GET https://apigw.wavy.global/api/v1/campaigns
Parâmetros da QueryString
* Campo obrigatório
| Campo | Detalhes | Tipo |
|---|---|---|
| name | Nome de uma campanha como filtro para a listagem | String |
| page | Página a ser listada | Integer |
| page_size | Total de campanhas por página | Integer |
Buscar uma campanha
Exemplo de busca de uma campanha
curl -X GET \
https://apigw.wavy.global/api/v1/campaigns/1234 \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>'
Resposta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Busca os dados de uma campanha pelo ID de cadastro
GET https://apigw.wavy.global/api/v1/campaign/{id}
Criar campanha
Exemplo de criação de uma campanha:
curl -X POST \
https://apigw.wavy.global/api/v1/campaigns \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>' \
-d '{
"campaign" : {
"name": "My Campaign",
"alias": "mycampaign"
}
}'
Resposta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Criação de uma nova campanha com nome e alias. O alias da campanha deve ser um nome simple para facilitar o uso com a API. Recomenda-se que seja curto e não utilize caracteres especiais.
POST https://apigw.wavy.global/api/v1/campaigns
Parâmetros do JSON
* Campo obrigatório
| Campo | Detalhes | Tipo |
|---|---|---|
| name* | Nome da campanha | String |
| alias | Identificador da campanha para utilização na API | String |
Alterar campanha
Exemplo de alteração de uma campanha:
curl -X PUT \
https://apigw.wavy.global/api/v1/campaigns/1234 \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>' \
-d '{
"campaign" : {
"name": "My Campaign",
"alias": "mycampaign"
}
}'
Resposta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Alteração de uma campanha podendo modificar o nome e/ou o alias.
PUT https://apigw.wavy.global/api/v1/campaigns/{id}
Parâmetros do JSON
* Campo obrigatório
| Campo | Detalhes | Tipo |
|---|---|---|
| name* | Nome da campanha | String |
| alias | Identificador da campanha para utilização na API | String |
Excluir campanha
Exemplo de exclusão de uma campanha:
curl -X DELETE \
https://apigw.wavy.global/api/v1/campaigns/1234 \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>'
Resposta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Exclusão de uma campanha pelo ID.
DELETE https://apigw.wavy.global/api/v1/campaigns/{id}
Suporte
| Abertura de chamados | Para solicitar suporte acesse nosso Service Center |