NAV Navbar
cURL Ruby Python PHP Java

en es pt

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.

Conozca también nuestro portal Web, por el su empresa puede administrar usuarios, proyectos y configuraciones. Enviar y recibir mensajes y obtener informes sin la necesidad de desarrollo o integracion

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 Movile 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 Movile 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 (Movile), y poseen reglas anti-fraude y anti-spam.

Flujo de Mensajes

Flujo simplificado - MT, Callback, DLR, e MO.

alt text

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.movile.com
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.movile.com

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.movile.com/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.movile.com/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.movile.com/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.movile.com/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.movile.com/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 Movile):

[
  {
  "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.movile.com/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.movile.com/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 Movile 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 Movile. 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.movile.com/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.movile.com/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.movile.com/v1/send-bulk-sms \
  --header 'authenticationtoken: <Token de autenticação>' \
  --header 'username:<Usuário Movile Messaging>' \
  --header 'content-type: application/json' \
  --data "{ "messages":[{ "destination":"5519999999999", "messageText":"First message" }, { "destination":"5519999999999" }, { "destination":"5519999999999" }], "defaultValues":{"messageText":"Default message" }}"

Mod: curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/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.movile.com/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",
  "scheduleDate": "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.movile.com/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 Movile 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 Movile. 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[]

Estatus de envio (Callback e DLR)

Existen dos maneras de obtener los estatus de envíos de los mensajes, son ellas:

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.

Los estatus quedan disponibles por 3 días, e pueden ser consultados por el UUID que Movile retorno al recibir el mensaje de su empresa, o por el ID que su empresa paso al entregar el mensaje para Movile.
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 Movile 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 Movile 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 Movile 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 Movile 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 consultar el estatus del ultimos mensaje enviado es necesario hacer una solicitud GET en la URL abajo pasando como parámetro el UUID(s) o el correlationId(s) obtenido en la respuesta del envió.

GET https://api-messaging.movile.com/v1/sms/status/search

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

También es posible obtener sólo el estado aún no consultado:

GET https://api-messaging.movile.com/v1/sms/status/list

Observe que este endpoint devuelve sólo el estado que no se devuelve por este punto final.

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 Movile 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 del e-mail support.messaging@movile.com 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 10.000 MOs. Para las fechas anteriores o cantidades mayores por favor entrar en contacto con nuestro equipo de soporte a través del e-mail support.messaging@movile.com

El comportamiento de Query List MO sera diferente para cada usuario autenticado debido al nivel de permisos de cada usuario.

Recomendamos el metodo de envio de los MOs para la API, todo MO enviado será automaticamente enviada para la API ya que de esta forma las respuestas pueden ser tratadas inmediatamente despues de recibidas

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 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.movile.com/v1/sms/receive/list

Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:

GET https://api-messaging.movile.com/v1/sms/receive/list

Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:

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

La solicitud de búsqueda (search request) retornara cada MO recibido en un determinado periodo de tiempo. Usted necesita definir los parámetros START y END para especificar un periodo de tiempo, deberá ser utilizado el formato ISO-8601. START es definido 5 días antes de la fecha actual y END es definido en la fecha actual. No es posible recuperar MOs anteriores a 5 días.

Como um usuario regular, para recuperar todos los MOs de una subcuenta use:

GET https://api-messaging.movile.com/v1/sms/receive/search

Como usuario administrador, para recuperar TODOS los MOs de TODAS las subcuentas use:

GET https://api-messaging.movile.com/v1/sms/receive/search

Como usuario administrador. Para recuperar los MOs de una subcuenta con la referencia “referencia_subcuenta”, use:

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

Busqueda com START e END definidos:

GET https://api-messaging.movile.com/v1/sms/receive/search?start=2016-09-12T00:00:00&end=2016-09-15T00:00:00

Solamente con START especificado (utilizando END estandar, fecha actual)

GET https://api-messaging.movile.com/v1/sms/receive/search?start=2016-09-12T00:00:00

Solamente con END especificado (utilizando START standar, 5 dias antes de la fecha atual)

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

Usado valores estandar para START y END especificando subconta

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

Códigos de Estatus de Envió

Existen dos niveles de estatus, que son enviados independientemente.

1 - Primer estatus (sent_status - Estatus de envió = Callback)

Estatus de entrega en la operadora, este es el primer estatus que retornamos, y todas las operadoras poseen.

Código Mensaje Significado
2 SENT_SUCCESS Entregado en la operadora con éxito (Este es un estatus que debe ser considerado para efecto de cobro.)
101 EXPIRED Expirado antes de ser entregado al aparato.
102 CARRIER_COMMUNICATION_ERROR Error de comunicación con la operadora.
103 REJECTED_BY_CARRIER Operadora rechazo el mensaje.
201 NO_CREDIT El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
202 INVALID_DESTINATION_NUMBER El numero de destino es invalido (No es un numero de celular valido).
203 BLACKLISTED El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
204 DESTINATION_BLOCKED_BY_OPTOUT El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
205 DESTINATION_MESSAGE_LIMIT_REACHED El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
207 INVALID_MESSAGE_TEXT El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.
301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.

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 Grupo Movile 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 e-mail support.messaging@movile.com.

En el caso que sea necesaria la liberación de salida de trafico en su firewall, recomendamos que sea liberado cualquier IP de destino en la puerta 2444. Si esto no es posible, se deberán incluir las siguientes reglas de liberación:


200.219.220.8:2444
200.219.220.193:2444
200.189.169.8:2444
189.36.59.86:2444

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 support.messaging@movile.com.

peer 200.155.0.250
hosts 200.219.220.8 and 200.219.220.193
port 2443

peer 200.143.57.150
hosts 200.189.169.8 and 189.36.59.86
port 2443

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.movile.com
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 201 201 NO_CREDIT El limite de mensajes configurado por el administrador de su empresa, para su cuenta o sub cuenta fue exedido. O, en el caso que su empresa utilice el modelo pre-pago de creditos, este credito acabo.
REJECTD 202 202 INVALID_DESTINATION_NUMBER El numero de destino es invalido (No es un numero de celular valido).
REJECTD 203 203 BLACKLISTED El numero de destino esta en la lista bloqueada, y fue ingresado manualmente por su empresa.
REJECTD 204 204 DESTINATION_BLOCKED_BY_OPTOUT El numero de destino solicito opt-out, y no quiere recibir mas mensajes de esta sub cuenta. (Este estatus es especifico para cuentas de Mobile Marketing).
REJECTD 205 205 DESTINATION_MESSAGE_LIMIT_REACHED El numero de destino ya recibió la cantidad máxima de mensajes que una misma empresa puede enviar, dentro de un periodo de tiempo. (Este estatus es especifico para cuentas de Mobile Marketing, es esta una regla de las operadoras.
REJECTD 207 207 INVALID_MESSAGE_TEXT El texto del mensaje contiene palabras que no son aceptadas por las operadoras. Estas palabras pueden ser de mucha bajeza, o en caso que su cuenta sea de Mobile Marketing, pueden ser de grandes marcas.
REJECTD 301 301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.
UNKNOWN 301 301 INTERNAL_ERROR Ocurrio un error en la plataforma de Movile.

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.movile.com smpp-messaging.movile.com:2444 ssl resolvers dns check inter 15000

$sudo yum install -y openssl-devel haproxy

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

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.movile.com;
  }
  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.movile.com
Puerta 2222
Protocolo SFTP (transferencia sobre ssh, usando criptografía entre cliente-servidor)
Autenticación username + senha (provisto por soporte)
Portal messaging.movile.com

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.movile.com
APIs Consulta en lote /v1/carrier/lookup
Puerta 443 (https)
Protocolo HTTPS (encriptacion TLS)
Autenticacion username + token
Portal messaging.movile.com

Requisicion HTTP Method POST

curl --request POST \
  --url https://api-messaging.movile.com/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.movile.com/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.movile.com/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.movile.com/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.movile.com/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, Movile enviá los mensajes separadamente, sin concatenar incluyendo automáticamente para nuestros clientes, indicadores de orden,

Ex:

Inicio do texto…. (½)

……fin do texto (2/2)


Email API

This API allows you to automatize both single and bulk message requests and the recovery of sent status through its endpoints. It uses HTTP protocol with TLS and accepts GET requests with query string parameters and POST requests with JSON parameters.

User authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters:

Field Details Data Type
UserName Your username or email String
AuthenticationToken Your authentication token. Get yours here String

Connection Details

Hostname api-messaging.movile.com
APIs SendEmail /v1/email/send
SearchEmail /v1/email/status/search
ListEmail /v1/email/status/list
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Portal messaging.movile.com

SendEmail

SendEmail request


curl --request POST \
  --url https://api-messaging.movile.com/v1/email/send \
  --header 'authenticationtoken: <authenticationtoken>' \
  --header 'content-type: application/json' \
  --header 'username: <username>' \
  --data '{
    "fromEmail": "notification@movile.com",
    "fromName": "Notifications",
    "replyTo": "replyTo@movile.com",
    "subject": "Marketing e-mail",
    "campaignAlias": "MyCampaign",
    "recipients": [{
            "correlationId": "1234",
            "emailAddress": "recipient-1@movile.com",
            "emailName": "Recipient-1",
            "extraInfo": "Extra e-mail info1",
            "substitutionData": {
                "name": "Recipient-1"
            }
        },
        {
            "correlationId": "567",
            "emailAddress": "recipient-2@movile.com",
            "emailName": "Recipient-2",
            "extraInfo": "Extra e-mail info2"
        }
    ],
    "emailHtml": "<html> Hi, {{name}}, this is the email HTML body </html>",
    "emailText": "Email text body",
    "substitutionData": {
        "name": "Recipient-1"
    },
    "attachments": [{
        "data": "Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh",
        "name": "billing.pdf",
        "type": "application/pdf"
    }]
}'

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/email/send")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"

response = http.request(request)
puts response.read_body
import requests

url = "https://api-messaging.movile.com/v1/email/send"

payload = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"
headers = {
    'username': "<username>",
    'authenticationtoken': "<authenticationtoken>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/email/send",
  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    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}",
  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;
}

