NAV Navbar
cURL Ruby Python PHP Java

en es pt

Introduction

Welcome to our documentation for developers. Here you’ll find everything you need to integrate your business to our messaging platform.

Here are the possible ways of integrating with us:

API HTTPS Allows sending and receiving messages and their statuses over HTTPS protocol, using GET or POST methods
API SMPP Standard protocol for SMS messages exchange, allows a permanent connection to be kept with our SMPP server, its use is encouraged for clients expecting traffic of over 5 million messages per month
API SFTP Protocol used for file transfer, its use is encouraged for mass delivery of messages (bulk). The files are tranfered by the client to our servers and are immediately processed
Websphere MQ Protocol used for transfer of messages between Webserver MQ servers, its use is encouraged for clients with traffic of over 30 million messages per month, specially financial institutions, which the company already has the system in place for internal messages. This integration option has setup and maintenance costs, fixed at R$50.000,00 and R$2.000,00 respectively

You can also visit our Web portal. There, your business is able to manage users, projects and configurations, send and receive messages, and obtain reports, without the need of any development of integration on your side

SMS API

Key Terms

MT Mobile Terminated A message that has a user (device) as destination. That is, a message that was sent by your company to be delivered to a user (device)
Response Synchronous Movile response The immediate answer of a request made to our API, where we let you know whether the message was accepted by our platform, or not
Callback Sent status The first delivery status that we return, where we let you know whether it was possible to deliver the message to the carrier, or not
DR or DLR Delivery Receipt The second delivery status we return, where we let you know whether it was possible to deliver the message to the device, or not. The carriers deliver this information to Movile, and we relay it to the client. The time it takes for a DLR to be delivered varies, for example, if the device was turned off at the moment the MT was sent, and the user only turns it on two hours later, this DLR status will be delivered to the client two hours later.
Obs1: This confirmation of delivery on the device will only exist when the message was successfully delivered to the carrier, that is, only if the first status (Callback) was successful.
Obs2: It is very important to make it clear that sadly, some carriers like OI and Sercomtel do not have this functionality. Therefore, they do not give Movile any information of the message being delivered to devices. The deliveries made to these carriers will only have information of delivery to the carrier (Callback).
MO Mobile Originated A message that has your business as destination, that is, messages that were sent by the user (device). MOs are used, for example, during question and answer flows via SMS, when a confirmation is necessary by the user.
LA Short Code Short number of 5 or 6 digits, used for delivering and receiving SMS messages. They possess anti-fraud and anti-spam rules and carriers only distribute and allow their usage by homologated integrators like Movile

Message Flow

Simplified Flow - MT, Callback, DLR, e MO.

alt text

API HTTPS

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.

Authentication

To send messages and get status through the API, it is necessary to authenticate using a combination of either username or email and and authentication token.

Field Details Data Type
UserName Your username or email String
AuthenticationToken Your authentication token. Get yours here String
Type Details
Administrator Administrator user of your company, it is used to create/edit/deactivate sub accounts and other users, can see reports of the whole company.
This user does not send messages, not through the portal or through the HTTPS API integration.
Regular Regular user used to send messages through the HTTPS API and portal. Can see reports specific to his sub account.
A user is always paired with a single sub account.
A sub account may contain multiple users.
Each sub account is a cost center in our platform, messages will be separated in financial reports by sub account, not by user.

Connection Details

Hostname api-messaging.movile.com
APIs Single message /v1/send-sms
Bulk messages /v1/send-bulk-sms
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Portal messaging.movile.com

Encoding

The standard of encoding is UTF-8, all message texts must follow this standard.

You can also escape special characters or use HTTP format.

You can see some encoding examples besides.

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

You may escape special characters:

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

Sending Messages (MT)

Sending with GET method - 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"}'

<?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;
    }
}

As response, you will receive a JSON informing the id that was generated for this message. (Response or Movile’s synchronous response):

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

Using GET, you can make a message request sending all parameters in the query string.

Single Message GET Request URL

GET https://api-messaging.movile.com/v1/send-sms?destination=..

Using POST, you can make a message request sending all parameters in the body.

Single Message POST Request URL

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

Request Parameters

* Required Field

Field Details Type
destination* Phone to which the message will be sent to (including country code). E.g.: 5511900000000 String
messageText* Message text to be sent (max 1280 chars) String
correlationId A unique ID defined by you for matching with sent statuses (callback and DLR). This parameter is optional, and you can use the ID generated by Movile for the same porpuse (max 64 chars). String
extraInfo Any information you want to add to the message (max 255 chars). String
timeWindow Messages will be sent only during the specified hours. E.g., configuring a time window of [11, 12, 18], the messages will be sent between 11:00 and 11:59, 12:00 and 12:59, and 18:00 and 18:59, this parameter must be added on the root of the JSON object Integer[]
expiresAt Messages will not be delivered after this date. Date format is Unix time . Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) Long
expiresInMinutes Messages will expire after the time set in this field. Time starts to count as soon as the message request is received by Movile. Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) Long
expiresDate The message will not be sent after this date. Date format is yyyy-MM-dd’T'HH:mm:ss. Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) String
scheduledAt Messages will not be delivered before this date. IMPORTANT! Its possible to schedule only a period superior to 30 minutos because scheduled mesasges are processed by a differentiated flow from non scheduled messages. Date format is Unix time . Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) Long
delayedInMinutes Messages will only be sent after the time set on this field. Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) Long
scheduledDate The message will not be sent before this date. Date format is yyyy-MM-dd’T'HH:mm:ss. Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) String
timeZone Specifies the timezone to be used directly on the fields expiresDate, scheduledDate and timeWindow (that will be changed if dynamic timezones are chosen, e.g. Daylight Saving Time). If a timezone is not set on the request, it will use the the timezone of the user - if the user’s timezone is not set as well, it will use the timezone of that user’s country. Last case scenario, UTC timezone will be used. String
campaignAlias Identification of a previously created campaign. You can create a new campaign here String
flashSMS Set this option to true to send a message that pops-up on the user’s device. Boolean
flowId Bot flow identifier. The message text will come from the flow String
subAccount SubAccount reference. It can only be used by Administrators String
params Map of placeholders that will be replaced in the message. If one or more params are incorrect, the message will be marked as invalid, but the bulk will not be canceled. You must use a flowId to pass the parameters Map

Sending Messages with POST - Single and Bulk

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

<?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;
    }
}

As response, you will receive a JSON object with the UUID of the bulk and its individual messages:


{
    "id": "592e6940-31cd-11e7-9369-8e79624807c4",
    "messages": [{
        "id": "592e6941-31cd-11e7-9369-8e79624807c4"
    }, {
        "id": "592e6942-31cd-11e7-9369-8e79624807c4"
    }, {
        "id": "592e6943-31cd-11e7-9369-8e79624807c4"
    }]
}

Allows sending messages, both single and bulk, passing parameters in a JSON object

HTTP Request using POST

JSON example for sending bulk messages

Example 1:

{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    },
    {
      "destination":"5519900003333"
    }
  ],
  "defaultValues":{
    "messageText":"Default message"
  }
}

Example 2:

{
  "messages":[
    {
      "destination":"5519900001111",
      "messageText":"First message"
    },
    {
      "destination":"5519900002222"
    }
  ],
  "timeZone":"America/Sao_Paulo",
  "scheduledDate": "2017-01-28T02:30:43",
  "timeWindow": [12, 15, 20],
  "defaultValues":{
    "messageText":"Default message"
  }
}

Example 3:

{
  "messages":[
    {
      "destination":"5519900001111"
    },
    {
      "destination":"5519900002222"
    }
  ],
  "defaultValues":{
    "messageText":"Default message",
    "flashSMS":"true"
  }
}

Example 4, with flowId and 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 that in the examples above, some of the messages do not have a “messageText”. In these cases, the message text will be the “messageText” field inside “defaultValues”. This feature is useful when it is necessary to send the same message to many different numbers.

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

The request body must contain the JSON object according to the fields below:

* Required Field

