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

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 Request URL

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

Query String Parametes

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

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

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

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[]

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)

Support

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

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