POST https://api-messaging.movile.com/v1/email/send Content-Type: application/json

The body of the request must contain a JSON object in which the information is enveloped with the following fields. *field is required

Field Details Type
fromEmail* Email’s sender address. Ex. notificacion@domain.com String
fromName* Email’s sender name. Ex. Notification. String
replyTo Email address used to compose the email’s “Reply-To” header. String
subject Email subject line. String
campaignAlias Campaign name. String
recipients* Array of recipients.
correlationId Identifier generated by the client. String
emailAddress* Valid email address of a recipient. String
emailName Name of the recipient, associated to the emailAddress String
extraInfo Any extra info set by the user when the email was sent. String
emailHTML HTML content for the email’s text/html MIME part. String
emailText Text content for the email’s text/plain MIME part. String
substitutionData Mapping of tags, within {{}} marks, that should be replaced on html body.
attachments Array of attachment files.
data The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. String
name The filename of the attachment (for example, document.pdf). String
type The MIME type of the attachment; e.g., text/plain, image/jpeg, audio/mp3, video/mp4, application/msword, application/pdf, etc., including the charset parameter (ex: text/html; charset=“UTF-8”) if needed. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment. String

SendEmail response

{
    "id": "abcd-1234-efgh-5678-ijkl-9999",
    "recipients": [
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       },
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       }
    ]
}