Field Details Type
destination* Phone to which the message will be sent to (including country code). E.g.: 5511900000000 String
messageText* Message text to be sent (max 1280 chars). String
correlationId A unique ID defined by you for matching with sent statuses (callback and DLR). This parameter is optional, and you can use the ID generated by Movile for the same porpuse (max 64 chars). String
extraInfo Any information you want to add to the message (max 255 chars). String
timeWindow Messages will be sent only during the specified hours. E.g., configuring a time window of [11, 12, 18], the messages will be sent between 11:00 and 11:59, 12:00 and 12:59, and 18:00 and 18:59 Integer[]
expiresAt Messages will not be delivered after this date. Date format is Unix time . Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) Long
expiresInMinutes Messages will expire after the time set in this field. Time starts to count as soon as the message request is received by Movile. Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) Long
expiresDate The message will not be sent after this date. Date format is yyyy-MM-dd’T'HH:mm:ss. Obs: The fields expiresAt, expiresInMinutes and expiresDate are mutually exclusive (use only one of them) String
scheduledAt Messages will not be delivered before this date. Date format is Unix time . Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) Long
delayedInMinutes Messages will only be sent after the time set on this field. Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) Long
scheduledDate The message will not be sent before this date. Date format is yyyy-MM-dd’T'HH:mm:ss. Obs: The fields scheduledAt, delayedInMinutes and scheduledDate are mutually exclusive (use only one of them) String
timeZone Specifies the timezone to be used directly on the fields expiresDate, scheduledDate and timeWindow (that will be changed if dynamic timezones are chosen, e.g. Daylight Saving Time). If a timezone is not set on the request, it will use the the timezone of the user - if the user’s timezone is not set as well, it will use the timezone of that user’s country. Last case scenario, UTC timezone will be used. String
campaignAlias Identification of a previously created campaign. You can create a new campaign here String
flashSMS Sett this option to true to send a message that pops-up on the user’s device. Boolean
flowId Bot flow identifier. The message text will come from the flow String
subAccount SubAccount reference. It can only be used by Administrators String
params Map of placeholders that will be replaced in the message. If one or more params are incorrect, the message will be marked as invalid, but the bulk will not be canceled. You must use a flowId to pass the parameters Map

Bulk message response

The response of a bulk message request will have a JSON object with the required tracking information. A unique ID will be generated for the bulk as well as for every message. Messages that were sent with a correlationId will have it listed as well.

Field Details Type
id UUID generated for this bulk String
messages This field is an array with the responses of every single message request of the bulk. It contais the id and correlationId of every message sent. SingleSMSResponse[]

HTTP Status Code Response

Status Code of HTTP response common:

Group Description
2xx Success
4xx Client Error
5xx Server Error
Code Description
200 Success
400 Bad request
401 Unauthorized
403 Forbidden
404 Not found
500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout

Sent Status (Callback and DLR)

There are two ways of obtaining the sent status of a message:

As soon as we send a message to the carrier, or as soon as the carrier informs us if it has delivered a message to a device, the information is relayed immediately to you.

The statuses are available for three days, and they can be retrieved using the UUID returned when Movile accepts a message of your company or the correlation ID provided by you to identify the message.
The disadvantage of this option comparing with webhooks is that you may request information on messages that may not yet have been sent to the carrier or to the device, this way, a series of unnecessary requests can be made. E.g.: If a device is turned off when you send it a message, and only turned on two hours later, you may spend two hours making unnecessary requests with its ID. On the other hand, using status through webhook, the information will be delivered to you as soon as it is delivered to the device, without any empty requests.

Status through webhook (delivered to your webservice)

To configure the delivery of Callbacks and DRs (if you have doubts about the terms, check the area Important Terms) first you need to login to Movile messaging at the API configuration area, where using the form, you will be able to configure to which URLs our sent status (Callbacks) and delivered to the device status (DRs) should be delivered to.

It may take up to 10 minutes for the information of the webhook configuration to take effect. After it has, we will call your URLs when the following actions happen:

Action Return status sent
After a message is delivered, or not, to the carrier. Message sent status API (callback)
When a message is delivered, or not, to a user’s device. Delivery report API (DRs)

JSON Message sent status example (callback - delivered to the carrier)

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":"",
}

JSON response fields on Callbacks (sent status)

Fields Description
id UUID for messge reference
correlationId ID provided by you when you send the message
carrierId Carrier Identification
carrierName Carrier Name
destination Phone the message was delivered to
sentStatusCode Status code generated by Movile for the message stating the sent status. Take a look at message status codes for more information
sentStatus Description of the sent status. Take a look at message status codes for more information
sentAt Time the message was sent, using Unix_time format
sentDate Date the message was set. Format: yyyy-MM-dd’T'HH:mm:ssZ
campaignId Campaign Identification if it exists
extraInfo Any other information added by the client during the act of sending the message

JSON response fields on Delivery Reports (DRs)

Field Description
id UUID for messge reference
correlationId ID provided by you when you send the message
carrierId Carrier Identification
carrierName Carrier Name
destination Phone the message was delivered to
sentStatusCode Status code generated by Movile for the message stating the sent status. Take a look at message status codes for more information
sentStatus Description of the sent status. Take a look at message status codes for more information
sentAt Time the message was sent, using Unix_time format
sentDate Date the message was set. Format: yyyy-MM-dd’T'HH:mm:ssZ
deliveredStatusCode Status code generated by Movile for the message stating the delivery status. Take a look at message status codes for more information
deliveredStatus Description of the delivery status. Take a look at message status codes for more information
deliveredAt Time of the delivery, using Unix_time format
deliveredDate Date of the delivery. Format: yyyy-MM-dd’T'HH:mm:ssZ
campaignId Campaign Identification if it exists
extraInfo Any other information added by the client during the act of sending the message

Message Status through HTTP requests

To get the status of the last sent message, you have to make a POST request to the URL below, passing the UUID(s) and/or correlationId(s) returned as response of the send request or the correlationId.

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

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

It is also possible to obtain only the status not yet consulted:

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

Look that this endpoint only returns the statuses that aren’t sent by this endpoint.

Response

JSON fields:

Field Description
id UUID for messge reference
correlationId ID provided by you when you send the message
carrierId Carrier Identification
carrierName Carrier Name
destination Phone the message was delivered to
sentStatusCode Status code generated by Movile for the message stating the sent status. Take a look at message status codes for more information
sentStatus Description of the sent status. Take a look at message status codes for more information
sentStatusAt Time the message was sent, using Unix_time format
sentStatusDate Date the message was set. Format: yyyy-MM-dd’T'HH:mm:ssZ
deliveredStatusCode Status code generated by Movile for the message stating the delivery status. Take a look at message status codes for more information
deliveredStatus Description of the delivery status. Take a look at message status codes for more information
deliveredAt Time of the delivery, using Unix_time format
deliveredDate Date of the delivery. Format: yyyy-MM-dd’T'HH:mm:ssZ
campaignId Campaign Identification if it exists
extraInfo Any other information added by the client during the act of sending the message

JSON Delivery Report Exemple (DR ou DLR - Delivery to a Device)

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

User response (MO)

The MO API alllows automation of the process of retrieving the answers given by users to the messages you sent them. Every request uses the GET method and the responses are sent as JSON objects.

It is also possible to configure a webhook for the MOs to be delivered to as they are received. This is the most efficient way, because it makes it unnecessary to make any requests, only handle the messages as they arrive. For this configuration to be made, it is necessary to open a Ticket with our tech support team sending an email to support.messaging@movile.com including the URL that should receive the MOs.

JSON example sent to your API (POST method)

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

Each request made will return the MOs received during the last 5 days, up to a limit of 10,000 MOs. For previous times of larger quantities, please get in contact with our tech support team through the email support.messaging@movile.com

The behavior of the query List MO will be different for each authenticated user, according to his permission level.

We recommend the method of delivering the MOs to a webhook, every MO will be automatically delivered and can be immediately handled after it is received

Role Permission
Regular Each request made through the MO API will only return the MOs corresponding to the sub account that user belongs to. It is not possible for a regular user to retrieve the MOs of other sub accounts.
Administrator The default behavior for the Administrator user is to recover all MOs from all sub accounts. If an administrator user desires to retrieve the MOs of only one sub account, it is necessary to specify the sub account in the parameter subAccount with the id or reference of the sub account it wishes to recover MOs from.

