Introduccion
Sean bienvenidos a nuestra documentación para desarrolladores. Aquí usted encontrara todo lo que necesita para integrar su empresa a nuestra plataforma de mensajes.
Es posible hacer la integración de las siguientes formas:
| API HTTPS | Permite el envió y recibimiento de mensajes y status a través del protocolo HTTPS utilizando los métodos GET o POST |
| API SMPP | Protocolo especifico para intercambio de mensajes SMS, permite mantener una conexión activa constante con nuestro servidor SMPP. Es indicado para clientes con trafico superior a 5 millones de mensajes por mes. |
| API SFTP | Protocolo utilizado para transferencia de archivos, es indicado para envíos de mensajes en masa (Lote). Los archivos son transferidos por el cliente para nuestros servidores y son inmediatamente procesados. |
| Websphere MQ | Utilizado para transferencia de mensajes entre servidores Websphere MQ, es indicado para clientes con trafico superior a 30 millones de mensajes por mes. Principalmente para bancos financieros donde el cliente ya posee este sistema funcionando para mensajes internos. Esta opción de integración posee un valor de configuración y mantenimiento de ambiente fijado en R$50.000,00 y R$20.000,00 respectivamente. |
SMS API
Términos importantes
| MT | Mobile Terminated | Es un termino utilizado para mensajes que poseen el usuario (Aparato) como destino. O sea, mensajes que fueron originados por su empresa con destino al usuario (Aparato). |
| Response | Respuesta sincronica de Wavy | Es una respuesta inmediata de una solicitud hecha en nuestra API, donde informamos si el mensaje fue aceptado o no por nuestra plataforma |
| Callback | Sent status o Estatus de envió | Es el primer status de envió que retornamos, en el informamos si fue posible, o no, hacer la entrega del mensaje. para la operadora. |
| DR ou DLR | Delivery Receipt | Es el segundo status de envió que retornamos, donde informamos si fue posible, o no, hacer la entrega para el aparato. Las operadoras envían para Wavy esta información y nosotros la entregamos al cliente. El tiempo de entrega es variable, por ejemplo si el aparato estaba apagado en el momento del envió y el usuario lo encendió 2 horas después este status DLR sera entregado al cliente con 2 horas de atraso. Obs1: Esta confirmación de entrega en el aparato, existirá solamente para casos en que el mensaje fue entregado con éxito en la operadora. O sea, el primer status (Callback) fue de exito. Obs2: Es muy importante resaltar que infelizmente las operadoras OI y Sercomtel no poseen esta funcionalidad, o sea, no nos retornan la información de entrega en el aparato. Los envíos realizados para números de estas operadoras tendrán solamente la informacion de entrega en la operadora (callback) |
| MO | Mobile Originated | Es el termino utilizado para mensajes que poseen su empresa como destino. O sea, mensajes que fueron originados por el usuario (Aparato). Y utilizado por ejemplo en flujos de preguntas y respuestas vía SMS, cuando es necesario una confirmación por parte del usuario. |
| LA | Short Code | Numero corto de 5 o 6 digitos, utilizados para envio y recibimiento de mensajes SMS. Son designados por las operadoras para integradores homologados (Wavy), y poseen reglas anti-fraude y anti-spam. |
Flujo de Mensajes
Flujo simplificado - MT, Callback, DLR, e MO.
API HTTPS
Esta API permite que usted automatice las solicitudes de envíos de mensajes únicas o en lotes, y la recuperación de los estatus de envíos a travez de consultas. Ella utiliza el protocolo HTTP con TLS y acepta los métodos GET con parámetros query string o POST con parámetros en JSON.
Autenticacion
Para efectuar envíos y consultas en nuestra API es necesaria una autenticacion por medio de usuario o e-mail, en conjunto con un token.
| Campo | Detalles | Data Type |
|---|---|---|
| UserName | Su usuário o email | String |
| AuthenticationToken | Su token de autenticacion. Verifique aqui y lea las siguientes descripciones de usuarios. | String |
| Tipo | Detalles |
|---|---|
| Administrador | Usuario administrador de su empresa, es utilizado para crear/editar/desactivar sub cuentas y otros usuarios y visualizar informes de toda la empresa. Este usuario no hace envíos de mensajes ni por el portal ni vía integración API. |
| Usuario | Usuario utilizado para envió de mensajes via API y portal, puede visualizar informes especificos de su sub cuenta. Un usuario es siempre relacionado a una única sub cuenta. Una sub cuenta puede contener multipes usuarios. Cada sub cuenta es un centro de costo en nuestra plataforma, los mensajes son discriminados en informes y financieramente por sub cuenta y no por usuario. |
Detalles de conexión
| Hostname | api-messaging.wavy.global |
| APIs | Envíos individuales /v1/send-sms Envíos en lote /v1/send-bulk-sms |
| Puerta | 443 (https) |
| Protocolo | HTTPS (encriptacion TLS) |
| Autenticacion | username + token |
| Portal | messaging.wavy.global |
Codificación (encoding)
El estándar de codificación utilizado es UTF-8, todo el contenido de los mensajes deben seguir ese estándar.
Es posible escapar los caracteres caso desee codificar utilizando el formato HTTP
A seguir algunos ejemplos de codificación
“messageText”:“La combinación fue perfecta :)”
O usted puede escapar los caracteres en el caso que quiera:
“messageText”:“La combina\u00e7\u00e3o fue perfecta :)”
Envió de mensajes (MT)
Envio por método GET - Individual
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"}'
Mod curl:
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;
}
}
Al hacer el envió usted recibirá un JSON informando el id que fue generado para este mensaje (Response o Respuesta sincrona de Wavy):
[
{
"id":"9cb87d36-79af-11e5-89f3-1b0591cdf807",
"correlationId":"myId"
}
]
Vía método GET, es posible realizar el envió de un mensaje pasando todos los parámetros como query string
URL para envíos unitarios via GET
GET https://api-messaging.wavy.global/v1/send-sms?destination=..
Vía método POST, es posible realizar el envió de un mensaje pasando todos los parámetros como body
URL para envíos unitarios via POST
POST https://api-messaging.wavy.global/v1/send-sms - Content-Type: application/json
Parametros
* Campo obligatorio
| Campo | Detalles | Tipo |
|---|---|---|
| destination* | Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000 | String |
| messageText* | Texto del mensaje que sera enviado (max 1280 chars). | String |
| correlationId | Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Wavy para coincidencia (max 64 chars). | String |
| extraInfo | Cualquier información extra que usted desee adicionar al mensaje (max 255 chars). | String |
| timeWindow | Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59, este parámetro se debe definir en la raíz del objeto JSON | Integer[] |
| expiresAt | Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| expiresInMinutes | El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Wavy. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| expiresDate | El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | String |
| scheduledAt | El mensaje no sera enviado después de esta fecha. ¡IMPORTANTE! Es posible realizar una agenda solo en un período superior a 30 minutos, un proceso por el cual fluxo diferenciado do envio sem agendamento. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| delayedInMinutes | Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| scheduledDate | El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | String |
| timeZone | Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC | String |
| campaignAlias | Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña, este parámetro se debe definir en la raíz del objeto JSON | String |
| flashSMS | Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true. | Boolean |
| flowId | Identificador del flujo del bot. El mensaje de texto provendrá del flujo | String |
| subAccount | Referencia de subcuenta. Solo puede ser utilizado por Administradores. | String |
| params | Mapa de marcadores de posición que serán reemplazados en el mensaje. Si uno o más parámetros son incorrectos, el mensaje se marcará como no válido, pero el envío no se cancelará. Es necesario enviar el flowId para utilizar los parámetros | Map |
Envio por método POST - Individual o e 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;
}
}
Al hacer el envió, retornara un objeto JSON con un UUID del lote e de los mensajes individuales :
{
"id": "ce528d70-013b-11e7-98f2-e27c463c8809",
"messages": [
{
"id": "ce528d71-013b-11e7-98f2-e27c463c8809"
},
{
"id": "ce528d72-013b-11e7-98f2-e27c463c8809"
}
]
}
Permite el envió de mensajes en lote o individuales pasando los parámetros de un objeto JSON
Solicitud HTTP Method POST
Ejemplo de JSON para envio em Lote:
Exemplo 1:
{
"messages":[
{
"destination":"5519900001111",
"messageText":"First message"
},
{
"destination":"5519900002222"
},
{
"destination":"5519900003333"
}
],
"defaultValues":{
"messageText":"Default message"
}
}
Exemplo 2:
{
"messages":[
{
"destination":"5519900001111",
"messageText":"First message"
},
{
"destination":"5519900002222"
}
],
"timeZone":"America/Sao_Paulo",
"scheduledDate": "2017-01-28T02:30:43",
"timeWindow": [12, 15, 20],
"defaultValues":{
"messageText":"Default message"
}
}
Exemplo 3:
`
{
"messages":[
{
"destination":"5519900001111",
},
{
"destination":"5519900002222"
}
],
"defaultValues":{
"messageText":"Default message",
"flashSMS":"true"
}
}
Ejemplo 4, com flowId y params:
{
"messages":[
{
"destination":"5519900001111",
"params": {
"param1": "other_value1",
"param2": "other_value2"
}
},
{
"destination":"5519900002222"
}
],
"defaultValues":{
"params": {
"param1": "value1",
"param2": "value2"
}
},
"flowId": "14f8142d-e731-4971-8220-5a76a12c413f"
}
Observe que en los ejemplos de arriba, algunos campos “destination” no tienen un “messageText” atribuido directamente para ellos, en este caso, el texto del mensaje sera el “messageText” dentro de “defaultValues”. Esa función es útil cuando es necesario el envió del mismo mensaje para varios números diferentes.
POST https://api-messaging.wavy.global/v1/send-bulk-sms Content-Type: application/json
El cuerpo de la solicitud necesita contener el objeto JSON con las informaciones conforme los campos abajo:
* Campo obligatorio
| Campo | Detalles | Tipo |
|---|---|---|
| destination* | Teléfono para el cual sera enviado el mensaje (incluido código de país). Ejemplo: 5511900000000 | String |
| messageText* | Texto del mensaje que sera enviado (max 1280 chars). | String |
| correlationId | Un ID único definido por usted para coincidencia con los estatus de envió (Callback y DLR). Este parámetro es opcional y usted puede utilizar el ID generado por Wavy para coincidencia (max 64 chars). | String |
| extraInfo | Cualquier información extra que usted desee adicionar al mensaje (max 255 chars). | String |
| timeWindow | Mensajes serán enviados apenas en horarios específicos. Por ejemplo, si usted configura la ventana [11, 12, 18], los mensajes seran enviados entre 11:00 y 11:59, 12:00 y 12:59, 18:00 y 18:59 | Integer[] |
| expiresAt | Los mensajes no serán enviados después de esta fecha. El formato utilizado es Unix time . Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| expiresInMinutes | El mensaje sera expirado después del tiempo informado en este campo. El tiempo pasa a ser contabilizado en el momento que el mensaje es recibido por Wavy. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| expiresDate | El mensaje no sera enviado después de esta fecha. El campo acepta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | String |
| scheduledAt | El mensaje no sera enviado después de esta fecha. El formato utilizado es Unix time. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| delayedInMinutes | Minutos después que la solicitud es realizada el mensaje sea enviado. Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | Long |
| scheduledDate | El mensaje no sera enviado antes de este fecha. El campo soporta el siguiente formato yyyy-MM-dd’T'HH:mm:ss. Obs: Los campos expiresAt, expiresInMinutes y expiresDate son mutuamente exclusivos (Use solamente uno de ellos) | String |
| timeZone | Especifica el timezone que sera utilizado directamente en los campos: expiresDate, scheduledDate y timeWindow (que sera modificado en caso que sean utilizados timezones dinámicos como los horarios de verano). Si el timezone no estuviese presente en la solicitud el sistema verificara el timezone del usuario - si estuviera presente - o el timezone del país del usuario en el ultimo caso. Si ninguna de las opciones estuvieran presentes, el sistema utilizara el horario UTC | String |
| campaignAlias | Identificación de campaña creada previamente. Clique aqui para registar una nueva campaña | String |
| flashSMS | Flash SMS,use esta opción para enviar un mensaje pop-up al teléfono del usuario. Para enviar un mensaje Flash pase el parámetro true. | Boolean |
| flowId | Identificador del flujo del bot. El mensaje de texto provendrá del flujo | String |
| subAccount | Referencia de subcuenta. Solo puede ser utilizado por Administradores. | String |
| params | Mapa de marcadores de posición que serán reemplazados en el mensaje. Si uno o más parámetros son incorrectos, el mensaje se marcará como no válido, pero el envío no se cancelará. Es necesario enviar el flowId para utilizar los parámetros | Map |
Respuestas de mensajes en lote
La respuesta de envíos en lote contendrá un archivo JSON con las informaciones necesarias para su rastreamiento, sera generado un id para todo el lote y un id y correlationid individual para cada mensaje:
| Campo | Detalles | Tipo |
|---|---|---|
| id | UUID generado para este lote | String |
| messages | Este campo es un array con las respuestas de los mensajes individuales del lote, contiene el id y el correlationid de cada mensaje enviado. | SingleSMSResponse[] |
Respuesta del código de estado HTTP
Código de estado de respuesta HTTP común:
| Grupo | Descripción |
|---|---|
| 2xx | El éxito |
| 4xx | Error del cliente |
| 5xx | Error del servidor |
| Código | Descripción |
|---|---|
| 200 | El éxito |
| 400 | Mal pedido |
| 401 | No autorizado |
| 403 | Prohibido |
| 404 | No encontrado |
| 500 | Error interno del servidor |
| 503 | Servicio no disponible |
| 504 | Tiempo de espera |
Estatus de envio (Callback e DLR)
Existen dos maneras de obtener los estatus de envíos de los mensajes, son ellas:
- Webhook - Recibir los estatus en un webservice de su empresa (recomendado)
Cuando entregamos el mensaje en la operadora, o en el momento que la operadora nos informa que se entrego el mensaje en el aparato, la información es pasada instantáneamente para usted.
- API de consulta - Hacer solicitudes de consulta en nuestra API sms-status.
Los estatus quedan disponibles por 3 días, e pueden ser consultados por el UUID que Wavy retorno al recibir el mensaje de su empresa, o por el ID que su empresa paso al entregar el mensaje para Wavy.
La desventaja de esta opción de consulta al revés de webhook, es que usted hará solicitudes de consulta de un ID que puede todavía no haber sido entregado en la operadora o en el aparato, en este caso, una serie de solicitudes innecesarias serán realizadas. Por ejemplo, si un usuario estaba con el aparato apagado cuando envio un mensaje para el y lo encendió dos horas después, usted consultara este ID innumerables veces por dos horas. En el caso de la utilización de webhook, esta información seria enviada para usted en el momento que el mensaje fuese entregado en el aparato, sin solicitudes vaciás.
Estatus via webhook (entrega en su webservice)
Para configurar el envió de los Callbacks y DRs (dudas sobre los términos consulte la pestaña Términos Importantes) primeramente es necesario loguear en Wavy messaging las configuraciones de la API, en el formulario de configuración usted podrá proveer las URLs para donde serán enviados los estatus de envió (Callbacks) y los estatus de confirmación de entrega en el aparato (DRs)
Después de la inclusión de su webhook en el portal arriba, las configuraciones serán replicadas para nuestra plataforma en hasta 10 minutos, y llamaremos su URL cuando las siguientes acciones ocurran:
| Accion | Estatus de retorno enviado |
|---|---|
| Después que un mensaje fue entregado o no, en la operadora | API de estatus de envió (callback) |
| Cuando un mensaje fue entregado o no, en el aparato del cliente | API de Delivery Report (DRs) |
Ejemplo JSON Estatus de Envio (callback - entrega en la operadora)
POST https://example.com/callback/
Content-Type: application/json
{
"id":"f9c100ff-aed0-4456-898c-e57d754c439c",
"correlationId":"client-id",
"carrierId":1,
"carrierName":"VIVO",
"destination":"5511900009999",
"sentStatusCode":2,
"sentStatus":"SENT_SUCCESS",
"sentAt":1266660300000,
"sentDate":"2010-02-20T10:05:00Z",
"campaignId":"64",
"extraInfo":"",
}
Campos JSON respuesta Callbacks (sent status)
| Campo | Descripción |
|---|---|
| id | UUID generado del mensaje |
| correlationId | Su identificación de este mensaje |
| carrierId | Identificador de la operadora |
| carrierName | Nombre de la operadora |
| destination | Número de telefone da mensagem enviada |
| sentStatusCode | Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones. |
| sentStatus | descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones. |
| sentAt | Hora do envió, el formato utilizado es Unix_time. |
| sentDate | Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ |
| campaignId | Identificador de campaña en el caso que exista. |
| extraInfo | Cualquier información extra adicionada por el cliente en el envió del mensaje |
Campos JSON respuesta Delivery Reports (DRs)
| Campo | Descripción |
|---|---|
| id | UUID generado del mensaje |
| correlationId | Su identificación de este mensaje |
| carrierId | Identificador de la operadora |
| carrierName | Nombre de la operadora |
| destination | Número de telefone da mensagem enviada |
| sentStatusCode | Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones. |
| sentStatus | descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones. |
| sentAt | Hora do envió, el formato utilizado es Unix_time. |
| sentDate | Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ |
| deliveredStatusCode | Código de estatus generado por Wavy para un mensaje indicando el estatus de envió. Verifique en el código de estatus para mas informaciones |
| deliveredStatus | descripción de estatus de envió. Verifique en código de estatus para mas informaciones. |
| deliveredAt | Hora do envió, el formato utilizado es Unix_time. |
| deliveredDate | Fecha que el mensaje fue enviado. Formato: yyyy-MM-dd’T'HH:mm:ssZ |
| campaignId | Identificador de campaña en el caso que exista. |
| extraInfo | Cualquier información extra adicionada por el cliente en el envió del mensaje |
Consulta Estatus via solicitud HTTP
Para obtener una lista del estado aún no consultado, puede realizar una solicitud GET a la siguiente URL:
GET https://api-messaging.wavy.global/v1/sms/status/list
Observe que este endpoint solo devuelve los estados que aún no ha enviado.
Respuesta
Campos JSON de respuesta:
| Campo | Detalles | Tipo |
|---|---|---|
| id | UUID generado en la solicitud para el mensaje | String |
| correlationId | Mismo correlationId de la solicitud | String |
| carrierId | ID de la operadora, para mas informaciones consulte el código de error | Long |
| carrierName | Nombre da la operadora | String |
| destination | Número de telefono del mensaje enviado | String |
| sentStatusCode | sentStatusCode | Códigos de estatus generado por Wavy para mensajes indicando el estatus de envió. Verifique en codigos de status para mas informaciones. |
| sentStatus | Descripción de estatus de envió. Verifique en códigos de estatus para mas informaciones. | String |
| sentStatusAt | Cuando el mensaje fue enviado. Es un Epoch Date | Long |
| sentStatusDate | Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601) | String |
| deliveredStatusCode | Código de estatus indicando el estatus de envió. Verifique en el código de estatus para mas informaciones. | Long |
| deliveredStatus | Descripción de estatus de envió. Verifique en código de estatus para mas informaciones. | String |
| deliveredAt | Cuando el mensaje fue enviado. Es un Epoch Date | Long |
| deliveredDate | Cuando el mensaje fue enviado. Formato yyyy-MM-dd’T'HH:mm:ssZ. Formato de fecha con hora y zona horaria (ISO 8601) | String |
| campaignId | Identificador de campaña | Long |
| extraInfo | Cualquier información extra adicionada por el cliente en el envió del mensaje | String |
Ejemplo JSON Delivery Report (DR ou DLR - Entrega en el aparato del usuario)
{
"id":"8f5af680-973e-11e4-ad43-4ee58e9a13a6",
"correlationId":"myId",
"carrierId":5,
"carrierName":"TIM",
"destination":"5519900001111",
"sentStatusCode":2,
"sentStatus":"SENT_SUCCESS",
"sentStatusAt":1420732929252,
"sentStatusDate":"2015-01-08T16:02:09Z",
"deliveredStatusCode":4,
"deliveredStatus":"DELIVERED_SUCCESS",
"deliveredAt":1420732954000,
"deliveredDate":"2015-01-08T16:02:34Z",
"campaignId":1234
}
Respuesta del usuario (MO)
La API de MO permite la automatización del proceso de recuperación de respuestas enviadas por los clientes a los mensajes que usted le envió a ellos. Todas las solicitudes usan el método GET y las respuestas son enviadas en formato JSON
Es posible también la configuración para que los MOs sean encaminados conforme llegan, para una API del cliente. Esa es la forma mas eficiente ya que no es necesario realizar ninguna llamada, solo se tratan los envíos conforme van llegando. Para que esta configuración sea realizada es necesario abrir un ticket con nuestro equipo de soporte técnico a través de nuestro Service Center pasando la URL que recibirán los MOs.
Ejemplo JSON enviado a su API (método POST)
{
"id": "25950050-7362-11e6-be62-001b7843e7d4",
"subAccount": "iFoodMarketing",
"campaignAlias": "iFoodPromo",
"carrierId": 1,
"carrierName": "VIVO",
"source": "5516981562820",
"shortCode": "28128",
"messageText": "Eu quero pizza",
"receivedAt": 1473088405588,
"receivedDate": "2016-09-05T12:13:25Z",
"mt": {
"id": "8be584fd-2554-439b-9ba9-aab507278992",
"correlationId": "1876",
"username": "iFoodCS",
"email": "customer.support@ifood.com"
}
}
Cada solicitud realizada retornara los MOs de los últimos 5 días, hasta un limite de 1.000 MOs. Para las fechas anteriores o cantidades mayores por favor entrar en contacto con nuestro equipo de soporte a través del nuestro Service Center.
El comportamiento de Query List MO sera diferente para cada usuario autenticado debido al nivel de permisos de cada usuario.
| Perfil | Permisos |
|---|---|
| Regular | Cada solicitud realizada en la MO API solo retornara los MOs correspondientes a la subcuenta a la que el usuario pertenece. No es posible para un usuario regular recuperar los MOs de otras subcuentas. |
| Administrador | El comportamiento estándar para el usuario administrador es recuperar todos los MOs de todas las subcuentas. Si un admin desea recuperar los MOs de apenas una de las subcuentas es necesario especificar la subcuenta en el parámetro subAccount con el id de la subcuenta deseada. |
Fomato de respuesta estandar de MO
Ejemplo JSON de respuesta:
{
"total": 1,
"start": "2016-09-04T11:12:41Z",
"end": "2016-09-08T11:17:39.113Z",
"messages": [
{
"id": "25950050-7362-11e6-be62-001b7843e7d4",
"subAccount": "iFoodMarketing",
"campaignAlias": "iFoodPromo",
"carrierId": 1,
"carrierName": "VIVO",
"source": "5516981562820",
"shortCode": "28128",
"messageText": "Eu quero pizza",
"receivedAt": 1473088405588,
"receivedDate": "2016-09-05T12:13:25Z",
"mt": {
"id": "8be584fd-2554-439b-9ba9-aab507278992",
"correlationId": "1876",
"username": "iFoodCS",
"email": "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 las solicitudes de listado (list) como la funcion de busqueda (search) retornan un objeto JSON con los campos abajo:
| Campo | Detalles | Tipo |
|---|---|---|
| total | Numero total de MOs retornados por la solicitud | Integer |
| start | Limite minimo de la query | String |
| end | Limite máximo de la query | String |
| messages | Listado de los objetos | List |
Cada mensaje del campo messages posee la siguiente estructura:
| Campo | Detalles | Tipo |
|---|---|---|
| id | Id del mensaje | String |
| subAccount | subcuenta responsable por enviar el mensaje que genero la respuesta | String |
| carrierId | Id de la operadora | Integer |
| carrierName | Nombre de la operadora | String |
| source | Numero de telefono que envio el mensaje de respuesta | String |
| shortCode | O shortcode del mensaje que origino la respuesta y por el cual la respuesta fue enviada. | String |
| messageText | Texto del mensaje de respuesta. | String |
| receivedAt | hora de recebido | Long |
| receivedDate | Fecha y hora de recibimiento en formato UTC | String |
| campaignAlias | Alias da campaña que origino la respuesta | String |
| mt | MT original que genero la respuesta | MT |
MTs tienen la siguinte estructura
| Campo | Detalles | Tipo |
|---|---|---|
| id | Id del MT | String |
| correlationId | CorrelationID enviado en el MT | String |
| username | Username del usuário responsable por enviar el MT | String |
| Email del responsable por enviar el MT | String |
Solicitud listar MO (list)
El listado ira a retornar todos los MOs recibidos desde la ultima llamada de acuerdo con la respuesta estándar descripta encima. Una vez que esta llamada es realizada sera consumida y no retornara las llamadas siguientes.
Como un usuario regular, para recuperar todos los MOs de una subcuenta use:
GET https://api-messaging.wavy.global/v1/sms/receive/list
Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:
GET https://api-messaging.wavy.global/v1/sms/receive/list
Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:
GET https://api-messaging.wavy.global/v1/sms/receive/list?subAccount=referencia_subconta
Códigos de Estatus de Envió
Existen dos niveles de estatus, que son enviados independientemente.
1 - Primer estatus (sent_status - Estatus de envió = Callback)
Estatus de entrega en la operadora, este es el primer estatus que retornamos, y todas las operadoras poseen.
| Código | Mensaje | Significado |
|---|---|---|
| 2 | SENT_SUCCESS | Entregado en la operadora con éxito (Este es un estatus que debe ser considerado para efecto de cobro.) |
| 101 | EXPIRED | Expirado antes de ser entregado al aparato. |
| 102 | CARRIER_COMMUNICATION_ERROR | Error de comunicación con la operadora. |
| 103 | REJECTED_BY_CARRIER | Operadora rechazo el mensaje. |
| 202 | INVALID_DESTINATION_NUMBER | El numero de destino es invalido (No es un numero de celular valido). |
| 203 | BLACKLISTED | El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa. |
| 204 | DESTINATION_BLOCKED_BY_OPTOUT | El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing). |
| 205 | DESTINATION_MESSAGE_LIMIT_REACHED | El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras. |
| 207 | INVALID_MESSAGE_TEXT | El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas. |
| 301 | INTERNAL_ERROR | Ocurrio un error en la plataforma de Wavy. |
2 - Segundo estatus (delivered_status - Delivery Report Callback)
Estatus de entrega en el aparato, este es el segundo estatus que retornamos y solo existe para los casos en que el primer estatus de arriba fue de éxito, o sea, el mensaje fue entregado en la operadora con éxito. En este estatus informamos si el mensaje fue o no entregado en el aparato. Algunas operadoras no poseen este segundo nivel de estatus, para estas operadoras, lo máximo de información que existe es el primer estatus o sea, si la operadora acepto el mensaje o no.
| Código | Mensaje | Significado |
|---|---|---|
| 4 | DELIVERED_SUCCESS | Entregado en el aparato con éxito. |
| 104 | NOT_DELIVERED | La operadora acepto el mensaje, pero no consiguió entregarlo en el aparato. Posibles causas: Aparato apagado o fuera del área de servicio por tiempo determinado (normalmente 24 horas, pero para algunas operadoras, este tiempo de tentativa es de 8 horas). Número válido, pero inactivo (algunas operadoras retornan este tipo de error solamente en este segundo nivel de estatus). |
API SMPP
Todos los servicios provistos por el Wavy deben obligatoriamente ser encriptados, y el protocolo SMPP no posee encriptacion nativa. En este caso disponibilizamos dos alternativas para integración
Opción 1 - SMPP over TLS + IP whitelist (Opción recomendada)
Esta es la opción que recomendamos. En el caso que su sistema no tenga esta funcionalidad, clique AQUI para obtener ayuda en la configuracion de un proxy TLS.
Mas allá de la encriptacion que será realizada por TLS, el acceso será autorizado solamente para la IP publica de su servidor. (Aceptamos múltiples IPs e rangos) Esta información debe ser enviada para el Service Center.
En el caso que sea necesaria la liberación de salida de trafico en su firewall, recomendamos que sea liberado cualquier IP de destino en la puerta 2444. Si esto no es posible, se deberán incluir las siguientes reglas de liberación:
200.219.220.8:2444200.219.220.193:244445.236.179.18:244445.236.179.19:2444
Opcion 2 - SMPP over VPN
La encriptacion y la liberación de acceso sera realizada vía VPN.
En el caso que elija esta opción, configure las VPNs utilizando los siguientes peers y hosts con las propuestas de fase 1 y 2 que desea. Llene y envié el formulario de VPN de su empresa para nuestro 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 razones de alta disponibilidad y balanceamiento de carga, es obligatorio el establecimiento de las 2 VPNs definidas arriba.
Detalles de conexión
| Información | Detalles |
|---|---|
| Hostname / IP Address | smpp-messaging.wavy.global Al configurar su sistema SMPP, es obligatorio utilizar el dominio como destino, y no las IPs. Este dominio posee 4 proxys de entrada con round robin DNS y health check, y múltiples servidores backend. Basado en el volumen de mensajes que su empresa traficara, vamos a aumentar el numero de binds (conexiones) permitidas simultáneamente. |
| Puerta | 2444 (SMPP over TLS) o 2443 (VPN) |
| Version SMPP | 3.4 |
| Numero de binds | Mínimo 4. Establecer por lo menos 4 binds es mandatario para obtener alta-disponibilidad y balanceamiento de carga. |
| Codificación de los caracteres | GSM7 - Default (data_coding = 0) (GSM3.38 extended table is not supported by carriers.) LATIN1 (data_coding = 1) UCS2 (data_coding=8). Atención: Verifique AQUI detalles de caracteres y cobranzas. |
| Flash SMS | Soporta data_coding=0x10 para GSM7 y data_coding 0x18 para UCS2 Cuando recibamos un flashSMS de nuestro cliente, el mismo sera enviado a la operadora como flashSMS, en el caso que la operadora no acepte flashSMS, este será entregado como un SMS regular. |
| Enquire-link | Minimo: 30 segundos / Máximo: 59 segundos. |
| Concatenación | UDH de 8 bits y 16 bits son compatibles / UDH Headers |
| Default addr_ton | 1 |
| Default addr_npi | 1 |
| window size | 10 |
| System IDs | SystemIDs can NOT contain the underscore _ character |
| Passwords | De acuerdo con la especificación del protocolo versión 3.4, no puede contener mas que 8 caracteres. |
| 2way | Soportado |
| SMPP bind type | Transceiver(Recomendado). Binds transmit/receiver separados también son aceptados. |
| SMPP system_type | MovileSMSC |
| SMPP source addr (senderID) | Cuando su servicio necesite respuestas de usuarios (MO), el source addres debe ser igual al system_id, o sea, el nombre de usuario. Cuando el servicio no necesita de MOs usted puede utilizar cualquier cosa en este campo. |
| Max flujo de MO | 80 por bind |
| Max flujo de MT | 80 por bind |
| Server Timezone | UTC |
| Formato de ID | UUID |
| Default validity_period | 24 hours |
Estatus de envio (Callback e DLR)
1 - Primer estatus (sent_status - Estatus de envio = Callback)
Estatus de entrega en la operadora, este es el primeir estatus que retornamos, y todas las operadoras poseen.
| stat | err | TLV (0x1403) | TLV (0x1404) | Significado |
|---|---|---|---|---|
| ACCEPTD | 000 | 2 | SENT_SUCCESS | Entregado en la operadora con éxito. (Este es un estatus que debe ser considerado para efecto de cobro.) |
| EXPIRED | 101 | 101 | EXPIRED | Expirado antes de ser entregado al aparato. |
| REJECTD | 102 | 102 | CARRIER_COMMUNICATION_ERROR | Error de comunicación con la operadora. |
| REJECTD | 103 | 103 | REJECTED_BY_CARRIER | Operadora rechazo el mensaje. |
| REJECTD | 202 | 202 | INVALID_DESTINATION_NUMBER | El numero de destino es invalido (No es un numero de celular valido). |
| REJECTD | 203 | 203 | BLACKLISTED | El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa. |
| REJECTD | 204 | 204 | DESTINATION_BLOCKED_BY_OPTOUT | El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing). |
| REJECTD | 205 | 205 | DESTINATION_MESSAGE_LIMIT_REACHED | El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras. |
| REJECTD | 207 | 207 | INVALID_MESSAGE_TEXT | El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas. |
| REJECTD | 301 | 301 | INTERNAL_ERROR | Ocurrio un error en la plataforma de Wavy. |
| UNKNOWN | 301 | 301 | INTERNAL_ERROR | Ocurrio un error en la plataforma de Wavy. |
2 - Segundo estatus (delivered_status - Delivery Report Callback)
Estatus de entrega en el aparato, este es el segundo estatus que retornamos y solo existe para los casos en que el primer estatus de arriba fue de éxito, o sea, el mensaje fue entregado en la operadora con éxito. En este estatus informamos si el mensaje fue o no entregado en el aparato. Algunas operadoras no poseen este segundo nivel de estatus, para estas operadoras, lo máximo de información que existe es el primer estatus o sea, si la operadora acepto el mensaje o no.
| stat | err | TLV (0x1403) | TLV (0x1404) | TLV (0x1405) | TLV (0x1406) | Significado |
|---|---|---|---|---|---|---|
| DELIVRD | 000 | 2 | SENT_SUCCESS | 4 | DELIVERED_SUCCESS | Entregado en el aparato con éxito. |
| UNDELIV | 104 | 2 | SENT_SUCCESS | 104 | NOT_DELIVERED | La operadora acepto el mensaje, pero no consiguió entregarlo en el aparato. Posibles causas: Aparato apagado o fuera del área de servicio por tiempo determinado (normalmente 24 horas, pero para algunas operadoras, este tiempo de tentativa es de 8 horas). Número válido, pero inactivo (algunas operadoras retornan este tipo de error solamente en este segundo nivel de estatus). |
Proxy TLS - Linux
El proxy es necesario en el caso que la conexión no sea vía VPN. Como fue explicado anteriormente, el protocolo SMPP no posee encriptacion TLS nativa, en este caso indicamos el siguiente proxy:
HAProxy
Configuración haproxy
global
# local2.* /var/log/haproxy.log
log 127.0.0.1 local2
chroot /var/lib/haproxy
pidfile /var/run/haproxy.pid
ssl-server-verify none
maxconn 4000
user haproxy
group haproxy
daemon
# turn on stats unix socket
stats socket /var/lib/haproxy/stats
resolvers dns
nameserver google 8.8.8.8:53
hold valid 1s
defaults
log global
option redispatch
retries 3
timeout http-request 10s
timeout queue 1m
timeout connect 10s
timeout client 1m
timeout server 1m
timeout http-keep-alive 10s
timeout check 10s
maxconn 3000
frontend movile
bind *:2444
mode tcp
option tcplog
use_backend movile
backend movile
mode tcp
server smpp-messaging.wavy.global smpp-messaging.wavy.global:2444 ssl resolvers dns check inter 15000
- Instalación haproxy servidores (red-hat / centos):
$sudo yum install -y openssl-devel haproxy
- Instalación haproxy servidores (debian / ubuntu)
$sudo apt-get install -y openssl-devel haproxy
- Despues de la Instalación, substituya todo el contenido del archivo /etc/haproxy/haproxy.cfg por el contenido al lado ->
IMPORTANTE: Configure su sistema (cliente SMPP) para utilizar como direccion de destino 127.0.0.1:2444
Proxy TLS - Windows
configuracion nginx
worker_processes 2;
events {
worker_connections 1024;
}
stream {
resolver 8.8.8.8 valid=1s;
map $remote_addr $backend {
default smpp-messaging.wavy.global;
}
server {
listen 2444;
proxy_pass $backend:2444;
proxy_ssl on;
}
}
Es posible utilizar nginx como proxy TLS en servidores windows para realizar la encriptacion de los dados
Descargue la versión abajo (importante utilizar esta versión porque las versiones antiguas resuelven el nombre apenas en el primer request)
http://nginx.org/download/nginx-1.12.1.zip
Extraiga el archivo .zip en la carpeta deseada y sustituya el contenido del archivo conf/nginx.conf con los datos al lado.
API SFTP
Detalles de conexión
| Hostname | ftp-messaging.wavy.global |
| Puerta | 2222 |
| Protocolo | SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor) |
| Autenticación | username + senha (provisto por soporte) |
| Portal | messaging.wavy.global |
Envio de mensajes via SFTP
Para realizar el disparo de mensajes vía SFTP es necesario generar un archivo en formato TXT, el formato debe seguir el siguiente ejemplo:
numero;texto;correlationId(opcional);
5511900000000;mensaje 1;;
5519900000000;mensaje 2;;
5521900000000;mensaje 3;;
EOF
El nombre del archivo a ser enviado debe seguir el siguiente formato:
<ID_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA>
ou
<NOME_DE_REFERÊNCIA_SUBCONTA>.<DATA(YYYYMMDD)>.<SEQUENCIA>
Las sub cuentas (projectos) pueden ser creadas por el propio cliente en el portal. En el caso que no sea seguida la nomenclatura arriba, el envío será realizado por la sub cuenta default del cliente.
Ejemplo:
3486.20170101.01.txt
ou
PROJETO1.20170101.01.txt
Después deberá ser realizado el envió del archivo para el servidor sftp en el directorio upload. El archivo será movido para el directorio success después de procesado, en el caso que aparezca un error el archivo será movido para el directorio error.
API Validación de números
Esta API permite realizar consultas en lote de números retornando la operadora a la que esos números pertenecen y consecuentemente los números inválidos (si un número no pertenece a ninguna operadora por lo tanto es inválido). Ella utiliza el protocolo HTTP con TLS y el metodo POST con parámetros en JSON. La consulta permite saber si determinado número pertenece a la operadora pero no es posible verificar si este número se encuentra activo.
Autenticacion
Para efectuar envíos y consultas en nuestra API es necesaria la autenticacion por medio de usuario o e-mail, en conjunto con un token.
| Campo | Detalles | Data Type |
|---|---|---|
| UserName | Su usuario o email | String |
| AuthenticationToken | Su token de autenticacion. Verifique aqui y lea las descripciones de usuarios abajo. | String |
Detalles de conexión
| Hostname | api-messaging.wavy.global |
| APIs | Consulta en lote /v1/carrier/lookup |
| Puerta | 443 (https) |
| Protocolo | HTTPS (encriptacion TLS) |
| Autenticacion | username + token |
| Portal | messaging.wavy.global |
Requisicion HTTP Method POST
curl --request POST \
--url https://api-messaging.wavy.global/v1/carrier/lookup \
--header 'authenticationtoken: <authenticationtoken>' \
--header 'username: <username>' \
--header 'Content-Type: application/json' \
--data '{
"destinations": ["+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 la consulta basta adicionar en el body de la requisicion un json con el array de números. Es posible hacer la consulta utilizando los formatos +55(19)999999999 y 5519999999999
Respuesta a la consulta
Respuesta a la llamada en formato JSON
{
"id": "aadb5130-7dd7-11e7-baac-a6aabe61edb5",
"destinations": [
{
"destination": "5519997712322",
"active": true,
"carrier": {
"name": "VIVO",
"countryCode": "BR"
}
},
{
"destination": "5519997712322",
"active": true,
"carrier": {
"name": "VIVO",
"countryCode": "BR"
}
},
{
"destination": "2312312",
"active": false,
"carrier": {
"name": "UNKNOWN"
}
}
]
}
El ultimo numero de ejemplo se trata de un numero invalido para demostrar como la consulta retorna el JSON en este caso.
La respuesta de la consulta en lote contendrá un archivo JSON con las informaciones individuales sobre cada número consultado:
| Campo | Detalles | Tipo |
|---|---|---|
| id | UUID generado para este lote | String |
| destinations | Este campo es un array con las respuestas de las consultas individuales del lote, contiene el id y el correlationId de cada número consultado | IndividualResponse[] |
| destination | Número de telefono consultado | Long |
| active | status del numero en la operadora (actualmente verifica apenas si el número pertenece a la operadora, no activo / en uso) | Boolean |
| carrier | Operadora y país a la cual pertenece el número consultado | array[] |
| name | Nombre de la operadora | String |
| countryCode | Codigo de País | String |
Acentos y caracteres especiales
Mensajes que poseen solamente caracteres que están en la siguiente tabla, son cobrados cada 160 caracteres. En el caso que el mensaje tenga uno o mas caracteres que no están en la tabla el cobro sera realizado cada 70 caracteres, conforme la especificación del protocolo en la red de las operadoras.
| Space | ( | 0 | 8 | @ | H | P | X | ` | h | p | x |
| ! | ) | 1 | 9 | A | I | Q | Y | a | i | q | y |
| “ | * | 2 | : | B | J | R | Z | b | j | r | z |
| # | + | 3 | ; | C | K | S | { | c | k | s | ~ |
| $ | , | 4 | < | D | L | T | \ | d | l | t | |
| % | - | 5 | = | E | M | U | } | e | m | u | |
| & | . | 6 | > | F | N | V | ^ | f | n | v | |
| ‘ | / | 7 | ? | G | O | W | _ | g | o | w |
Observaciones:
1 - La habilitación del uso de acentos y caracteres especiales debe ser solicitada al suporte.
2 - En el caso que la operadora destino no acepte acentos y caracteres, nuestra plataforma realiza automáticamente para nuestros clientes, la substitución de los mismos, por ejemplo: á para a, é para e, etc.
Textos grandes (concatenación)
A pesar que el protocolo utilizado en la red de las operadoras tenga limite de 70 o 160 caracteres, para mensajes con o sin caracteres especiales respectivamente, es posible enviar mensajes grandes con la utilización de concatenación, donde los mensajes son reagrupados por los aparatos al recibirlos.
Clientes integrados vía HTTPS, SFTP, o MQ, no existe ningún indicador adicional para activar la concatenación, basta solo enviar el texto del mensaje grande entero de una sola vez.
Clientes integrados vía SMPP, deben utilizar la funcionalidad de concatenación con indicadores en el header (UDH), LINK
Es importante notar que, a pesar de aparecer en el aparato como un único mensaje grande, los mensajes continúan traficando en la red de operadora individualmente, en este caso, continúan siendo cobrados individualmente cada 70 o 160 (dependiendo de los caracteres utilizados). Recordando que al utilizar concatenación parte de los caracteres (70 o 160) son utilizados por el encabezado.
Observación: En los casos de operadoras que no soportan la funcionalidad de concatenación, Wavy enviá los mensajes separadamente, sin concatenar incluyendo automáticamente para nuestros clientes, indicadores de orden,
Ex:
Inicio do texto…. (½)
……fin do texto (2/2)
Wavy Messaging WhatsApp API
Esta documentación contiene información sobre cómo su aplicación podrá enviar los mensajes de Whatsapp vía API, utilizando la plataforma de Wavy Messaging.
También encontrará aquí información sobre los Webhooks, esto es, los retornos de llamada HTTP definidos por el usuario, los cuales son accionados por eventos específicos. Siempre que ocurre un evento de acción, ya sea, un mensaje enviado o recibido, la API de Wavy recibe los datos e inmediatamente envía una notificación (solicitud HTTP) a la URL indicada por el cliente, actualizando el estatus de los mensajes enviados o indicando cuando recibe un mensaje.
La API de Wavy Messaging permite el envío de mensajes únicos o en lotes. La API posee integración REST, utilizando el protocolo HTTP con TLS, soportando el método POST con los parámetros enviados en formato JSON.
Términos Importantes para WhatsApp
| MT | Mobile Terminated | Es un termino utilizado para mensajes que poseen el usuario (Aparato) como destino. O sea, mensajes que fueron originados por su empresa con destino al usuario (Aparato). |
| Response | Respuesta sincronica de Wavy | Es una respuesta inmediata de una solicitud hecha en nuestra API, donde informamos si el mensaje fue aceptado o no por nuestra plataforma |
| Callback | Sent status o Estatus de envió | Es el primer status de envió que retornamos, en el informamos si fue posible, o no, hacer la entrega del mensaje. para lo WhatsApp. |
| MO | Mobile Originated | Es el termino utilizado para mensajes que poseen su empresa como destino. O sea, mensajes que fueron originados por el usuario (Aparato). |
Flujo de mensajes WhatsApp
Flujo simplificado - MT, Callback e MO.
Pré Requisitos
- Para utilizar la API de Wavy Messaging, primero debe tener una cuenta activa en la plataforma de Wavy. Consulte la documentación de Cuenta y configuraciones para obtener más información sobre cómo realizar este procedimiento.
- Deberá tener un usuario y token válidos asociados a su cuenta. Puede agregar otros usuarios si así lo desea, aprenda a crear un usuario en nuestra guía Agregar usuarios.
- Con las credenciales mencionadas anteriormente, ahora puede comenzar a usar la API Wavy Messaging.
Detalles de la conexión
| Hostname | api-messaging.wavy.global |
| Porta | 443 (https) |
| Protocolo | HTTPS (TLS encryption) |
| Autenticação | UserName e AuthenticationToken |
| Encoding | UTF-8 |
Haciendo llamadas para la API de Wavy Messaging
Para realizar sus primeros envíos, recomendamos utilizar la aplicación Postman con requisitos de formato JSON en lugar de comenzar escribiendo código en otros lenguajes.
Nota: Para enviar mensajes de prueba, necesita tener un Template de mensaje aprobado en su cuenta de WhatsApp Business. Consulte nuestra documentación sobre Creación de Template de Whatsapp, para crear sus primeros modelos.
En el caso que no tenga algún template de mensaje aprobado, aún puede enviar mensajes de prueba, si el destinatario inicia la conversación enviando un mensaje (MO) al número de origen de la línea de Whatsapp. De esta forma, se abre una sesión hacia al cliente. Esto permite que pueda enviar cualquier tipo de mensaje en un lapso de 24 horas. Si el mensaje llega, significa que su solicitud a la API de Wavy Messaging fue exitosa. Caso contrario, verifique su Webhook en busca de notificaciones que puedan indicar algún problema.
Envío de mensajes
Las llamadas para la API de Wavy Messaging son enviadas a https://api-messaging.wavy.global/v1/whatsapp/send en formato POST independientemente del tipo de mensaje, pero el contenido del cuerpo del mensaje JSON puede variar para cada tipo de mensaje.
Los campos de autenticación en el header también seguirán el mismo formato independientemente del tipo de mensaje:
| POST | /v1/whatsapp/send HTTP/1.1 |
| Host: | api-messaging.wavy.global |
| UserName: | user_name |
| AuthenticationToken: | aaaaaa-bbbbbbbbbbbbbXXXXX12 |
| Content-Type: | application/json |
El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| destinations | Si | Lista de destinatarios | Destination |
| message | Si | Mensaje de texto que se enviará a la lista de destinatarios | Message |
| flowId | No | Identificación del flujo de Bot | String |
| defaultExtraInfo | No | Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje | String |
| campaignAlias | No | ID de campaña, está vinculado a todos los mensajes del envío | String |
Destino:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| correlationId | No | Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos. | String |
| destination | Si | Número de teléfono (código de país y estado deben estar presentes) o el WhatsApp group ID al que se enviará el mensaje. Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111. | String |
| recipientType | No | Debe ser "individual" o "group", dependiendo de si el campo destination es un número de teléfono o un group ID. |
String |
Mensaje:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| messageText | Si | Campo utilizado en caso de que desee enviar un mensaje personalizado como respuesta a un mensaje recibido. | text |
| image | Si | Campo utilizado en caso de que desee enviar un contenido de imagen. | Image |
| audio | Si | Campo utilizado en caso de que desee enviar un contenido de audio. | Audio |
| document | Si | Campo utilizado en caso de que desee enviar un archivo o documento. | Document |
| contacts | Si | Campo utilizado en caso de que desee enviar contactos. | Contact[] |
| previewFirstUrl | No | Controla la vista previa de la aplicación de la primera URL enviada | Boolean |
| location | Si | Campo utilizado en caso de que desee enviar una ubicacion. | Location |
Ejemplo de envío de texto
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"messageText": "Mensaje de prueba"
}
}
Ejemplo de envío de imagen (URL)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"url": "http://...jpg",
"caption": "image description"
}
}
}
Ejemplo de envío de imagen (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"image": {
"type": "JPG",
"data": "ZmlsZQ=="
}
}
}
Ejemplo de envío de audio (URL)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"url": "http://...mp3"
}
}
}
Ejemplo de envío de audio (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"audio": {
"type": "MP3",
"data": "ZmlsZQ=="
}
}
}
Ejemplo de envío de documento (URL)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"url": "http://...pdf",
"caption": "pdf description"
}
}
}
Ejemplo de envío de documento (Base64)
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"document": {
"type": "PDF",
"data": "ZmlsZQ=="
}
}
}
Ejemplo de envío de ubicacion
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"location": {
"geoPoint": "-22.894180,-47.047960",
"name": "Wavy",
"address": "Av. Cel. Silva Telles"
}
}
}
Ejemplo de envio de contactos
{
"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"
}
]
}
]
}
}
Solo se debe enviar un mensaje personalizado como respuesta a un mensaje recibido por el usuario siempre cuando la sesión se encuentre abierta. Si la sesión no está abierta o el usuario no envió un mensaje deberá utilizase el Template.
Texto:
| Campo | Obrigatório | Detalhes | Tipo |
|---|---|---|---|
| messageText | Si | Texto que se enviará al usuario. |
Imagen:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| type | Si | Tipo / extensión de la imagen que se enviará en el mensaje. Opciones disponibles: JPG, JPEG, PNG. | String |
| caption | No | Texto que se mostrara al usuario debajo de la imagen en Whatsapp | String |
| url | Si | URL donde se aloja el contenido que se enviará. | String |
| data | Si | Base64 contenido codificado | String |
Audio:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| type | Si | Tipo/Extensión de audio que se enviará en el mensaje. Opciones disponibles: AAC, MP4, AMR, MP3, OGG. | String |
| url | Si | URL donde se aloja el contenido que se enviará. | String |
| data | Si | Base64 contenido codificado | String |
Documento:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| type | Si | Tipo/Extensión de documento que se enviará en el mensaje. Opciones disponibles: PDF. | String |
| caption | No | Texto que se mostrara al usuario debajo del documento en Whatsapp | String |
| url | Si | URL donde se aloja el contenido que se enviará. | String |
| data | Si | Base64 contenido codificado | String |
Contact:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| addresses | No | Direcciones de contacto completas. | Address[] |
| birthday | No | Fecha de cumpleaños como cadena con formato YYYY-MM-DD. | String |
| emails | No | Direcciones de correo electrónico de contacto. | Email[] |
| name | No | Nombre completo de contacto. | Name |
| org | No | Información de la organización de contacto. | Org |
| phones | No | Teléfonos de contacto. | Phone[] |
| urls | No | URLs de los contactos. | Url[] |
Address:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| street | No | Número y nombre de la calle. | String |
| city | No | Nombre de la ciudad. | String |
| state | No | Abreviatura del estado. | String |
| zip | No | Código postal. | String |
| country | No | Nombre completo del país. | String |
| country_code | No | Abreviatura de país de dos letras. | String |
| type | No | Valores estándar: HOME, WORK. | String |
Email:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| No | Correo electrónico. | String | |
| type | No | Valores estándar: HOME, WORK. | String |
Name:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| first_name | No | Primer nombre. | String |
| last_name | No | Apellido. | String |
| middle_name | No | Segundo nombre. | String |
| name_suffix | No | Sufijo del nombre. | String |
| name_prefix | No | Prefijo del nombre. | String |
| formatted_name | No | Nombre completo como aparece normalmente. | String |
Org:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| company | No | Nombre de la empresa del contacto. | String |
| department | No | Nombre del departamento de contacto. | String |
| title | No | Título comercial de contacto. | String |
Phone:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| phone | No | Número de teléfono formateado. | String |
| type | No | Valores estándar: CELL, MAIN, IPHONE, HOME, WORK. | String |
| wa_id | No | Identificador de WhatsApp. | String |
Url:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| phone | No | URL del contacto. | String |
| type | No | Valores estándar: HOME, WORK. | String |
Envío de Template
Ejemplo de solicitud template
{
{
"destinations": [{
"correlationId": "MyCorrelationId",
"destination": "5519900001111"
}],
"message": {
"template": {
"namespace" : "aaaaaaaa_bbbb_cccc_dddd_eeeeeeeeeeee",
"elementName" : "some_approved_image_hsm"
},
{
"languagePolicy": "DETERMINISTIC",
"languageCode": "pt_BR"
}
}
}
}
Ejemplo de solicitud template con Header y 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"
}
}
}
Si aún no tiene una plantilla creada y aprobada para su uso, consulte la documentación en Template de WhatsApp para obtener más información sobre cómo hacerlo. El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:
| Field | Required | Details | Type |
|---|---|---|---|
| destinations | Si | Detalles sobre los identificadores de envío y destino | Destination[] |
| message | Si | Detalles sobre el objeto MENSAJE que se enviará | message |
| defaultExtraInfo | No | Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje | String |
| campaignAlias | No | ID de campaña, está vinculado a todos los mensajes del envío | String |
destinations:
| Field | Required | Details | Type |
|---|---|---|---|
| correlationId | No | Id definido por el cliente que se devolverá en el estado del mensaje (devolución de llamada). Puede usar esta identificación para rastrear mensajes enviados de manera personalizada. | String |
| destination | Si | Número de teléfono que recibirá el mensaje (el código de país y DDD son obligatorios). Ejemplos: 5519900001111, +5519900001111, +55 (19) 900001111. | String |
message:
| Campo | Obrigatório | Detalhes | Type |
|---|---|---|---|
| template | Si | Detalles sobre el objeto TEMPLATE que se enviará. | Template |
template:
| Field | Required | Details | Type |
|---|---|---|---|
| namespace | Si | ID del namespace que será usado. NOTA: Los parámetros namespace y element_name deben corresponder al Business Manager al cual el número de origen está asociado, o el mensaje tendrá una falla en el envío. | String |
| elementName | Si | Nombre del Template registrado y aprobado. | String |
| header | Si, cuando el Template tiene un parámetro en el encabezado (header) | Objetos del encabezado (header) con sus parámetros | Header |
| bodyParameters | Si (cuando el Template tiene parámetros) | La suma de todos los caracteres en el cuerpo, considerando campos fijos y dinámicos, está limitada a 1024 caracteres si el modelo registrado solo tiene el cuerpo. Está limitado a 160 caracteres si tiene un encabezado o pie de página. | Lista de strings |
| languageCode | Sí, cuando hay más de un idioma registrado para la misma plantilla. | 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án reemplazados en el texto del encabezado. Nota: En el caso de que esté presente el encabezado no debe tener título ni elemento alguno. | String |
| title | Opcional | El título debe tener hasta 60 caracteres | String |
| (element) | Si | Opciones: text (patrón), image, audio, document, video. | Object |
element:
| Field | Required | Details | Type |
|---|---|---|---|
| url | Si | URL del archivo multimedia. Usar únicamente con URLs HTTP/HTTPS. | String |
| type | Si | Tipo de archivo multimedia (JPEG, MP3, PDF, etc) | String |
Webhooks
Ejemplo
{
"total": 1,
"data": [
{
"id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
"correlationId": "...",
"destination": "5411900000000",
"origin": "5411900000000",
"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
}
}
Los Webhooks (o callbacks) son retornos de llamada de HTTP definidos por el usuario, que son accionados por eventos específicos. Siempre que ocurra un evento de acción, la API de Wavy recolectará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL proporcionada por el cliente actualizando el estatus de los mensajes enviados o indicando cuándo recibirá un mensaje.
Cuando reciba un mensaje, la API de Wavy Messaging enviará una notificación de solicitud HTTP POST a la URL del Webhook con los detalles.
Es importante que su Webhook retorne una respuesta HTTPS 200 OK para las notificaciones (en un lapso de hasta 200 ms o de manera asíncrona). Caso contrario, la API de Wavy Messaging considerará esa notificación como una falla e intentará nuevamente.
Importante: Indicar el webhook donde recibirá los mensajes, para que nuestro equipo de soporte pueda asociarlo a su cuenta de Whatsapp
| Campo | Detalles | Tipo |
|---|---|---|
| total | Número de callbacks en la llamada. | String |
| data | Lista de callbacks. | Data[] |
| clientInfo | Información del cliente | ClientInfo |
data:
| Campo | Detalles | Tipo |
|---|---|---|
| id | ID del último mensaje | String |
| correlationId | Un ID único configurado por usted para coincidir con el estado del mensaje (callback y DLR). Este parámetro es opcional y puede usar el ID generado por Wavy Messaging para esta coincidencia. | String |
| destination | Teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5411900000000. | String |
| origin | Teléfono que identifica la cuenta de WhatsApp (incluido el código de país). Ejemplo: 5411900000000. | String |
| campaignId | ID de campaña previamente definido. | String |
| campaignAlias | Alias de campaña previamente definido. | String |
| extraInfo | Información adicional enviada con el mensaje original. | String |
| sent | Indica si el mensaje fue enviado. | Boolean |
| sentStatusCode | Código de estado generado por Wavy Messaging para un mensaje que indica el estado de envío. | Number |
| sentStatus | Descripción del estado enviado. | Boolean |
| sentDate | Fecha en que se envió el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ. | String |
| sentAt | Hora en que se envió el mensaje, utilizando el formato Unix_time | Number |
| delivered | Indica si el mensaje fue entregado al destino. | Boolean |
| deliveredStatusCode | Código de estado generado por Wavy Messaging para indicar que el mensaje fue entregado. | Number |
| deliveredStatus | Descripción del estado de entrega | String |
| deliveredDate | Fecha en que se entregó el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| deliveredAt | Hora en que se entregó el mensaje, utilizando el formato Unix_time | Number |
| read | Indica si el mensaje fue leído por el destinatario. | Boolean |
| readDate | Fecha en que se leyó el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| readAt | Hora en que se leyó el mensaje, utilizando el formato Unix_time | String |
| updatedDate | Fecha en que se actualizó el estado del mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| updatedAt | Fecha en que se actualizó el estado del mensaje, utilizando el formato Unix_time | String |
| type | El tipo de entidad del que trata este objeto de estado. Actualmente, la única opción disponible es “mensaje”. | String |
clientInfo
| Campo | Detalles | Tipo |
|---|---|---|
| customerId | Identificación del cliente. | Number |
| subAccountId | Identificación de la subcuenta. | Number |
| userId | Identificación del usuario. | Number |
Status
Descripción del Status que nosotros podemos enviar en la devolución de llamada:
| Status | Descripción | Equivalente en WhatsApp para dispositivos móveis |
|---|---|---|
| SENT_SUCCESS | Mensaje recibido por servidor de WhatsApp | Una marca de verificación |
| DELIVERED_SUCCESS | Mensaje de entrega para el destinatario | Dos marcas de verificación |
| READ_SUCCESS | Mensaje leído por el destinatario | Dos marcas de verificación azules |
Otros Status
Estos son los códigos devueltos en los campos sentStatusCode y deliveryStatusCode.
| Código de envio | Código de entrega | Status | Significado |
|---|---|---|---|
| 102 | CARRIER COMMUNICATION ERROR | Error al cargar multimedia para WhatsApp. | |
| 103 | REJECTED_BY_CARRIER | Se produjo un error en la base de datos. | |
| 2 | 101 | EXPIRED | Mensaje expirado. |
| 2 | 104 | NOT_DELIVERED | Posibles Causas:Límite alcanzado: se han intentado demasiados mensajes enviados,o no envía un mensaje porque el número de teléfono de destino no existe,o la estructura de la plantilla no existe,o no pudo enviar un mensaje porque el número de destino está fuera del tiempo de sesión abierta de 24 horas para recibir mensajes libremente. o hubo un error de carga de medios (error desconocido), o no envía un mensaje porque su cuenta no es elegible en Facebook Business Manager,o hubo un error de carga temporal. Intentar nuevamente más tarde. |
| 202 | EXPIREDINVALID_DESTINATION_NUMBER | Contacto de WhatsApp inválido. | |
| 204 | DESTINATION_BLOCKED_BY_OPTOUT | Destino bloqueado por Opt-Out. | |
| 207 | INVALID_MESSAGE_TEXT | El valor del parámetro no es válido. | |
| 209 | INVALID_CONTENT | Tipo de mensaje UNKNOWN inválido. | |
| 210 | INVALID_SESSION | La sesión no está abierta o ninguna plantilla de fallback está configurada. | |
| 301 | INTERNAL_ERROR | No es posible verificar contactos desde la API de WhatsApp. | |
Errores
| 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 |
Mensajes (MO)
Ejemplo de mensaje 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"
}
]
}
Ejemplo de mensaje con respuesta de botón:
{
"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
}
}
Ejemplo de mensaje multimedia
{
"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"
}
]
}
Ejemplo de mensaje de ubicación:
{
"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"
}
]
}
Ejemplo de mensaje de contacto:
{
"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"
}
]
}
Ejemplo 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
}
]
}
Ejemplo de mensaje de texto de 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"
}
]
}
Cuando el cliente le envíe un mensaje, Wavy Messaging API enviará una notificación de solicitud HTTP POST a la URL de Webhook con los detalles.
Es importante que su Webhook retorne una respuesta HTTPS 200 OK para las notificaciones (en un lapso de hasta 200 ms o de manera asíncrona). Caso contrario, la API de Wavy Messaging considerará esa notificación como una falla e intentará nuevamente.
Importante: Indicar el webhook donde recibirá los mensajes, para que nuestro equipo de soporte pueda asociarlo a su cuenta de Whatsapp
El formato de la respuesta será de acuerdo a la siguiente descripción:
| Campo | Detalles | Tipo |
|---|---|---|
| total | Número de callbacks en la llamada. | String |
| data | Lista de mensajes originados en dispositivos móviles. | Data |
| Campo | Detalles | Tipo |
|---|---|---|
| id | Última identificación del mensaje | String |
| source | Teléfono del remitente | String |
| origin | Teléfono que identifica la cuenta de WhatsApp (incluido el código de país). Ejemplo: 5411900000000. | String |
| userProfile | Perfil del usuario que envió el mensaje | UserProfile |
| correlationId | Un ID único configurado por usted para coincidir con el estado del mensaje (Callback y DLR). Este parámetro es opcional y puede usar el ID generado por Wavy Messaging para esta coincidencia. | String |
| campaignId | ID de campaña previamente definido. | String |
| campaignAlias | Alias de Campaña previamente definido. | String |
| message | Mensaje MO. | Message |
| receivedAt | Fecha en que se recibió el mensaje. Formato: yyyy-MM-dd’T'HH:mm:ssZ | String |
| receivedDate | Fecha en que se recibió el mensaje, utilizando el formato Unix_time | String |
| extraInfo | Información extra relacionada con el mensaje. Formato: Json | String |
| referral | Presente si el usuario inició el mensaje al hacer clic en una publicación o anuncio. Este campo es opcional (puede ser nulo). | Referral |
| mtSentAt | La marca de tiempo de la fecha/hora en que se envió el último MT a este destinatario. | Long |
| session | Información de la sesión. | Session |
Referral
Todos los campos de este objeto son opcionales (pueden ser nulos).
| Campo | Detalhes | Tipo |
|---|---|---|
| headLine | Titular del anuncio que generó el mensaje. | String |
| body | Cuerpo del anuncio. | String |
| sourceType | Tipo de anuncio. Puede ser “ad”, “post” o “unknown”. | String |
| sourceId | Identificación de anuncio o publicación en Facebook. | String |
| sourceUrl | URL del anuncio o publicación. | String |
| mediaType | Tipo de medio presente en el anuncio. Puede ser “image” o “video”. | String |
| mediaUrl | Url del medio presente en el anuncio. | String |
Session
| Field | Details | Type |
|---|---|---|
| sessionId | ID de sesión para este usuario. | String |
| createdAt | Marca de tiempo de creación de la sesión. | Long |
Mensaje:
| Campo | Detalles | Tipo |
|---|---|---|
| type | Tipo de mensaje enviado por el usuario final: TEXT - IMAGE - AUDIO - DOCUMENT | String |
| messageText | El mensaje de texto (MO) enviado por el usuario final. | String |
| waGroupId | El grupo al que se envió el mensaje. | String |
| mediaUrl | Url para descargar la multimedia enviada por el usuario final. | String |
| mimeType | Tipo de archivo enviado por el usuario final. | String |
| caption | Etiqueta de multimedia enviada por el usuario final. | String |
| location | Ubicación enviada por el usuario final. | Location |
| contacts | Contactos enviados por el usuario final. | Contact[] |
UserProfile:
| Field | Necesario | Detalles | Tipo |
|---|---|---|---|
| name | No | El nombre del perfil del usuario | String |
Location:
| Field | Details | Type |
|---|---|---|
| name | Nombre del sitio. | String |
| address | Dirección del sitio. | String |
| geoPoint | Geopoint enviada por el usuario final. Formato: “latitud, longitud” | String |
Contact:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| addresses | No | Direcciones de contacto completas. | Address[] |
| birthday | No | Fecha de cumpleaños como cadena con formato YYYY-MM-DD. | String |
| emails | No | Direcciones de correo electrónico de contacto. | Email[] |
| name | No | Nombre completo de contacto. | Name |
| org | No | Información de la organización de contacto. | Org |
| phones | No | Teléfonos de contacto. | Phone[] |
| urls | No | URLs de los contactos. | Url[] |
Address:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| street | No | Número y nombre de la calle. | String |
| city | No | Nombre de la ciudad. | String |
| state | No | Abreviatura del estado. | String |
| zip | No | Código postal. | String |
| country | No | Nombre completo del país. | String |
| country_code | No | Abreviatura de país de dos letras. | String |
| type | No | Valores estándar: HOME, WORK. | String |
Email:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| No | Correo electrónico. | String | |
| type | No | Valores estándar: HOME, WORK. | String |
Name:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| first_name | No | Primer nombre. | String |
| last_name | No | Apellido. | String |
| middle_name | No | Segundo nombre. | String |
| name_suffix | No | Sufijo del nombre. | String |
| name_prefix | No | Prefijo del nombre. | String |
| formatted_name | No | Nombre completo como aparece normalmente. | String |
Org:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| company | No | Nombre de la empresa del contacto. | String |
| department | No | Nombre del departamento de contacto. | String |
| title | No | Título comercial de contacto. | String |
Phone:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| phone | No | Número de teléfono formateado. | String |
| type | No | Valores estándar: CELL, MAIN, IPHONE, HOME, WORK. | String |
| wa_id | No | Identificador de WhatsApp. | String |
Url:
| Campo | Necesario | Detalles | Tipo |
|---|---|---|---|
| url | No | URL del contacto. | String |
| type | No | Valores estándar: HOME, WORK. | String |
extraInfo (Control de flujo de MO - Listas de segmentación)
El mensaje tendrá una lista de listas de segmentaciones en el campo Información adicional. Nuestros asociados lo utilizan para redirigir los mensajes a través de ciertos flujos. El nombre de la clave es segmentation_lists y contiene una lista de SegmentationList.
| Campo | Detalles | Tipo |
|---|---|---|
| id | Identificador de la lista de segmentación | Integer |
| customerId | Identificador de cliente | Integer |
| subAccountId | Identificador de subcuenta | Integer |
| name | Nombre de la lista de segmentación | String |
| active | Estado de la lista de segmentación | Boolean |
API SFTP WhatsApp
Detalle de Conexión
| Hostname | ftp-messaging.wavy.global |
| puerto | 2222 |
| Protocolo | SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor) |
| Autenticación | username + senha (provisto por soporte) |
Envío de mensajes a través de SFTP
Mensaje Template a través de SFTP
Template con multimidia:
2020-01-21;16:00;16:00;TEMPLATE;chatclub_welcome;whatsapp:hsm:ecommerce:movile;pt_BR;DETERMINISTIC;nombre|empresa
IMAGE;URL;https://upload.wikimedia.org/wikipedia/en/d/d2/Imagem_logo.png;PNG
phone;nombre;empresa
5519981560597;Nombre1;Wavy
| 1ª línea |
|---|
| Fecha de envío (para casos de programación) |
| Hora inicial de envío (para casos de programación) |
| Hora final de envío (para casos de programación) |
| Tipo de mensaje debe ser: TEMPLATE |
| Nombre (elementName) del Template |
| Namespace (namespace) del Template |
| Idioma (languageCode) de Template |
| Definicíon del idioma del Template (languagePolicy): DETERMINISTIC o FALLBACK |
| Nombre de los parámetros de Template |
Observaciones para la primera línea:
1 - Los nombres de los parámetros deben coincidir con los nombres de las columnas o será considerado como valores constantes
2 - Las informaciones que no se utilicen se pueden dejar en blanco, pero deben mantener el punto y coma como separación. Ejemplo de un caso que no utilizamos programación (los campos iniciales quedan entre punto y coma y sin información dentro): ; ; ; TEMPLATE;chatclub_welcome;whatsapp:hsm:ecommerce:movile;pt_BR;DETERMINISTIC;nome|empresa
3 - Por defecto (predeterminado) la languagePolicy será DETERMINISTIC.
4 - Los nombres de los parámetros del Template deben ser separados por “|” y no por “;”
| 2ª línea | Ejemplo |
|---|---|
| Tipo de Header soportado por template | IMAGE, AUDIO, VIDEO o DOCUMENT |
| Tipo de fuente de medios | URL o PATH (Directorio de medios del servidor FTP) |
| Medio | Url o directorio del servidor FTP |
| Tipo de medio | JPEG, PNG, JPG, PDF, DOC, MP4, MP3 |
Observaciones para la segunda línea:
1 - El tipo de medio debe ser un tipo aceptado por el WhatsApp
| Medio | Content-Types soportados |
|---|---|
| documento | cualquier MIME-type valido |
| foto | image/jpeg, image/png |
| audio | audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus |
| vídeo | video/mp4, video/3gpp. Observação: Solamente H.264 vídeo codec e AAC audio codec es compatible. |
| 3ª línea |
|---|
| Nombre de las columnas |
| 4ª y demás líneas: |
|---|
| Destinatario y valores de los parámetros de Template |
Templates personalizadas por destinatario:
Para mensajes personalizadas, como diferentes medios por destinatario, contacte a nuestro equipo de soporte técnico para realizar la configuración y obtener más detalles para el envío.
Consulta sesiones abiertas vía API
Solicitud
Para consultar sesiones abiertas a través de nuestra API, debe realizar una solicitud GET a la siguiente dirección:
GET http://api-messaging.wavy.global/v1/session?customerId={customerId}&subAccountId={subAccountId}
Pasar el parámetro customerId es obligatorio, mientras que subAccountId es opcional.
Atención: Tenga cuidado de reemplazar ‘{’ y ‘}’ también. Por ejemplo, “={customerId}” se convierte en “=42”.
También necesitará utilizar los siguientes headers:
| Header | Valor |
|---|---|
| Content-Type | application/json |
| authenticationToken | Token de Messaging1 |
| userName | Nombre de usuario de Messaging1 |
Respuesta
En el exito, si hay sesiones abiertas para el cliente especificado y subAccountId, la solicitud devuelve un JSON con el atributo:
| Atributo | Valor |
|---|---|
| file_url | Link para descargar un archivo de tipo csv que contiene los campos “source” y “session_created_at” de todos los destinos encontrados |
Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, sólo con el encabezado.
Ejemplo de respuesta:
{
"file_url": "https://chatclub-cdn.wavy.global/2019/02/13/633e33fc-3a3f-4ca5-a8b0-4b747fb67137/5bd46e2b-5990-4681-9b29-98ab6598960e"
}
API de Campañas
Este documento proporciona la información necesaria para integrarse con la plataforma de Wavy Messaging para realizar la gestión de campañas. La API tiene integración REST, mediante el protocolo HTTP con TLS, que admite los métodos POST con los parámetros enviados en formato JSON.
Autenticación
Para utilizar con éxito nuestra API, debe proporcionar un nombre de usuario válido (correo electrónico) asociado con un token de autenticación. Debe agregar los siguientes encabezados a la solicitud:
| Campo | Detalles | Tipo de datos |
|---|---|---|
| userName | Correo electrónico válido suscrito en la plataforma Wavy Messaging | String |
| authenticationToken | Token de autenticación generado por nuestra plataforma. Encuéntrelo aquí o consulte nuestro soporte. | String |
Detalles de conexión
| Hostname | apigw.wavy.global |
| Port | 443 (https) |
| Protocol | HTTPS (TLS encryption) |
| Authorization | username + token |
| Encoding | UTF-8 |
Listado de campañas
Ejemplo de listado de campañas
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>'
Respuesta
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"
}
]
}
Listado de campañas ya registradas en la plataforma. Puedes seleccionar la página de resultados o filtrar por nombre de campaña.
GET https://apigw.wavy.global/api/v1/campaigns
Parámetros QueryString
* Campos Requeridos
| Campo | Detalles | Tipo de Dato |
|---|---|---|
| name | Nombre de la campaña para ser utilizado como filtro. | String |
| page | Página que se solicita | Integer |
| page_size | Cantidad de registros por página | Integer |
Solicitando una campaña específica
Ejemplo de solicitación de una campaña específica
curl -X GET \
https://apigw.wavy.global/api/v1/campaigns/1234 \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>'
Respuesta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Solicitando una campaña específica por el ID
GET https://apigw.wavy.global/api/v1/campaign/{id}
Creando campañas
Ejemplo de creación de campaña:
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"
}
}'
Respuesta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Creando una nueva campaña con nombre y alias . El alias de la campaña debe ser un nombre simple para que sea más fácil de usar con la API. Se recomienda ser corto y no usar caracteres especiales.
POST https://apigw.wavy.global/api/v1/campaigns
JSON Object
* Campos requeridos
| Campo | Detalles | Tipo de dato |
|---|---|---|
| name* | Nombre de la campaña | String |
| alias | Identificador de la campaña. | String |
Cambiando campañas
Ejemplo de cambio en campaña:
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"
}
}'
Respuesta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Cambiando una campaña por su nombre o alias.
PUT https://apigw.wavy.global/api/v1/campaigns/{id}
JSON Object
* Campos requeridos
| Campo | Detalles | Tipo de dato |
|---|---|---|
| name* | Nombre de la campaña | String |
| alias | Identificador de la campaña | String |
Borrando campañas
Ejemplo borrando campañas:
curl -X DELETE \
https://apigw.wavy.global/api/v1/campaigns/1234 \
-H 'Content-Type: application/json' \
-H 'authenticationToken: <authentication_token>' \
-H 'userName: <e-mail>'
Respuesta
{
"status": {
"error": false
},
"campaign": {
"name": "My Campaign",
"id": 1234,
"alias": "mycampaign"
}
}
Borrando una campaña por su ID
DELETE https://apigw.wavy.global/api/v1/campaigns/{id}
Soporte
| Apertura de llamados | Para abrir llamados visite nuestro Service Center |
| Telefono México | +52 55 5985 9111 |
| Telefono Colômbia | +57 1 3814943 |
| Telefono Perú (Toll Free) | (0800) 78427 |