The response body will contain a JSON object with tracking information regarding the email request:

Field Details Type
id UUID generated for this email request. String
correlationId The same correlationId from the request. String
recipients Tag corresponding of a id and correlationId for every request recipient.

SearchEmailStatus request

Example:
{
    "correlationIds": ["1234", "5678", "7890"],
    "ids": ["1234-5678-9asd-fghj", "qwer-1234-asdf-0987",
              "zxcv-4567-ghjk-6789"],
    "startDate": "2017-04-27T10:00:00Z",
    "endDate": "2017-04-28T10:00:00Z"
}

POST https://api-messaging.movile.com/v1/email/status/search Content-Type: application/json

Recovers information regarding a previously sent email, given its ids, correlationIds and an interval date.

Field Details Type
ids* UUID generated for this email. Must correspond to the respective correlationId. String
correlationIds The same correlationId from the request. Must corresponds to the respective id. String
startDate Start date for search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
endDate End date to search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String

ListEmailStatus request

POST https://api-messaging.movile.com/v1/email/status/list Content-Type: application/json

Recovers information regarding a previously sent email, given its user and token. This method return all emails that have not been checked yet.

List and Search EmailStatus response

[{
    "recipient": {
        "id": "1234-5678-9asd-fghj",
        "correlationId": "1234",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9638527410,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "qwer-1234-asdf-0987",
        "correlationId": "5678",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "zxcv-4567-ghjk-6789",
        "correlationId": "0987",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}]

Recovers information regarding a previously sent email, given its user and token. This method return all previously unconsulted emails.

Field Details Type
emailStatus Block for each email information.
recipient Block for recipient email information.
id The same id from the request.
correlationId The same correlationId from the request.
emailAddress Email address of the recipient.
emailName Name of the recipient, associated to the emailAddress.
extraInfo Any extra information.
fromEmail Email’s sender address. Ex. notificacion@domain.com
fromName Email’s sender name. Ex. Notification, Not reply, etc.
createdAt When the email was created. It is an Epoch Date. Long
createdDate When the message was created. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
sent Flag indicating if the email was sent. Boolean
sentStatusCode Sent status code. Check Sent Status Codes for more information. Long
sentStatus Sent status. String
sentAt When the email was sent. It is an Epoch Date. Long
sentDate When the email was sent.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
delivered Flag indicating if the email was delivered to the recipient. Boolean
deliveredStatusCode Delivered status code. Check Delivered Status Codes for more information. Long
deliveredStatus Delivered status. String
deliveredAt When the email was delivered. It is an Epoch Date. Long
deliveredDate When the email was delivered. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
open Flag indicating if the email was opened by the recipient. Boolean
openedAt When the email was opened. It is an Epoch Date. Long
openedDate When the email was opened. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
clicked Flag indicating if the email was clicked by the recipient. Boolean
clickedAt When the email was clicked. It is an Epoch Date. Long
clickedDate When the email was clicked by the recipient.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
campaignId Campaign identifier. Long
campaignAlias Campaign name. String

Status Codes

Sent Status Codes

A sent status code represents the status of a message passing through our system and being sent to the carrier.

Success codes

2 SENT_SUCCESS Sent to Movile successfully

Movile error codes

301 INTERNAL_ERROR Movile internal error

Delivered Status Codes

A delivered status code represents the status report that we receive from the server about the email.

Success codes

3 DELIVERED_SUCCESS Delivered to server successfully

Carrier error codes

103 NOT_DELIVERED Email accepted but has not delivered the e-mail.

Opened Status Codes

A open status code represents the e-mail opened by the customer.

Success codes

4 OPENED_SUCCESS Delivered to server successfully

Carrier error codes

104 NOT_OPENED Email accepted but has not opened by the customer

Clicked Status Codes

A clicked status code represents the status report when the customer clicked over the email. |||| |–|–|–| |5|CLICKED_SUCCESS|Clicked by the customer successfully|

Carrier error codes

104 NOT_CLICKED Email accepted but has not clicked by the customer

Fallback API

This API allows you to automatize both single and bulk message requests and the recovery of sent status through its endpoints. It uses HTTP protocol with TLS and accepts GET requests with query string parameters and POST requests with JSON parameters.

User authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters:

Field Details Data Type
UserName Your username or email String
AuthenticationToken Your authentication token. Get yours here String

Connection Details

Hostname api-messaging.movile.com
APIs SendEmail /v1/email/send
SearchEmail /v1/email/status/search
ListEmail /v1/email/status/list
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Portal messaging.movile.com

SendEmail

SendEmail request


curl --request POST \
  --url https://api-messaging.movile.com/v1/email/send \
  --header 'authenticationtoken: <authenticationtoken>' \
  --header 'content-type: application/json' \
  --header 'username: <username>' \
  --data '{
    "fromEmail": "notification@movile.com",
    "fromName": "Notifications",
    "replyTo": "replyTo@movile.com",
    "subject": "Marketing e-mail",
    "campaignAlias": "MyCampaign",
    "recipients": [{
            "correlationId": "1234",
            "emailAddress": "recipient-1@movile.com",
            "emailName": "Recipient-1",
            "extraInfo": "Extra e-mail info1",
            "substitutionData": {
                "name": "Recipient-1"
            }
        },
        {
            "correlationId": "567",
            "emailAddress": "recipient-2@movile.com",
            "emailName": "Recipient-2",
            "extraInfo": "Extra e-mail info2"
        }
    ],
    "emailHtml": "<html> Hi, {{name}}, this is the email HTML body </html>",
    "emailText": "Email text body",
    "substitutionData": {
        "name": "Recipient-1"
    },
    "attachments": [{
        "data": "Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh",
        "name": "billing.pdf",
        "type": "application/pdf"
    }]
}'

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/email/send")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"