Default MO response format

JSON response example (Movile API request):

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

Both listing (list) and searching (search) requests return a JSON object with the following fields:

Field Details Type
total Total number of MOs returned by the request Integer
start The minimum limit of the query String
end The maximum limit of the query String
messages A list of the message objects List

Each message object has the following fields:

Field Details Type
id message id String
subAccount subconta responsible for sending the message that generated this MO String
carrierId Carrier ID Integer
carrierName Carrier Name String
source Phone number that sent the MO String
shortCode The shortcode of the message that generated this MO and to which the answer was sent String
messageText Text sent as answer String
receivedAt time message was received Long
receivedDate Date the message was received in UTC format String
campaignAlias Alias da campanha que originou a resposta String
mt MT that generated the message MT

MTs have the following fields

Field Details Type
id Id of the MT String
correlationId correlationID sent on the MT String
username Username of the user responsible of sending the MT String
email Email of the user responsible of sending the MT String

List MO request (list)

The listing request will return all MOs received since the last time this request was made according to the description above. Once this request is made, MOs will be consumed and will not be returned on following calls.

As a regular user, to recover all MOs of a sub account, use:

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

As an administrator user, to recover all MOs from ALL sub accounts, use:

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

As an administrator user, to recover the MOs of a specific sub account with reference “sub_account_reference”, use:

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

A search request will return every MO received in a given time period. You need to define the start and end parameters to specify a time period. Format ISO-8601 must be used. START, as default is defined as 5 days prior to the request time and END, as default is defined as the current date. It is not possible to recover MOs prior to 5 days with this request.

As a regular user, to recover all MOs of a sub account, use:

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

As an administrator user, to recover all MOs of all sub accounts, use:

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

As an administrator user, to recover all MOs of a sub account with reference “sub_account_reference”, use

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

Search specifying START and END:

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

Search only specifying START (using default END, current date)

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

Search only specifying END (using default Start, 5 days prior to current date)

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

Using default values for both START and END and specifying sub account

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

Send Message Status Codes

There are two independently sent status levels.

1 - First status (sent_status - Sent Status = Callback)

Sent status to the carrier, this is the first status we return, supported by all carriers.

Code Message Meaning
2 SENT_SUCCESS Successfully sent to the carrier (This is the status considered for billing purposes.)
101 EXPIRED Expired before being sent to the handset
102 CARRIER_COMMUNICATION_ERROR Communication error with the carrier
103 REJECTED_BY_CARRIER Carrier rejected the message
201 NO_CREDIT The message limit set by the administrator of your business, for you account or sub account, was reached. If you business uses the prepaid charging model, it means you have used all messages you have paid for.
202 INVALID_DESTINATION_NUMBER The destination number is invalid (It is not a valid mobile phone number).
203 BLACKLISTED The destination number is blacklisted, it was manually put into the blacklist by your business.
204 DESTINATION_BLOCKED_BY_OPTOUT The destination number has opted-out of your messages. It no longer wants to receive messages from your sub account. (This status is specific for mobile marketing accounts)
205 DESTINATION_MESSAGE_LIMIT_REACHED The destination number has already received the maximum amount of messages that a single business may send in a given period of time. (This status is specific for Mobile Marketing and it is a rule set by the carriers)
207 INVALID_MESSAGE_TEXT The text of the message contains words that are not accepted by the carrier. It may contain foul language or, if you account is Mobile Marketing, you may be using names of large companies.
301 INTERNAL_ERROR There was an internal error on Movile’s platform

2 - Second status (delivered_status - Delivery Report Callback)

Delivery status to a device, this is the second status we return, and it only exists when the first status cited above was successful, that is, if the message was successfully send to the carrier. In this status we inform whether the message was sent to the device or not. Carriers Oi and Sercomtel do not possess this second status level, for these carriers, we can only return the information of the first status, that is, if the message was delivered to the carrier or not.

Code Message Meaning
4 DELIVERED_SUCCESS Successfully delivered to the device.
104 NOT_DELIVERED The carrier accepted the message but was not able to deliver it to the device. Possible causes:
The device is turned off or out of the service area for a given period of time (normally 24h, but for some carriers, such as Vivo, the trial period if of 8 hours.)
Valid number, but inactive (some carriers return this kind of error only on this second level status).

API SMPP

All services provided by the Movile Group are required to be encrypted. The SMPP protocol does not possess native encryption. Because of that, we provide the two following alternatives for integration:

This is the recommended option. If your system does not possess this functionality, get help on the configuration of a TLS proxy HERE.

Beyond the TLS encryption, access will be authorized only for your server’s the public IP. (We accept multiple IPs and IP ranges) This information must be sent by email to our tech support at support.messaging@movile.com

If there is the need to allow outgoing traffic on your firewall, we recommend to allow any destination IP on port 2444. If this is not possible, you must include rules allowing the addresses below:
200.219.220.8:2444
200.219.220.193:2444
200.189.169.8:2444
189.36.59.86:2444

SMPP over VPN

The encryption and access granting will be made through VPN

If you choose this option, configure the VPNs using the peers and hosts below, already with the phase 1 and 2 proposals you wish. Send the filled in VPN form of your company to 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: For high availability and load balancing, it is required to establish the 2 VPNs above, and to use the domain address smpp-messaging.movile.com as destination in your SMPP client, instead of IPs.

Connection Details

Information Details
Hostname / IP Address smpp-messaging.movile.com
When you configure your SMPP system, it is required to use the domain as destination, instead of IPs.
This domain has 4 entrance proxies with round robin DNS and health check and multiple servers backend. Based on the volume of messages your business will send, we can increase the number o binds(connections) allowed simultaneously.
Port 2444 (SMPP over TLS) or 2443 (VPN)
SMPP Version 3.4
Bind Count The establishment of at least four binds is mandatory for high availability and load balancing. Minimum of 4.
Character Encoding GSM7 - Default (data_coding = 0) (GSM3.38 extended table is not supported by carriers.)
LATIN1 (data_coding = 1)
UCS2 (data_coding=8).
Atention: Check HERE details of characters and billing.
Flash SMS Supported
data_coding=0x10 for GSM7 and data_coding 0x18 for UCS2
When we receive a flashSMS from our customer, it will be sent to the carrier as flashSMS, if the carrier doesn’t accept flashSMS, it will be delivered as a regular SMS.
Enquire-link Minimum: 30 seconds / Maximum: 59 seconds.
Concatenation UDH 8-bit and 16-bit are supported / UDH Headers
Default addr_ton 1
Default addr_npi 1
window size 10
2way Supported
SMPP bind type Transceiver(Recommended). Binding transmit/receiver separately is also accepted.
SMPP system_type MovileSMSC
SMPP source addr (senderID) When your service needs user’s responses (MO), the source address must be equal to the system_id, that is, the name of the user. When there is no need of MOs, you may use anything on this field.
Max MO throughput 80 per bind
Max MT throughput 80 per bind
Server Timezone UTC
ID Format UUID
Default validity_period 24 hours

Send Message Status Codes (Callback e DLR)

1 - First status (sent_status - Sent Status = Callback)

Sent status to the carrier, this is the first status we return, supported by all carriers.

stat err TLV (0x1403) TLV (0x1404) Meaning
ACCEPTD 000 2 SENT_SUCCESS Successfully sent to the carrier. (This is the status considered for billing purposes).
EXPIRED 101 101 EXPIRED Expired before being sent to the handset.
REJECTD 102 102 CARRIER_COMMUNICATION_ERROR Communication error with the carrier.
REJECTD 103 103 REJECTED_BY_CARRIER Carrier rejected the message.
REJECTD 201 201 NO_CREDIT The message limit set by the administrator of your business, for you account or sub account, was reached. If your business uses the prepaid charging model, it means you have used all messages you have paid for.
REJECTD 202 202 INVALID_DESTINATION_NUMBER The destination number is invalid (It is not a valid mobile phone number).
REJECTD 203 203 BLACKLISTED The destination number is blacklisted, it was manually put into the blacklist by your business.
REJECTD 204 204 DESTINATION_BLOCKED_BY_OPTOUT The destination number has opted-out of your messages. It no longer wants to receive messages from your sub account. (This status is specific for mobile marketing accounts).
REJECTD 205 205 DESTINATION_MESSAGE_LIMIT_REACHED The destination number has already received the maximum amount of messages that a single business may send in a given period of time. (This status is specific for Mobile Marketing and it is a rule set by the carriers).
REJECTD 207 207 INVALID_MESSAGE_TEXT The text of the message contains words that are not accepted by the carrier. It may contain foul language or, if your account is Mobile Marketing, you may be using names of large companies.
REJECTD 301 301 INTERNAL_ERROR There was an internal error on Movile’s platform.
UNKNOWN 301 301 INTERNAL_ERROR There was an internal error on Movile’s platform.

