Registration

Module Message

Creation, sending, and other functions for handling individual messages (not campaigns).

API methods

Retrieving SMS Delivery Status Report
https://api.mobizon.com.br/service/Message/GetSMSStatus

Getting List of SMS Messages
https://api.mobizon.com.br/service/Message/List

Sending a Single SMS Message
https://api.mobizon.com.br/service/Message/SendSmsMessage

Retrieving SMS Delivery Status Report

https://api.mobizon.com.br/service/Message/GetSMSStatus

This method allows you to retrieve the current delivery status of one or more SMS messages.

Regardless of the type of input parameter, the returned result is always presented as an array.

If non-existent or unauthorized message identifiers are passed, the result will not contain information about these messages.

Request Parameters

ParameterTypeDescription
idsarray stringMessage identifier(s).
An array or a string of identifiers separated by commas.
Maximum number of identifiers in one request is 100.

Server Response

FieldTypeDescription
idintegerMessage identifier.
statusstringMessage status.
See the table List of Possible Message Statuses.
segNumintegerNumber of segments in this message.
startSendTsstringTime the message sending started.
Format: YYYY-MM-DD HH-MM-SS.
If the message has not been sent yet, the field value will be NULL.
statusUpdateTsstringTime of the last status update of the message.
Format: YYYY-MM-DD HH-MM-SS.
If the message has not been sent yet, the field value will be NULL.

API Response Codes

CodeDescription
0Delivery status report successfully retrieved.
2If no message identifiers are specified.
12If more than 100 message identifiers are specified.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988'
var data = "ids%5B0%5D=123&ids%5B1%5D=556&ids%5B2%5D=988";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.com.br/service/message/getSMSStatus?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php
use Mobizon\MobizonApi;

$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');