response = http.request(request)
puts response.read_body
import requests

url = "https://api-messaging.movile.com/v1/email/send"

payload = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"
headers = {
    'username': "<username>",
    'authenticationtoken': "<authenticationtoken>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/email/send",
  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    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}",
  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;
}

POST https://api-messaging.movile.com/v1/email/send Content-Type: application/json

The body of the request must contain a JSON object in which the information is enveloped with the following fields. *field is required

Field Details Type
fromEmail* Email’s sender address. Ex. notificacion@domain.com String
fromName* Email’s sender name. Ex. Notification. String
replyTo Email address used to compose the email’s “Reply-To” header. String
subject Email subject line. String
campaignAlias Campaign name. String
recipients* Array of recipients.
correlationId Identifier generated by the client. String
emailAddress* Valid email address of a recipient. String
emailName Name of the recipient, associated to the emailAddress String
extraInfo Any extra info set by the user when the email was sent. String
emailHTML HTML content for the email’s text/html MIME part. String
emailText Text content for the email’s text/plain MIME part. String
substitutionData Mapping of tags, within {{}} marks, that should be replaced on html body.
attachments Array of attachment files.
data The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. String
name The filename of the attachment (for example, document.pdf). String
type The MIME type of the attachment; e.g., text/plain, image/jpeg, audio/mp3, video/mp4, application/msword, application/pdf, etc., including the charset parameter (ex: text/html; charset=“UTF-8”) if needed. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment. String

SendEmail response

{
    "id": "abcd-1234-efgh-5678-ijkl-9999",
    "recipients": [
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       },
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       }
    ]
}

The response body will contain a JSON object with tracking information regarding the email request:

Field Details Type
id UUID generated for this email request. String
correlationId The same correlationId from the request. String
recipients Tag corresponding of a id and correlationId for every request recipient.

SearchEmailStatus request

Example:
{
    "correlationIds": ["1234", "5678", "7890"],
    "ids": ["1234-5678-9asd-fghj", "qwer-1234-asdf-0987",
              "zxcv-4567-ghjk-6789"],
    "startDate": "2017-04-27T10:00:00Z",
    "endDate": "2017-04-28T10:00:00Z"
}

POST https://api-messaging.movile.com/v1/email/status/search Content-Type: application/json

Recovers information regarding a previously sent email, given its ids, correlationIds and an interval date.

Field Details Type
ids* UUID generated for this email. Must correspond to the respective correlationId. String
correlationIds The same correlationId from the request. Must corresponds to the respective id. String
startDate Start date for search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
endDate End date to search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String

ListEmailStatus request

POST https://api-messaging.movile.com/v1/email/status/list Content-Type: application/json

Recovers information regarding a previously sent email, given its user and token. This method return all emails that have not been checked yet.

List and Search EmailStatus response