2 - Second status (delivered_status - Delivery Report Callback)

Delivery status to a device, this is the second status we return, and it only exists when the first status cited above was successful, that is, if the message was successfully send to the carrier. In this status we inform whether the message was sent to the device or not. Carriers Oi and Sercomtel do not possess this second status level, for these carriers, we can only return the information of the first status, that is, if the message was delivered to the carrier or not.

stat err TLV (0x1403) TLV (0x1404) TLV (0x1405) TLV (0x1406) Meaning
DELIVRD 000 2 SENT_SUCCESS 4 DELIVERED_SUCCESS Successfully delivered to the device.
UNDELIV 104 2 SENT_SUCCESS 104 NOT_DELIVERED The carrier accepted the message but was not able to deliver it to the device. Possible causes:
The device is turned off or out of the service area for a given period of time (normally 24h, but for some carriers, such as Vivo, the trial period if of 8 hours.)
Valid number, but inactive (some carriers return this kind of error only on this second level status).

TLS Proxy - Linux

The proxy is necessary if the connection is not made through a VPN. As previously stated, the SMPP proxy does not possess native TLS encryption, in this case we recommend the proxy below:

HAProxy

HAproxy Configuration

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

Important: Configure your system (SMPP client) to use 127.0.0.1:2444 as destination address

TLS Proxy - Windows

nginx configuration

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;
  }
}

It’s possible to use nginx as a proxy TLS on windows servers to encrypt SMPP data

Download the version below (its important to use this version because earlier versions resolve name on the first request only)

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

Extract the .zip file on the desired place and replace the content on the file conf/nginx.conf with these example configuration.

API SFTP

Connection Details

Hostname ftp-messaging.movile.com
Port 2222
Protocol SFTP (transfer over ssh, providing client-server encryption)
Authentication username + password (supplied by our tech support)
Portal messaging.movile.com

Sending messages through SFTP

To send messages through SFTP, it is necessary to create a TXT file with formatting following the example below:

number;text;correlationId(optional);
5511900000000;message 1;;
5519900000000;message 2;;
5521900000000;message 3;;
EOF

The file name to be sent must have the following format:

<SUB_ACCOUNT_ID>.<DATE(YYYYMMDD)>.<SEQUENCE> or <SUB_ACCOUNT_REFERENCE_NAME>.<DATE(YYYYMMDD)>.<SEQUENCE>

The sub accounts(projects) can be created by the client himself in our portal. If naming above is not followed, the messages will be sent using the clients default sub account

Example:

3486.20170101.01.txt or PROJECT1.20170101.01.txt

After creating the file, it must be sent to our sftp server on the upload directory. The file will be moved to the success directory after its processing is done. If some error happens, the file will be moved to the error directory.

Accents and special characters

Messages that contain only the characters on the table below are charged every 160 characters. If a message contains one or more characters that are not in the table below, the charging is done every 70 characters, according to the specification of the protocol in the carrier network.

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

Observations:

1 - Before using accents and special characters, you musk ask for permission with our tech support

2 - In cases where the destination carrier does not accept accents and special characters (Oi and Sercomtel), our platform does automatic character substitution for their closest not special counterparts, e.g.: á becomes a, and ç becomes c.

Large Texts (concatenation)

Even though the communication protocol used by the carriers has limits of 70 and 160 characters for messages with and without special characters respectively, it is possible to send large texts with the use of concatenation, where the messages are put together by the device when it receives them.

For clients integrated through HTTPS, SFTP or MQ, there is no additional parameter to be set in order to activate concatenation, just sending the whole large message at once is enough.

Clients integrated through SMPP must use the concatenation functionality with indicators on the header (UDH), LINK

It is important to note that even though the message will show up in the devices as a large, single message, the messages are still traveling on the carrier network individually, and in this case, we are still being charged on a per message basis, every 70 of 160 characters (depending on the caracteres used). Remember that when using concatenation some of the characters (70 or 160) are used by the header.

Observation: In cases then the carriers do not support the concatenation feature (Oi and Sercomtel), Movile will send the messsage separately, with no concatenations and will automatically include numbering indicators on the message texts.

E.g.:

Beginning of text…. (½)

……end of text (2/2)

API Carrier Lookup

This API allows you to perform batch queries of numbers, returning the operator that these numbers belongs to and if it’s an invalid number (if a number does not belong to any operator so it is invalid). It uses the HTTP protocol with TLS, and the POST method with parameters in JSON. The query lets you know if a certain number belongs to the operator, but you can not verify if the number is active.

Authentication

To send messages and get status through the API, it is necessary to authenticate using a combination of either username or email and authentication token.

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 Batch request /v1/carrier/lookup
Port 443 (https)
Protocolo HTTPS (TLS encryption)
Authentication username + token
Portal messaging.movile.com

HTTP POST request

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

To perform the query simply add in the body of the request a json with the array of numbers. The number format must contain the country code. Ex Brazil: 5519999999999

Request response

Resposta chamada em formato JSON

{
    "id": "aadb5130-7dd7-11e7-baac-a6aabe61edb5",
    "destinations": [
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "5519997712322",
            "active": true,
            "carrier": {
                "name": "VIVO",
                "countryCode": "BR"
            }
        },
        {
            "destination": "2312312",
            "active": false,
            "carrier": {
                "name": "UNKNOWN"
            }
        }
    ]
}

The last number in the example is an invalid number to demonstrate how the query returns the JSON in these cases.

The batch query response will contain a JSON file with the individual information about each queried number:

Campo Detalhes Tipo
id UUID for messge reference String
destinations This field is an array with the responses of the individual batch queries, contains the id and correlationId of each query number IndividualResponse[]
destination Searched telephone number Long
active status of the operator’s number (currently only check if the number belongs to the operator, not active / in use) Boolean
carrier Operator and country to which the consulted number belongs array[]
name Carrier name String
countryCode countryCode String

Email API

This API allows you to automatize both single and bulk email message requests and the recovery of sent status through its endpoints. It uses HTTP protocol with TLS 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 on the headers:

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

SearchEmail

SearchEmailStatus request

curl --request POST \
  --url https://api-messaging.movile.com/v1/email/status/search \
  --header 'authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF' \
  --header 'content-type: application/json' \
  --header 'username: felipe.cabrini@movile.com' \
  --data '{
    "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"
}'
require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["username"] = 'felipe.cabrini@movile.com'
request["authenticationtoken"] = 'rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF'
request["content-type"] = 'application/json'
request.body = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"

response = http.request(request)
puts response.read_body
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/email/status/search",
  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\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    "content-type: application/json",
    "username: felipe.cabrini@movile.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import requests

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

payload = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"
headers = {
    'username': "felipe.cabrini@movile.com",
    'authenticationtoken': "rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    'content-type': "application/json"
    }

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

print(response.text)

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

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

The response is gonna be a JSON with all the information status about the sent emails, will contain the following fields:

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

Configuring your on domain

To set your domain to send emails through our API you have to open a ticket to our Technical support sending a email to support.messaging@movile.com with the domain you gonna use.

It’s necessary to validate the ownership of that domain so you can use it, so it’s going to be requested the creation of a TXT DNS record with a DKIM key (all information is going to be provided by support team).

Warming UP

IP warming is the process of methodically adding campaign volume week-over-week to a new IP Address to establish a positive sending reputation with Internet Services Providers. (ISPs)

IP Warm-up Plan

During the Warm-up phase the more consistent you are with volume, frequency, complaint and bounce levels, the faster you will establish a positive sending reputation. If you send infrequently, anything less than weekly it will take more time to build a positive sender reputation.