// API method call
if ($api->call(
    'message',
    'getSMSStatus',
    array(
        //message identifiers
        'ids' => array(
            '123',
            '556',
            '988'
        )
    )
)
) {
    // Getting the result of an API request
    $result = $api->getData();
} else {
    // An error occurred during execution. Error code and message text output
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Getting List of SMS Messages

https://api.mobizon.com.br/service/Message/List

This method allows you to get a list of created SMS messages.

The search can be performed by ID and campaign fields.

Request Parameters

ParameterTypeDescription
criteriaarraySearch criteria (see the table Search Criteria).
paginationarrayPagination parameters (see the table Pagination Parameters).
sortarraySorting parameters (see the table Sorting Parameters).
withNumberInfointegerThis parameter allows you to get additional information about the recipient's number from the server, such as "country" and "operator".
Possible values:
0 – do not get (default);
1 – get.

Search Criteria

Information about the fields of the SMS message by which the search is performed. The search can be done by one field or multiple fields simultaneously.

ParameterTypeDescription
criteria[campaignIds]array \ stringSearch by campaign identifiers.
The parameter must be passed as an array or a string of comma-separated identifiers.
The maximum number of identifiers is 100; if this limit is exceeded, the search will be performed for the first 100 IDs from the list.
criteria[from]stringSearch by sender ID.
The search is performed by the sender ID created in the campaign.
criteria[to]stringSearch by recipient's phone number.
Search is allowed both by the entire number and by part of it.
For example:
12223334455 – will find all campaigns in which this number participated;
38097 – will find all campaigns with numbers containing the specified digit combination.
Only one number can participate in the search.
criteria[text]stringSearch by campaign message text.
Performed based on the complete match of the search value.
criteria[status]integerSearch by message status.
criteria[groups]stringSearch by identifiers of contact groups used in the campaign.
The parameter must be passed as an array or a string of comma-separated identifiers.
criteria[campaignStatus]stringSearch by the campaign status of the SMS message.
criteria[campaignCreateTsFrom]stringSearch by the date and time of campaign creation, starting from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[campaignCreateTsTo]stringSearch by the date and time of campaign creation up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[campaignSentTsFrom]stringSearch by the date and time of sent campaigns, starting from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[campaignSentTsTo]stringSearch by the date and time of sent campaigns up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[startSendTsFrom]stringSearch by the date and time of sent messages, starting from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[startSendTsTo]stringSearch by the date and time of sent messages up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[statusUpdateTsFrom]stringSearch by the date and time of messages whose status was changed, starting from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[statusUpdateTsTo]stringSearch by the date and time of messages whose status was changed up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.

Pagination Parameters

These parameters are created for structured (partial) output of the requested information.

ParameterTypeDescription
pagination[pageSize]integerNumber of items displayed per page (25, 50, 100).
pagination[currentPage]integerCurrent page
Page numbering starts from 0.

Sorting Parameters

These parameters allow you to sort the search results by one of the fields in ascending (ASC) or descending (DESC) order.

For example:

Sort by recipient number in ascending order – sort[to]: ASC.

Sort by message status in descending order – sort[status]: DESC.

ParameterDescription
sort[campaignId]Sort by campaign identifier.
sort[from]Sort by sender ID.
sort[to]Sort by recipient number.
sort[text]Sort by text.
sort[status]Sort by message status.
sort[startSendTs]Sort by send time.
sort[statusUpdateTs]Sort by status update.
sort[segNum]Sort by number of segments.

Server Response

Array of data:

FieldTypeDescription
itemsarrayList of found messages (see the table List of Messages).
totalItemCountintegerTotal number of found items.
List of Messages

Each message contains fields:

FieldTypeDescription
idintegerMessage identifier.
campaignIdintegerCampaign identifier of the message.
segNumintegerNumber of segments.
segUserBuyfloatCost of the message segment for the user
Specified in the user's currency.
fromstringSender ID.
tostringRecipient number.
textstringMessage text.
statusstringMessage status (see the table List of Possible Message Statuses).
groupsstringIdentifiers of contact groups that included the recipient number at the time of campaign creation.
uuidstringInternal message identifier.
countryA2stringRecipient country code in ISO-3166 alpha2 format.
operatorNamestringRecipient operator name.
startSendTsdateMessage send date and time.
Format: YYYY-MM-DD HH:MM:SS.
statusUpdateTsdateDate and time of the last message status update.
Format: YYYY-MM-DD HH:MM:SS.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5BcampaignId%5D=ASC";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.com.br/service/message/list?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php
use Mobizon\MobizonApi;

$api = new MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');

// API method call
if ($api->call(
    'message',
    'list',
    array(
        //search criteria
        'criteria' => array(
            //sender ID
            'from' => 'Alpha'
        ),
        //pagination parameters
        'pagination' => array(
            //current page
            'currentPage' => '2',
            //number of items per page
            'pageSize' => '50'
        ),
        //sorting parameters
        'sort' => array(
            //sort by campaign ID
            'campaignId' => 'ASC'
        )
    )
)
) {
    // Getting the result of an API request
    $result = $api->getData();
} else {
    // An error occurred during execution. Error code and message text output
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Sending a Single SMS Message

https://api.mobizon.com.br/service/Message/SendSmsMessage

This method allows you to send a single SMS message to a specified mobile phone number.

Request Parameters

ParameterTypeDescription
recipientstringThe recipient's phone number for the SMS message.
The number must be in international format and contain only digits.
For example: 12223334455.
If the number has a “+” at the beginning, it should be encoded as %2B or removed, leaving only digits.
textstringThe text of the SMS message, encoded in URL encoding.
If the system does not return a response with message data when attempting to send a message using a GET request, first check for special characters in the request body, such as: ? / \ & + and [space].
The presence of such characters indicates that the text was not encoded.
fromstringSender ID.
To use your own sender ID, it must first be registered.
If the sender ID is not specified, the default sender ID selected in your account will be used.
If you do not have registered sender IDs or it is not possible to send with the specified sender ID, one of the shared service sender IDs will be used if possible.
For more details about sender IDs, see the “Sender IDs” section.
paramsarrayAdditional parameters (see the table Additional Parameters).

Additional Parameters

ParameterTypeDescription
params[name]stringCampaign name.
params[deferredToTs]stringDate and time of deferred SMS message sending.
You can set the start of sending no earlier than one hour and no later than 14 days.
Format: YYYY-MM-DD HH:MM:SS.
params[mclass]integerClass of the sent message:
0 – messages are displayed as a pop-up and not saved anywhere (flashSMS);
1 – messages are saved in the phone's Inbox folder (default).
params[validity]integerMaximum waiting time for message delivery if the recipient cannot receive it immediately.
For example, if the recipient's phone is turned off or out of network coverage.
Specified in minutes from the moment of sending: from 60 minutes (1 hour) to 1440 minutes (24 hours).

Server Response

In case of successful message sending, the response contains an array with the following fields:

FieldTypeDescription
campaignIdintegerID of the created SMS campaign.
messageIdintegerID of the created SMS message.
statusintegerStatus of the SMS campaign sending.
1 – campaign awaiting moderation;
2 – campaign sent without moderation.

API Response Codes

CodeDescription
0SMS message successfully sent.
1If any parameter is specified incorrectly.

Examples

curl -X POST \
  'https://api.mobizon.com.br/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'recipient=12223334455&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440'
var data = "recipient=12223334455&text=Test+sms+message&from=YourAlpha&params%5Bvalidity%5D=1440";

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});

xhr.open("POST", "https://api.mobizon.com.br/service/message/sendSmsMessage?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
xhr.setRequestHeader("cache-control", "no-cache");

xhr.send(data);
<?php

use 'Mobizon\MobizonApi.php';

$api = new Mobizon\MobizonApi('KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK', 'api.mobizon.com.br');

// API call to send a message
if ($api->call('message',
    'sendSMSMessage',
    array(
        // Recipient international phone number
        'recipient' => '12223334455',
        // Message text
        'text' => 'Test sms message',
        // Alphaname is optional, if you don't have registered alphaname, just skip this parameter and your message will be sent with our free common alphaname, if it's available for this direction.
         'from' => 'YourAlpha',
         // Message will be expired after 1440 min (24h)
         'params[validity]' => 1440
    ))
) {
    // Get message ID assigned by our system to request it's delivery report later.
    $messageId = $api->getData('messageId');

    if (!$messageId) {
        // Message is not accepted, see error code and data for details.
    }
    // Message has been accepted by API.
} else {
    // An error occurred while sending message
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . 'See details below:' . PHP_EOL . print_r($api->getData(), true) . PHP_EOL;
}