[{
    "recipient": {
        "id": "1234-5678-9asd-fghj",
        "correlationId": "1234",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9638527410,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "qwer-1234-asdf-0987",
        "correlationId": "5678",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "zxcv-4567-ghjk-6789",
        "correlationId": "0987",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}]

Recovers information regarding a previously sent email, given its user and token. This method return all previously unconsulted emails.

Field Details Type
emailStatus Block for each email information.
recipient Block for recipient email information.
id The same id from the request.
correlationId The same correlationId from the request.
emailAddress Email address of the recipient.
emailName Name of the recipient, associated to the emailAddress.
extraInfo Any extra information.
fromEmail Email’s sender address. Ex. notificacion@domain.com
fromName Email’s sender name. Ex. Notification, Not reply, etc.
createdAt When the email was created. It is an Epoch Date. Long
createdDate When the message was created. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
sent Flag indicating if the email was sent. Boolean
sentStatusCode Sent status code. Check Sent Status Codes for more information. Long
sentStatus Sent status. String
sentAt When the email was sent. It is an Epoch Date. Long
sentDate When the email was sent.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
delivered Flag indicating if the email was delivered to the recipient. Boolean
deliveredStatusCode Delivered status code. Check Delivered Status Codes for more information. Long
deliveredStatus Delivered status. String
deliveredAt When the email was delivered. It is an Epoch Date. Long
deliveredDate When the email was delivered. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
open Flag indicating if the email was opened by the recipient. Boolean
openedAt When the email was opened. It is an Epoch Date. Long
openedDate When the email was opened. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
clicked Flag indicating if the email was clicked by the recipient. Boolean
clickedAt When the email was clicked. It is an Epoch Date. Long
clickedDate When the email was clicked by the recipient.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
campaignId Campaign identifier. Long
campaignAlias Campaign name. String

Status Codes

Sent Status Codes

A sent status code represents the status of a message passing through our system and being sent to the carrier.

Success codes

2 SENT_SUCCESS Sent to Movile successfully

Movile error codes

301 INTERNAL_ERROR Movile internal error

Delivered Status Codes

A delivered status code represents the status report that we receive from the server about the email.

Success codes

3 DELIVERED_SUCCESS Delivered to server successfully

Carrier error codes

103 NOT_DELIVERED Email accepted but has not delivered the e-mail.

Opened Status Codes

A open status code represents the e-mail opened by the customer.

Success codes

4 OPENED_SUCCESS Delivered to server successfully

Carrier error codes

104 NOT_OPENED Email accepted but has not opened by the customer

Clicked Status Codes

A clicked status code represents the status report when the customer clicked over the email. |||| |–|–|–| |5|CLICKED_SUCCESS|Clicked by the customer successfully|

Carrier error codes

104 NOT_CLICKED Email accepted but has not clicked by the customer

WhatsApp API

Esta documentación le proporciona información para la integrarse con la plataforma ChatClub para enviar y recibir mensajes a través de la integración WhatsApp de Wavy, así como información para recibir notificaciones de estado (CallBack - WebHook). La plataforma ChatClub permite enviar mensajes simples y masivos de WhatsApp. La API tiene una integración REST, usando el protocolo HTTP con TLS, que admite el método POST con parámetros enviados en formato JSON.

Autenticacion de usuario

Para utilizar con éxito nuestra API, debe disponer de un nombre de usuario o correo electrónico válidos y el token de autenticación asociado. Al crear la solicitud, debe proporcionar los siguientes parámetros en los encabezados:

Campo Detalles Tipo
UserName Nombre o correo electrónico válido para la identificación del usuario en ChatClub. String
AuthenticationToken Token de autenticación generado por nuestra plataforma. Encuéntrelo aquí o consulte a soporte. aquí String

Detalles de la conexión

Nombre del host api-messaging.movile.com
Puerto 443 (https)
Protocolo HTTPS (TLS encryption)
Autenticación username + token
Codificación UTF-8

Enviar mensajes

Envío de mensajes de texto

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

Permite que los mensajes se envíen a través de la plataforma de WhatsApp a uno o más destinatarios.

POST https://api-messaging.movile.com/v1/whatsapp/send

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

Texto:

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
email 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 mensajes HSM

Ejemplo de solicitud HSM

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "ttl": 1,
               "hsm": {
                   "namespace": "namespace",
                   "elementName": "elementName",
                   "parameters":[
                       "MyParam1",
                       "MyParam2"
                   ]
               }
           }
       }

También es posible enviar una base de mensajes en plantillas previamente definidas (también llamado HSM), con la adición de placeholders (“parámetros”). 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 al que se enviará el mensaje (código de país y estado deben estar presentes). Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111. String

Mensaje:

Campo Necesario Detalles Tipo
ttl No Tiempo de vida en días. Define el número máximo de días en que el mensaje debe entregarse. Válido de 1 a 30. Valor predeterminado 7 si no está configurado. long
hsm Si Contenido del mensaje HSM. HSM

HSM:

Campo Necesario Detalles Tipo
namespace Si El espacio de nombres que se usará String
elementName Si El nombre del elemento que indica qué plantilla usar dentro del espacio de nombres String
parameters Si, si la plantilla del mensaje tiene variables Este campo es una matriz de valores para aplicar a las variables en la plantilla String
languagePolicy No Parámetro que identifica cómo se seleccionará el lenguaje HSM. Opciones Disponibles: FALLBACK: Cuando la plantilla de HSM no tenga una versión para el idioma del dispositivo del usuario, se usará el idioma definido. DETERMINISTIC: El mensaje siempre se enviará en el código de idioma, independientemente del idioma en que esté configurado el dispositivo del usuario final. String
languageCode Obligatorio si languagePolicy está presente Código de idioma o configuración regional, acepta ambos formatos: lenguaje (en) o lenguaje_local (es_AR). Para confirmar todos los idiomas disponibles para un HSM en particular, contáctese con nuestro equipo de Soporte. String

Códigos comunes de respuesta de estado HTTP

Respuesta de envio exitoso (200)

Si tiene éxito, se espera una lista de destinatarios (“destinos”) con uuids generados desde el lado de la aplicación:

{
 "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "destinations": [{
  "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "correlationId": "MyCorrelationId",
  "destination": "5519900001111."
}]
}

Respuesta de error de autenticación (401)

Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:

{
  "errorCode": 401,
  "errorMessage": "Authentication Error: No se encontró ningún usuario con esta combinación de nombre de usuario y token de autenticación."
}

Callback de actualización de estado

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
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Para cada actualización sobre el estado de los mensajes enviados (confirmación de entrega al usuario final, lectura de mensajes, etc.), se envíara un Callback / Webhook. Los callbacks se envían por lotes.