Week 1 Daily Volume Notes
Day 1 200 • During weeks 1-2 send to the most
Day 2 500 active subscribers. 30 days active
Day 3 1,000
Day 4 2,000
Day 5 5,000 • During weeks 3-4 send to 60 days
Day 6 10,000 active subscribers.
Day 7 20,000
Week 2
Day 8 40,000 • Do not send to subscribers that have
Day 9 100,000 note opened or clicked in the past 90 days
Day 10 250,000 during the first 45 days of warm-up.
Day 11 500,000
Day 12 1,000,000
Day 13 2,000,000 • If warming above 5 Million do not send
Day 14 5,000,000 more than double the previous volume.

Fallback API

This API allows you to automatize both single and bulk email message requests and the recovery of sent status through its endpoints. It uses HTTP protocol with TLS 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 on the headers:

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/omni/send
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/omni/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/omni/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/omni/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/omni/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/omni/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.

SearchEmail

SearchEmailStatus request

curl --request POST \
  --url https://api-messaging.movile.com/v1/omni/status/search \
  --header 'authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF' \
  --header 'content-type: application/json' \
  --header 'username: felipe.cabrini@movile.com' \
  --data '{
    "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"
}'
require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/omni/status/list")

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

request = Net::HTTP::Post.new(url)
request["username"] = 'felipe.cabrini@movile.com'
request["authenticationtoken"] = 'rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF'
request["content-type"] = 'application/json'
request.body = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"

response = http.request(request)
puts response.read_body
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/omni/status/search",
  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\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    "content-type: application/json",
    "username: felipe.cabrini@movile.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import requests

url = "https://api-messaging.movile.com/v1/omni/status/search"

payload = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"
headers = {
    'username': "felipe.cabrini@movile.com",
    'authenticationtoken': "rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    'content-type': "application/json"
    }

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

print(response.text)

POST https://api-messaging.movile.com/v1/omni/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

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

The response is gonna be a JSON with all the information status about the sent emails, will contain the following fields:

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

Voice API

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 Type
UserName* Your username or email String
AuthenticationToken* Your authentication token. String

SendVoice request

Endpoint: https://api-messaging.movile.com/v1/voice/send

There are three different ways of sending voice messages through our API:

The request you make will have different json parameters depending on which of the ways you are using:

Common to all requests is a list of destination blocks:

DestinationBlock

Destination Block JSON structure:

{
  "destination": "string",
  "correlationId": "string",
  "extraInfo": "string"
}

*field is required

Field Details Type
destination* The destination number (with DDI) to which the message will be sent. String
correlationId Any correlation id that you wish to correlate the message to. String
extraInfo Any extra info set by the user when the email was sent. String

SendVoice request (Text To Speech)

Send Voice request JSON structure (tts):

{
  "ttsMessage": "string",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
ttsMessage* The text of this message will be transformed into voice. String
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

SendVoice request (Audio Url)

Send Voice request JSON structure (with audio url):

{
  "audioUrl": "string",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
audioUrl* Our system will process the audio file in this url and send it. String
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

SendVoice request (Audio File)

Send Voice request JSON structure (with audio file):

{
  "audioFile": "audio_file_block",
  "destinations": ["destination_block"],
  "campaignAlias": "string"
}

*field is required

Field Details Type
audioFile* And audio file block with the audio information. AudioFileBlock
destinations A list of the destination blocks. [DestinationBlock]
campaignAlias Alias of a previously created campaign that you wish to link this messages to String

AudioFileBlock

Audio File Block JSON structure:

{
  "type": "string",
  "data": "string",
  "name": "string"
}

*field is required

Field Details Type
type* The format of the audio file. E.g. ‘wav’, ‘mp3’. string
data* An audio file encoded as a Base64 string. string
name* The name of the audio file to be shown on the reports. string

SendVoice Response

Send Voice response JSON Structure:

{
  "id": "string",
  "destinations": ["destination_response_block"]
}

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

Field Details Type
id UUID generated for this email request. String
destinations A list of destination response blocks. DestinationResponseBlock

DestinationResponseBlock

Destination Block response JSON Structure:

{
  "id": "string",
  "destination": "string",
  "correlationId": "string",
  "extraInfo": "string"
}

A destination response bock is just the same as a DestinationBlock plus the generated id for that message.

Field Details Type
id UUID generated for this destination request. String
destination The destination number (with DDI) to which the message will be sent. String
correlationId Any correlation id that was sent to be correlated to the message. String
extraInfo Any extra info set by the user when the email was sent. String

SearchVoiceStatus request

Search Voice status request JSON Structure:

{
  "ids": ["string"],
  "correlationIds": ["string"],
  "startDate": "string",
  "endDate": "string"
}

Recovers information regarding a previously sent voice messages, given their ids, correlationIds and an interval date.

Field Details Type
ids* UUID generated for the voice messages. [String]
correlationIds List of correlation ids of the messages being searched for. [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

ListVoiceStatus request

Search Voice status request JSON Structure:

{
  "ids": ["string"],
  "correlationIds": ["string"],
}
Endpoint: https://api-messaging.movile.com/v1/voice/status/list

Recovers information regarding previously sent voice messages, given its user and authentication token. This method return all voice messages that have not been previously returned by a ListVoiceStatus request. It is a convenient method of returning all voice messages whose statuses were received after the last time you checked.

Field Details Type
ids* UUID generated for the voice messages. [String]
correlationIds List of correlation ids of the messages being searched for. [String]

ListVoiceStatus and SearchVoiceStatus response

Search and List Voice Status response JSON structure:

[{
  "destination": "destination_response_body",
  "createdAt": "long",
  "createdDate": "string",
  "sent": "boolean",
  "sentStatusCode": "integer",
  "sentStatus": "string",
  "sentAt": "long",
  "sentDate": "string",
  "answered": "boolean",
  "answeredAt": "long",
  "answeredDate": "string",
  "hungUpAt": "long",
  "hungUpDate": "string",
  "campaignId": "long",
  "campaignAlias": "string"
}]
Field Details Type
destination Destination response block for this destination entry. DestinationResponseBlock
createdAt When the voice message was created. It is an Epoch Date. Long
createdDate When the voice message was created. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
sent Flag indicating if the voice message was sent. Boolean
sentStatusCode Sent status code. Check Sent Status Codes for more information. Long
sentStatus Sent status. String
sentAt When the voice message was sent. It is an Epoch Date. Long
sentDate When the voice message was sent.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
answered Flag indicating if the voice message was answered by the destination. Boolean
answeredAt When the voice message was answered by the destination. It is an Epoch Date. Long
answeredDate When the voice message was answered by the destination. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
hungUpAt When the voice call was hung up. It is an Epoch Date. Long
hungUpDate When the voice call was hung up. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
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

Code Code Name Description
2 SENT_SUCCESS Sent to Movile successfully

Error codes

Code Code Name Description
202 INVALID_DESTINATION_NUMBER Destination number is invalid
206 INVALID_MESSAGE_LENGTH Message text was empty
209 INVALID_CONTENT Error generating audio
401 AUTHENTICATION_ERROR Invalid username/authentication token combination

Movile error codes

Code Code Name Description
301 INTERNAL_ERROR Movile internal error

Carrier error codes

Code Code Name Description
102 CARRIER_COMMUNICATION_ERROR There was a problem communicating with the carrier servers.
103 REJECTED_BY_CARRIER Voice message accepted but has not delivered the e-mail.

WhatsApp API

This documentation provides you with information for the integration with the ChatClub platform for sending and receiving messages through Wavy’s WhatsApp Integration, as well as information for receiving status notifications (CallBack - WebHook). The ChatClub platform allows sending WhatsApp single and bulk messages. The API has REST integration, using the HTTP protocol with TLS, supporting the POST method with parameters sent in JSON format.

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 on the headers:

Field Details Data Type
UserName Name or email valid for user identification on ChatClub. String
AuthenticationToken Authentication token generated by our platform. Find it here or consult the support. here String

Connection Details

Hostname api-messaging.movile.com
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Encoding UTF-8

Send Messages

Sending Text Messages

Text request example

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "messageText": "test message"
            }
        }

Image request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "image": {
                    "type": "JPG",
                    "url": "http://...jpg",
                    "caption": "image description"
                }
            }
        }

Image request example (Base64)

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "image": {
                   "type": "JPG",
                   "data": "ZmlsZQ=="
               }
           }
       }

Audio request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "url": "http://...mp3"
                }
            }
        }

Audio request example (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "data": "ZmlsZQ=="
                }
            }
        }

Document request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "url": "http://...pdf",
                    "caption": "pdf description"
                }
            }
        }

Document request example (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "data": "ZmlsZQ=="
                }
            }
        }

Location request example

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "location": {
                    "geoPoint": "-22.894180,-47.047960",
                    "name": "Wavy",
                    "address": "Av. Cel. Silva Telles"
                }
        }

Contacts request example

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

Group request example

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

Allows messages to be sent through the WhatsApp platform to one or more recipients.

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
destinations Yes List of recipients Destination[]
message Yes Text message that will be sent to the recipient list Message
flowId No Bot flow identification String
defaultExtraInfo No Additional data that identifies the submission will be linked to all recipients who will receive the message String
campaignAlias No Campaign ID, is linked to all sending messages String

Destination:

Field Required Details Type
correlationId No Your defined id will be returned in a confirmation message (callback). This is useful in cases where you want to keep track of the sent message, since you can define different ids for different messages. String
destination Yes Either the phone number (country code — 55 for Brazil — and state must be present) or the WhatsApp group ID to which the message will be sent. Examples:5519900001111, +5519900001111, +55(19) 900001111. String
recipientType No Must be either "individual" or "group", depending on whether the destination is a phone number or a group id. Default value is "individual" String

Message:

Field Required Details Type
messageText Yes field used for in case you want to send a personalized message in response to a received message. text
image Yes Field used for in case you want to send an image content. Image
audio Yes Field used for in case you want to send an audio content. Audio
document Yes Field used for in case you want to send an document file. Document
contacts Yes Field used for in case you want to send contact(s). Contact[]
previewFirstUrl No Control the app’s preview of first URL sent Boolean
location Yes Field used for in case you want to send a location. Location

Text:

Image:

Field Required Details Type
type Yes Type/extention of the image to be sent in the message. Available options: JPG, JPEG, PNG. String
caption No Text to be presented to the user under the image in Whatsapp String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Audio:

Field Required Details Type
type Yes Type/extension of the audio to be sent in the message. Available options: AAC, MP4, AMR, MP3, OGG. String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Document:

Field Required Details Type
type Yes Type/extention of the document to be sent in the message. Available options: PDF. String
caption No Text to be presented to the user under the document in Whatsapp String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Contact:

Field Required Details Type
addresses No Full contact address(es). Address[]
birthday No Birthday date as YYYY-MM-DD formatted string. String
emails No Contact email address(es). Email[]
name No Full contact name. Name
org No Contact organization information. Org
phones No Contact phone number(s). Phone[]
urls No Contact URL(s). Url[]

Address:

Field Required Details Type
street No Street number and name. String
city No City name. String
state No State abbreviation. String
zip No ZIP code. String
country No Full country name. String
country_code No Two-letter country abbreviation. String
type No Standard Values: HOME, WORK. String

Email:

Field Required Details Type
email No Email address. String
type No Standard Values: HOME, WORK. String

Name:

Field Required Details Type
first_name No First name. String
last_name No Last name. String
middle_name No Middle name. String
name_suffix No Name suffix. String
name_prefix No Name prefix. String
formatted_name No Full name as it normally appears. String

Org:

Field Required Details Type
company No Name of the contact’s company. String
department No Name of the contact’s department. String
title No Contact’s business title. String

Phone:

Field Required Details Type
phone No Formatted phone number. String
type No Standard Values: CELL, MAIN, IPHONE, HOME, WORK. String
wa_id No WhatsApp ID. String

Url:

Field Required Details Type
phone No Contact URL. String
type No Standard Values: HOME, WORK. String

Sending HSM messages

HSM Request Example

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

It is also possible to send message base in previously defined templates (also called HSM), with addition of placeholders (“parameters”). The request body must contain a JSON object with the following fields:

Field Required Details Type
destinations Yes List of recipients Destination[]
message Yes Text message that will be sent to the recipient list Message
flowId No Bot flow identification String
defaultExtraInfo No Additional data that identifies the submission will be linked to all recipients who will receive the message String
campaignAlias No Campaign ID, is linked to all sending messages String

Destination:

Field Required Details Type
correlationId No Your defined id will be returned in a confirmation message (callback). This is useful in cases where you want to keep track of the sent message, since you can define different ids for different messages. String
destination Yes Telephone number to which the message will be sent (country code (55 for Brazil) and state must be present).Examples:5519900001111, +5519900001111, +55(19) 900001111. String

Message:

Field Required Details Type
ttl No Time to live in days. Defines the maximum number of days that the message should be delivered. Valid from 1 to 30. Default value 7 if not set. long
hsm Yes HSM message content. HSM

HSM:

Field Required Details Type
namespace Yes The namespace that will be used String
elementName Yes The element name that indicates which template to use within the namespace String
parameters Yes, if the message template has variables This field is an array of values to apply to variables in the template String[]
languagePolicy No Parameter that identifies how the HSM language will be selected. Available options:FALLBACK: When the HSM template does not have a version for the language to user’s device, the defined language will be used. DETERMINISTIC: The message will always be sent in the languageCode, regardless of the language the end user device is set to. String
languageCode Mandatory if languagePolicy is present Language code or locale, accepts both formats: language (en) or language_locale (pt_BR). To confirm all available languages ​​for a particular HSM, contact our Support team. String

Common HTTP Status Code Response

Successful request response (200)

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

If successful, a list of recipients (“destinations”) with uuids generated from the application side is expected:

Authentication error response (401)

{
  "errorCode": 401,
  "errorMessage": "Authentication Error: No user was found with this combination of username and authentication token."
}

If there is a problem in user authentication, the following error message is expected:

Status Update Callback

Example

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Each update on the status of sent messages (delivery confirmation to the end user, message reading, etc.), a callback/webhook is sent. Callbacks are sent in batch.

IMPORTANT: The endpoint in which the webhook will be sent must be previously configured with the support / operations team.

The format of this return will be according to the following description:

Field Details Type
total Number of callbacks in the call. String
data Callback list. Data[]
clientInfo Client Information ClientInfo

Data:

Field Details Type
id Last message id. String
correlationId A unique ID set by you to match with the message status (callback and DLR). This parameter is optional, and you can use the ID generated by ChatClub for this matching. String
destination Phone to which the message was sent (including country code). Example: 5511900000000. String
origin Phone that identifies the WhatsApp Account (including country code). Example: 5511900000000. String
campaignId Previously defined campaignID. String
campaignAlias Previously defined Campaign alias. String
extraInfo Extra information sent with the original message. String
sent Indicates whether the message was sent. Boolean
sentStatusCode Status code generated by the ChatClub for message indicating the sending status. Number
sentStatus Sent status description. Boolean
sentDate Date the message was sent. Format: yyyy-MM-dd’T'HH:mm:ssZ. String
sentAt Time when the message was sent, using Unix_time format Number
delivered Indicates whether the message was delivered to the destination. Boolean
deliveredStatusCode Status code generated by the ChatClub for message indicating the message was delivered. Number
deliveredStatus Delivery status description. String
deliveredDate Date the message was delivered. Format:: yyyy-MM-dd’T'HH:mm:ssZ String
deliveredAt Time when the message was delivered, using Unix_time format Number
read Indicates whether the message was read by the destination. Boolean
readDate Date the message was read. Format: yyyy-MM-dd’T'HH:mm:ssZ String
readAt Time when the message was read, using Unix_time format String
updatedDate Date the message status was updated. Format: yyyy-MM-dd’T'HH:mm:ssZ String
updatedAt Date when the message status was updated, using Unix_time format String

ClientInfo

Field Details Type
customerId Client identification. Number
subAccountId Subaccount identification. Number
userId User identification. Number

MO (messages sent by the end user to the Whatsapp Account)