IMPORTANTE: El endpoint al que sera enviado el webhook debe configurarse previamente con el equipo de soporte / operaciones.

El formato de esta devolución será de acuerdo a la siguiente descripción:

Campo Detalles Tipo
total Número de callbacks en la llamada. String
data Lista de callbacks. Data[]
clientInfo Información del cliente ClientInfo

Datos:

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 ChatClub 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 ChatClub 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 ChatClub 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

ClientInfo

Campo Detalles Tipo
customerId Identificación del cliente. Number
subAccountId Identificación de la subcuenta. Number
userId Identificación del usuario. Number

MO (Mensajes enviados por el usuario final a la cuenta de Whatsapp)

Ejemplo de mensaje de texto:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5419900000000",
      "origin": "5419900000000",
      "userProfile": {
        "nombre del usuario"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
        "type": "TEXT",
        "messageText": "Hola, este es un mensaje del usuario."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Ejemplo de Extra Info:

{  
   "segmentation_list":[  
      {  
         "id":26,
         "customerId":42,
         "subAccountId":0,
         "name":"Movile WhatsApp Segmentation List",
         "active":true
      },
      {  
         "id":27,
         "customerId":43,
         "subAccountId":0,
         "name":"Movile WhatsApp Segmentation List 2",
         "active":true
      }
   ]
}

Ejemplo de mensaje multimedia

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5419900000000",
      "origin": "5419900000000",
      "userProfile": {
        "nombre del usuario"
      },
      "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": "5419900000000",
      "origin": "5419900000000",
      "userProfile": {
        "nombre del usuario"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
           "location": {
               "geoPoint": "-22.894180,-47.047960",
               "name": "Movile",
               "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": {
        "nombre del usuario"
      },
      "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"
    }
  ]
}

En cada respuesta del usuario final (MO) se envía un Callback / webhook. Estos MO se envían por lotes.

*** IMPORTANTE: *** El endpoint al que se enviará el webhook debe configurarse previamente con el equipo de soporte / operaciones.

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 ChatClub 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

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

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
email 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

API SFTP WhatsApp

Detalle de Conexión

Hostname ftp-messaging.movile.com
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

Para realizar el disparo de mensajes vía FTP es necesario generar un archivo con el formato siguiendo el ejemplo abajo: Mensaje HSM:

2018-10-16;10:00;20:00;HSM;chatclub_welcome;pt_BR;DETERMINISTIC;nome|empresa
telefone;nome;empresa
551999999999;Nome1;Wavy
551999999999;Nome2;Movile

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: HSM
Nombre (elementName) del HSM
Idioma (languageLocale) de HSM
Determinante o Fallback del idioma de HSM (languagePolicy)
Nombre de los parámetros de HSM

** Observaciones para la primera línea: **

1 - Los nombres de los parámetros deben coincidir con los nombres de las columnas

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):; ; ; HSM; chatclub_welcome; es_ES; DETERMINISTIC; nombre | empresa

3 - Por defecto (predeterminado) la languagePolicy será determinante.

4 - Los nombres de los parámetros del HSM deben ser separados por “|” y no por “;”

2ª línea
Nombre de las columnas
3ª y demás líneas:
Destinatario y valores de los parámetros de HSM

Consulta de listas vía API

Solicitud

Usando GET, puede hacer una solicitud enviando todos los parámetros en la query string (cadena de consulta)

GET http://api-messaging.movile.com/v1/list/{listType}?customerId={customerId}&subAccountId={subAccountId}

Tipo de Lista Valor pasado en {listType}
Whatsapp OPT-OUT List OPTOUT
Whatsapp OPT-IN List OPTIN
Whatsapp Blacklist BLACKLIST
Whatsapp Whitelist (para MT) WHITELIST

El parámetro customerId es obligatorio, mientras que el subAccountId es opcional.

Atención: Tenga cuidado de reemplazar ‘{’ y ‘}’ también. Por ejemplo, “{listType}” se convierte en “OPTIN”.

Todavía es necesario pasar los siguientes headers:

Header Valor
Content-Type application/json
authenticationToken Token de Messaging1
userName Nombre de usuario de Messaging1

Puede obtener su nombre de usuario y su token a través de la plataforma Messaging1: https://messaging.movile.com

Respuesta

En caso de éxito, si hay datos asociados al customerId y al subAccountId, la solicitud devuelve un JSON con 3 atributos:

Atributo Valor
success true
status 200
data Link para descargar un archivo de tipo csv que contiene los campos “source” y “createdAt” de todos los destinos encontrados

La columna “createdAt” está en la zona horaria America/Sao_Paulo, UTC-3 o UTC-2 en el horario de verano

En caso de que no haya datos relacionados con customerId y subAccountId, sólo se devuelve un JSON similar, pero sin el campo “data”, lo que significa que no hubo problemas con la solicitud, pero no había datos relativos a los parámetros pasados.

Ejemplo de respuesta:

{
    "success": true,
    "status": 200,
    "data": "https://chatclub-cdn.wavy.global/2019/02/12/f2b8effb-d0bc-4327-86c2-48fedcb01b1b/list-42-4330544192402746957.csv"
}

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.movile.com/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"
}

WhatsApp Groups API

Esta documentación le proporciona información para la integrarse con la plataforma ChatClub para gestionar grupos a través de la integración WhatsApp de Wavy. La API tiene una integración REST, usando el protocolo HTTP con TLS, que admite el método POST con parámetros enviados en formato JSON.