Text Message example:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "userProfile": {
        "name": "name of the user"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
        "type": "TEXT",
        "messageText": "Hi, this is a message from the user"
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Extra Info example:

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

Media Message example

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",      
      "userProfile": {
        "name": "name of the user"
      },
      "campaignId": 100,
      "correlationId":"...",
      "campaignAlias":"...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "IMAGE",
           "mediaUrl": "https://...",
           "mimeType": "image/jpg",
           "caption": "..."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Location message example:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",      
      "userProfile": {
        "name": "name of the user"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
           "location": {
               "geoPoint": "-22.894180,-47.047960",
               "name": "Wavy",
               "address": "Av. Cel. Silva Telles"
           }
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Contacts message example:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",      
      "userProfile": {
        "name": "name of the user"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "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"
    }
  ]
}

At each end-user response (MO or Mobile Originated) a callback/webhook is sent. These MOs are sent in batch.

IMPORTANT: The endpoint in which the webhook will be sent must be previously configured with the support / operations team.

The format of this return will be according to the following description:

Field Details Type
total Number of callbacks in the call. String
data List of Mobile Originated messages. Data[]
Field Details Type
id Last message identification String
source ID of the sender String
origin Phone that identifies the WhatsApp Account (including country code). Example: 5511900000000. String
userProfile Profile of the user who sent the message UserProfile
correlationId A unique ID set by you to match with the message status (callback and DLR). This parameter is optional, and you can use the ID generated by ChatClub for this matching. String
campaignId Previously defined campaignID. String
campaignAlias Previously defined Campaign alias. String
message MO message. Message
receivedAt Date the message was received. Format: yyyy-MM-dd’T'HH:mm:ssZ String
receivedDate Date when the message was received, using Unix_time format String
extraInfo Extra information related to the message. Format: Json String

MO Flow Control - Segmentation Lists

The message will have a list of segmentations lists in the extraInfo field. Our partners use it to redirect the messages through certain flows. The key’s name is segmentation_lists and it contains a list of SegmentationList.

Field Details Type
id Segmentation list identifier Integer
customerId Customer identifier Integer
subAccountId SubAccount identifier Integer
name Segmentation list name String
active Segmentation list status Boolean

Message:

Field Details Type
type Type of message sent by the end user: TEXT - IMAGE - AUDIO - DOCUMENT String
messageText The text message (MO) sent by the end user. String
waGroupId The group to which the message was sent. String
mediaUrl Url to download the media sent by the end user. String
mimeType Mime type of the file sent by the end user. String
caption Media label sent by end user. String
location Location sent by end user. Location
contacts Contact(s) sent by end user. Contact[]

UserProfile:

Field Required Details Type
name No Profile name of the user String

Location:

Field Details Type
name Name of the location. String
address Address of the location. String
geoPoint Geopoint sent by end user. Format: “latitude,longitude” String

Contact:

Field Required Details Type
addresses No Full contact address(es). Address[]
birthday No Birthday date as YYYY-MM-DD formatted string. String
emails No Contact email address(es). Email[]
name No Full contact name. Name
org No Contact organization information. Org
phones No Contact phone number(s). Phone[]
urls No Contact URL(s). Url[]

Address:

Field Required Details Type
street No Street number and name. String
city No City name. String
state No State abbreviation. String
zip No ZIP code. String
country No Full country name. String
country_code No Two-letter country abbreviation. String
type No Standard Values: HOME, WORK. String

Email:

Field Required Details Type
email No Email address. String
type No Standard Values: HOME, WORK. String

Name:

Field Required Details Type
first_name No First name. String
last_name No Last name. String
middle_name No Middle name. String
name_suffix No Name suffix. String
name_prefix No Name prefix. String
formatted_name No Full name as it normally appears. String

Org:

Field Required Details Type
company No Name of the contact’s company. String
department No Name of the contact’s department. String
title No Contact’s business title. String

Phone:

Field Required Details Type
phone No Formatted phone number. String
type No Standard Values: CELL, MAIN, IPHONE, HOME, WORK. String
wa_id No WhatsApp ID. String

Url:

Field Required Details Type
phone No Contact URL. String
type No Standard Values: HOME, WORK. String

API SFTP WhatsApp

Detalhes de conexão

Hostname ftp-messaging.movile.com
Port 2222
Protocol SFTP (transfer over ssh, providing client-server encryption)
Authentication username + password (supplied by our tech support)

Sending messages through SFTP

To send messages through SFTP, it is necessary to create a TXT file with formatting following the example below:

HSM Message:

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

1st Line
Send Date (for scheduling cases)
Initial sending time (for scheduling cases)
Final sending time (for scheduling cases)
Message type should be: HSM
Name (elementName) of HSM
Language (languageLocale) of HSM
Deterministic or Fallback of the language of HSM (languagePolicy)
name of HSM parameters

Observation for first line:

1 - Parameter names must match the column names

2 - Information that is not to be used can be left blank, but should keep the semicolon as separation. Example of a case that we do not use scheduling (initial fields are between semicolons and no information inside):; ; ; HSM; chatclub_welcome; pt_BR; DETERMINISTIC; name | company

3 - By default the languagePolicy will be Deterministic.

4 - HSM parameter names must be separated by “|” and not by “;”

2nd Line
Column name
3rd and further lines:
Recipient and parameter values of HSM

Consulting lists via API

Request

Using GET, you can make a request sending all parameters in the query string.

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

List Type Value passed as {listType}
Whatsapp OPT-OUT List OPTOUT
Whatsapp OPT-IN List OPTIN
Whatsapp Blacklist BLACKLIST
Whatsapp Whitelist (for MT) WHITELIST

Passing the parameter customerId is mandatory, while subAccountId is optional.

Attention: Be careful to replace ‘{’ and ‘}’ too. For example, “{listType}” becomes “OPTIN”.

You will also need to use the following headers:

Header Value
Content-Type application/json
authenticationToken Messaging1 token
userName Messaging1 username

You can obtain your userName and token through out Messaging1 platform: https://messaging.movile.com

Response

On success, if there is data related to the customerId and subAccountId, the request will return a JSON with 3 attributes

Field Value
success true
status 200
data Link to download a csv file containing the columns “source” and “createdAt” of all found destinations

The column “createdAt” is at America/Sao_Paulo timezone, UTC-3 or UTC-2 in Daylight Saving Time

In case there is no data related to the customerId and subAccountId, a similar JSON will be returned, but without the “data” attribute, meaning that there were no errors with the request but no data was found.

Response example:

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

Consulting open sessions via API

Request

To consult open sessions via our API, you need to do GET request to the following address:

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

Passing the parameter customerId is mandatory, while subAccountId is optional.

Attention: Be careful to replace ‘{’ and ‘}’ too. For example, “={customerId}” becomes “=42”.

You will also need to use the following headers:

Header Value
Content-Type application/json
authenticationToken Messaging1 authentication token
userName Messaging1 username

Response

On success, if there are open sessions for the specified customerId and subAccountId, the request will return a JSON with the attribute:

Field Value
file_url Link to download a file of type csv containing the fields “source” and “session_created_at” of all the found destinations

If there is no data associated with customerId and subAccountId, the returned file is empty, with only the header.

Response example:

{
    "file_url": "https://chatclub-cdn.wavy.global/2019/02/13/633e33fc-3a3f-4ca5-a8b0-4b747fb67137/5bd46e2b-5990-4681-9b29-98ab6598960e"
}

WhatsApp Groups API

This documentation provides you with information for the integration with the ChatClub platform for managing groups through Wavy’s WhatsApp Integration. The API has REST integration, using the HTTP protocol with TLS, supporting the POST method with parameters sent in JSON format.

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 on the headers:

Field Details Data Type
UserName Name or email valid for user identification on ChatClub. String
AuthenticationToken Authentication token generated by our platform. Find it here or consult the support. here String

Connection Details

Hostname api-messaging.movile.com
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Encoding UTF-8

Sending Group Messages

When sending group messages, the request is similar to that of a direct message. Only the Destination object needs to be adapted.

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

The body of the request must contain the same fields shown in Sending Text Messages.

Group request example

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

Group MO