Autenticacion de usuario

Para utilizar con éxito nuestra API, debe disponer de un nombre de usuario o correo electrónico válidos y el token de autenticación asociado. Al crear la solicitud, debe proporcionar los siguientes parámetros en los encabezados:

Campo Detalles Tipo
UserName Nombre o correo electrónico válido para la identificación del usuario en ChatClub. String
AuthenticationToken Token de autenticación generado por nuestra plataforma. Encuéntrelo aquí o consulte a soporte. aquí String

Detalles de la conexión

Nombre del host api-messaging.movile.com
Puerto 443 (https)
Protocolo HTTPS (TLS encryption)
Autenticación username + token
Codificación UTF-8

Envío de mensajes a grupos

Al enviar mensajes a grupos, la solicitud es similar a la de mensajes directos. Sólo el objeto Destino necesita ser adaptado.

POST https://api-messaging.movile.com/v1/whatsapp/send

El cuerpo de la solicitud deve contener los mismos campos de Envío de Mensajes de Texto.

Ejemplo de envío a grupo

        {
          "destinations": [{
            "destination": "5519900000000-1513616971",
            "recipientType": "group"
          }],
          "message": {
            "messageText": "Hola"
          }
        }

MO de Grupo

MOs de grupos contienen los mismos campos que las MOs regulares con la adición de waGroupId que indica a qué grupo se envió el mensaje, como se muestra en el ejemplo.

Ejemplo de mensaje en grupo:

{
  "total": 1,
  "data": [
    {
      "source": "5419900000000",
      "origin": "5419900000000",

      "...",

      "message": {
        "type": "TEXT",
        "messageText": "Hola, este es un mensaje del usuario.",
        "waGroupId": "5519900000000-1553784379"
      },

      "..."
    }
  ]
}

Creación de Grupos

Cree un grupo proporcionando un tema o título para el grupo, que es el nombre que aparecerá en la lista de chat. Como respuesta, recibirá un ID de grupo que utilizará para enviar mensajes al grupo, administrar el grupo, etc.

Solicitud

Ejemplo

        {
           "subject": "tema-de-tu-grupo"
        }

POST https://api-messaging.movile.com/v1/whatsapp/groups

El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:

Campo Necesario Detalles Tipo
subject Si Asunto o título del grupo, limitado a 25 caracteres String

Respuesta

Ejemplo de respuesta

        {
            "groups": [{
                "creation_time": 1513616971,
                "id": "5519900000000-1513616971"
            }]
        }

La respuesta a la solicitud para crear un grupo devuelve una ID de grupo que utilizará para enviar mensajes al grupo, administrar el grupo, etc. Si necesita obtener la ID de grupo en otro momento, consulte la sección Consulta a Todos los Grupos.

Los siguientes campos se devuelven en una respuesta exitosa:

Campo Detalles Tipo
creation_time Hora de creación Integer
id Identificador de grupo para el grupo recién creado. Se debe utilizar para identificar de forma única grupos en solicitudes posteriores, donde se usa group_id. String

Consulta a Todos los Grupos

Recuperar todos los grupos donde el cliente es un participante.

Solicitud

GET https://api-messaging.movile.com/v1/whatsapp/groups

Respuesta

Ejemplo de respuesta

        {
            "groups": [{
                "id": "5519900000000-1513616971"
            }]
        }

La respuesta devuelve los ID de grupo para todos los grupos en los que el cliente es un participante. Puede obtener más información sobre el grupo, como la lista de participantes y el tema del grupo, utilizando la llamada que se describe en la sección Consulta la Información de Grupo.

Los siguientes campos se devuelven en una respuesta exitosa. Si no existe ningún grupo, se devuelve un array JSON de grupos vacío.

Campo Detalles Tipo
id Lista de grupos en los que participa el cliente String

Consulta la Información de Grupo

Utilice esta llamada para obtener información sobre el grupo, incluida la identificación de los participantes y el tema del grupo. Esta llamada no devolverá el icono de grupo. Para obtener el icono de grupo, consulte la sección Consulta al Icono de Grupo.

Solicitud

GET https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id

Respuesta

Ejemplo de respuesta

        {
            "groups": [{
                "admins": [
                    "5519900000000"
                ],
                "creation_time": 1513616971,
                "creator": "5519900000000",
                "id": "5519900000000-1513616971",
                "participants": [
                    "5519900000000"
                ],
                "subject": "tema-de-tu-grupo"
            }]
    }

Los siguientes campos se devuelven en una respuesta exitosa:

Campo Detalles Tipo
admins Administradores del grupo. Enumera los ID del creador del grupo y los administradores agregados como se describe en la sección Agregación de Administradores de Grupo. Array
creation_time Hora de creación del grupo Int
creator ID del creador de este grupo. String
id ID de este grupo String
participants Participantes del grupo. Esto es un array de todas las ID de los participantes en el grupo. Inicialmente, este será el creador del grupo. Invite a los usuarios a agrupar el grupo creando un link de invitación de grupo, como se describe en Creación de Link de Invitación de Grupo. Array
subject Asunto o título del grupo String

Actualización de la Información del Grupo

Actualizar la información es definir un nuevo asunto del grupo.

Solicitud

Ejemplo

        {
           "subject": "nuevo-asunto-del-grupo"
        }

PUT https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id

El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:

Campo Necesario Detalles Tipo
subject Si Actualice el asunto del grupo a este valor, limitado a 25 caracteres String

Respuesta

Una respuesta exitosa retornará 200 OK y null o {}. Si no se encuentra el grupo, la respuesta retornará 404 Not Found.

No puede agregar participantes directamente al grupo. Los participantes solo pueden ser invitados a unirse al grupo. Cree un link que los participantes puedan usar para unirse al grupo.

Solicitud

GET https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/invite

Respuesta

Ejemplo de respuesta

        {
           "groups": [{
               "link": "link-de-invitación-de-grupo"
           }]
        }

Los siguientes campos se devuelven en una respuesta exitosa:

Campo Detalles Tipo
link El link a la invitación del grupo String

Cuando tenga el link para invitar a los participantes a unirse al grupo, envíe el link en un mensaje de texto. Cuando el usuario hace clic en el mensaje, se le invita a unirse al grupo.

Solicitud

DELETE https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/invite

Respuesta

Una solicitud existosa volverá status 200 OK y null o {}. Si no se encuentra el grupo, la respuesta será 404 Not Found.

Eliminación de Participantes del Grupo

Solicitud

Example

        {
           "waIds": [
               "5519900000000",
               "5519900000000"
           ]
        }

DELETE https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/participants

El body de la Solicitud deve contener un objeto JSON con los siguientes campos:

Campo Necesario Detalles Tipo
waIds Si Los números de teléfono de los participantes que dejarán el grupo String[]

Respuesta

Una solicitud existosa retornará status 200 OK y null o {}. Si el número de teléfono no es válido, la respuesta será 404 Not Found o 400 Bad Request.

Dejando un Grupo

Dejar un grupo significa que usted se retirará del grupo, pero seguirá existiendo con sus participantes actuales

Solicitud

POST https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/leave

Respuesta

Una solicitud existosa retornará status 200 OK y null o {}.

Configuración del Icono del Grupo

Solicitud

Example

curl -X POST \
  https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/icon \
  -H 'authenticationToken: <authenticationtoken>'
  -H 'username: <username>' \ 
  -H 'Content-Type: image/jpeg' \
  --data-binary @your-file-path

POST https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/icon Content-Type: image/jpeg u otro tipo apropriado

binary-image-content

Para configurar un icono de un grupo, debe hacer upload de una imagen. La solicitud debe contener los datos binarios de la imagen y el header Content-Type debe configurarse según el tipo de medio que se está cargando.

Respuesta

Una solicitud exitosa retornará status 200 OK y null o {}.

Consulta al Icono de Grupo

Solicitud

GET https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/icon

Respuesta

Ejemplo de Respuesta

{
    "type": "URL",
    "mimeType": "image/jpeg",
    "fileName": "groupIcon.jpeg",
    "extraData": {
        "public": true,
        "Content-Type": "image/jpeg",
        "Content-Length": "2500"
    },
    "data": "https://chatclub-cdn.wavy.global/2019/03/25/ce425ffe-bc62-421f-9261-e6819a5eab43/groupIcon.jpeg"
}

Una respuesta exitosa devolverá el estado 200 OK y un objeto JSON con los siguientes campos. Si el grupo no tiene un icono, la respuesta será 404 Not Found.

Campo Detalles Tipo
type Tipo del campo de datos String
mimeType Tipo MIME del archivo String
fileName Nombre del archivo String
extraData Información sobre el archivo String
data Archivo String

Eliminación de Icono de Grupo

Solicitud

DELETE https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/icon

Respuesta

Una solicitud existosa retornará status 200 OK y null o {}. Si el grupo no tiene un icono, la respuesta será 404 Not Found.

Agregación de Administradores de Grupo

Por defecto, el creador del grupo es solo administrador. Se pueden agregar más administradores con tal que ya sean participantes del grupo. Para verificar los participantes de un grupo, siga los pasos en Consulta La Información de Grupo

Solicitud

Example

        {
           "waIds": [
               "5519900000000",
               "5519900000000"
           ]
        }

PATCH https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/admins

El body de la solicitud debe contener un objeto JSON con los siguientes campos:

Campo Necesario Detalles Tipo
waIds Si Los números de teléfono de los participantes que se tornarán administradores String[]

Respuesta

Una solicitud existosa retornará status 200 OK y null o {}.

Eliminación de administradores de Grupo

Los administradores pueden ser eliminados para que se conviertan en participante regulares. Para verificar los administratores de un grupo, siga los pasos en Consulta La Información de Grupo

Solicitud

Example

        {
           "waIds": [
               "5519900000000"
           ]
        }

DELETE https://api-messaging.movile.com/v1/whatsapp/groups/your-group-id/admins

El body de la solicitud debe contener un objeto JSON con los siguientes campos:

Campo Necesario Detalles Tipo
waIds Si Los números de teléfono de los administradores que se tornarán participantes regulares String[]

Respuesta

Una solicitud existosa retornará status 200 OK y null o {}.


Campaigns API

Este documento proporciona la información necesaria para integrarse con la plataforma de ChatClub 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 ChatClub String
authenticationToken Token de autenticación generado por nuestra plataforma. Encuéntrelo aquí o consulte nuestro soporte. here 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 Enviar un email para support.messaging@movile.com
Telefono +55 (11) 3230-3260