Group MOs contain the same fields as regular MOs with the addition of waGroupId indicating to which group the message was sent, as shown in the example.

Group Message example:

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

      "...",

      "message": {
        "type": "TEXT",
        "messageText": "Hi, this is test message",
        "waGroupId": "5519900000000-1553784379"
      },

      "..."
    }
  ]
}

Creating Groups

Create a group by providing a subject or title for the group, which is the name that will appear in the chat list. In response, you will receive a group ID that you will use to send messages to the group, manage the group, etc.

Request

Example

        {
           "subject": "your-group-subject"
        }

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
subject Yes Subject or title of the group, limited to 25 characters String

Response

Response example

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

The response to the request to create a group returns a group ID that you will use for sending messages to the group, managing the group, etc. If you need to get the group ID at another time, see the Retrieving All Groups section.

The following fields are returned in a successful response:

Field Details Type
creation_time Creation time Integer
id Group identifier for the newly created group. Must be used to uniquely identify groups in subsequent requests, where group_id is used. String

Retrieving All Groups

Retrieve all groups where the client is a participant.

Request

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

Response

Response example

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

The response returns the group IDs for all groups where the client is a participant. You can get more information about the group, such as the list of participants and the subject of the group, using the call described in the Retrieving Group Information section.

The following fields are returned in a successful response. If no groups exist, an empty groups JSON array is returned.

Field Details Type
id List of groups that client participates in String

Retrieving Group Information

Use this call to get information about the group, including the ID of the participants, and the subject of the group. This call will not return the group icon. To get the group icon, see the Getting the Group Icon section.

Request

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

Response

Response example

        {
            "groups": [{
                "admins": [
                    "5519900000000"
                ],
                "creation_time": 1513616971,
                "creator": "5519900000000",
                "id": "5519900000000-1513616971",
                "participants": [
                    "5519900000000"
                ],
                "subject": "your-group-subject"
            }]
    }

The following fields are returned in a successful response:

Field Details Type
admins Group administrators. Lists IDs of the creator of the group and any administrators added as described in the Adding Group Admins section. String[]
creation_time Group creation time Int
creator ID of the creator of this group String
id ID of this group String
participants Participants of the group. This is an array of all the IDs of the participants in the group. Initially, this will be the creator of the group. Invite users to group the group by creating a group invite link, as described in the Creating Group Invite Link. String[]
subject Subject of the group String

Updating Group Information

Update information is set a new group subject.

Request

Example

        {
           "subject": "new-group-subject"
        }

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
subject Yes Update the group subject to this value, limited to 25 characters String

Response

A successful response will return status 200 OK and either null or {}. If the group is not found, the response will be 404 Not Found.

You cannot add participants directly to the group. Participants can only be invited to join the group. Create a link participants can use to join the group.

Request

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

Response

Response example

        {
           "groups": [{
               "link": "group-invite-link"
           }]
        }

The following fields are returned in a successful response:

Field Details Type
link The link to the group invite String

When you have the link to invite participants to join the group, send the link in a text message. When the user clicks on the message, they are invited to join the group.

Request

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

Response

A successful response will return status 200 OK and either null or {}.

Removing Group Participants

Request

Example

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

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
waIds Yes The WhatsApp IDs of the participants to remove from the group String[]

Response

A successful response will return status 200 OK and either null or {}. If the phone number is not found, the response will be either 404 Not Found or 400 Bad Request.

Leaving a Group

Leaving a group means that you are removing yourself from the group participants list. The group will continue to exist with the remaining participants.

Request

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

Response

A successful response will return status 200 OK and either null or {}. If the user making the request is not a participant of the group, the response will be status 404 Not Found.

Setting the Group Icon

Request

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 or other appropriate type

binary-image-content

To set an icon of a group, you must upload image file. The request must contain the binary image data and the Content-Type header must be set to the type of the media being uploaded.

Response

A successful response will return status 200 OK and either null or {}.

Getting the Group Icon

Request

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

Response

Response example

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

A successful response will return status 200 OK and a JSON object with the following fields. If an icon is not set for the group, the response will be 404 Not Found.

Field Details Type
type Type of the data field String
mimeType MIME type of the file String
fileName File name String
extraData File information String
data File String

Deleting the Group Icon

Request

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

Response

A successful response will return status 200 OK and either null or {}. If the group doesn’t have an icon, the response will be 404 Not Found.

Adding Group Admins

By default, the original group creator is it’s only admin. Other admins can be added to te group as long as they already are participants. To see who is listed as an administrator of a group, follow the steps in Retrieving Group Information.

Request

Example

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

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
waIds Yes The phone numbers of the participants to be turned into admins String[]

Response

A successful response will return status 200 OK and either null or {}.

Removing Group Admins

To remove someone as the administrator of a group, use the admins endpoint. To see who is listed as an administrator for a group, follow the steps in Retrieving Group Information.

Request

Example

        {
           "waIds": [
               "5519900000000"
           ]
        }

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

The request body must contain a JSON object with the following fields:

Field Required Details Type
waIds Yes The WhatsApp IDs of the people to be removed as group admins String[]

Response

A successful response will return status 200 OK and either null or {}.


Campaigns API

This document provides the information needed to integrate with the ChatClub platform to perform campaign management. The API has REST integration, using HTTP protocol with TLS, supporting the POST methods with the parameters sent in JSON format.

Authentication

To successfully use our API, you must provide a valid username (email) associated with an authentication token. You must add the following headers to the request:

Field Details Data Type
userName Valid e-mail subscribed in ChatClub Platform String
authenticationToken Authentication token generated by our platform. Find it here or check our support. here String

Connection details

Hostname apigw.wavy.global
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authorization username + token
Encoding UTF-8

Listing campaigns

Listing campaigns example

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

Response

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

List of campaigns already registered in the platform. You can page results or filter by campaign name. GET https://apigw.wavy.global/api/v1/campaigns

QueryString parameters

* Requeried fields

Field Details Data type
name Campaign’s name to be used as a filter String
page Requested page to be listed Integer
page_size Records per page Integer

Requesting for a specific campaign

Requesting specific campaign example

curl -X GET \
  https://apigw.wavy.global/api/v1/campaigns/1234 \
  -H 'Content-Type: application/json' \
  -H 'authenticationToken: <authentication_token>' \
  -H 'userName: <e-mail>'

Response

{
    "status": {
        "error": false
    },
    "campaign": {
        "name": "My Campaign",
        "id": 1234,
        "alias": "mycampaign"
    }
}

Requesting a specific campaign by id

GET https://apigw.wavy.global/api/v1/campaign/{id}

Creating campaigns

Creating campaign example:

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

Response

{
    "status": {
        "error": false
    },
    "campaign": {
        "name": "My Campaign",
        "id": 1234,
        "alias": "mycampaign"
    }
}

Create a new campaign with name and alias. The campaign alias should be a simple name to make it easier to use with the API. It is recommended to be short and do not use special characters.

POST https://apigw.wavy.global/api/v1/campaigns

JSON Object

* Required fields

Field Details Data type
name* Campaign name String
alias Campaign identifier. To be used when send messages. String

Changing campaigns

Changing campaign example:

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

Response

{
    "status": {
        "error": false
    },
    "campaign": {
        "name": "My Campaign",
        "id": 1234,
        "alias": "mycampaign"
    }
}

Change a campaign by modifying the name and / or alias.

PUT https://apigw.wavy.global/api/v1/campaigns/{id}

JSON Object

* Required fields

Field Details Data type
name* Campaign name String
alias Campaign identifier. To be used when send messages. String

Deleting campaigns

Deleting campaign example:

curl -X DELETE \
  https://apigw.wavy.global/api/v1/campaigns/1234 \
  -H 'Content-Type: application/json' \
  -H 'authenticationToken: <authentication_token>' \
  -H 'userName: <e-mail>'

Response

{
    "status": {
        "error": false
    },
    "campaign": {
        "name": "My Campaign",
        "id": 1234,
        "alias": "mycampaign"
    }
}

Deleting a campaign by id

DELETE https://apigw.wavy.global/api/v1/campaigns/{id}

Support

Opening Tickets Send an email to support.messaging@movile.com
Phone Number +55 (11) 3230-3260