Creation, sending, and other functions for handling individual messages (not campaigns).
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
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.
Parameter | Type | Description |
---|---|---|
ids | array string | Message identifier(s). An array or a string of identifiers separated by commas. Maximum number of identifiers in one request is 100. |
Field | Type | Description |
---|---|---|
id | integer | Message identifier. |
status | string | Message status. See the table List of Possible Message Statuses. |
segNum | integer | Number of segments in this message. |
startSendTs | string | Time 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. |
statusUpdateTs | string | Time 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. |
Code | Description |
---|---|
0 | Delivery status report successfully retrieved. |
2 | If no message identifiers are specified. |
12 | If more than 100 message identifiers are specified. |
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;
}
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.
Parameter | Type | Description |
---|---|---|
criteria | array | Search criteria (see the table Search Criteria). |
pagination | array | Pagination parameters (see the table Pagination Parameters). |
sort | array | Sorting parameters (see the table Sorting Parameters). |
withNumberInfo | integer | This 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. |
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.
Parameter | Type | Description |
---|---|---|
criteria[campaignIds] | array \ string | Search 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] | string | Search by sender ID. The search is performed by the sender ID created in the campaign. |
criteria[to] | string | Search 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] | string | Search by campaign message text. Performed based on the complete match of the search value. |
criteria[status] | integer | Search by message status. |
criteria[groups] | string | Search 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] | string | Search by the campaign status of the SMS message. |
criteria[campaignCreateTsFrom] | string | Search by the date and time of campaign creation, starting from the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[campaignCreateTsTo] | string | Search by the date and time of campaign creation up to the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[campaignSentTsFrom] | string | Search by the date and time of sent campaigns, starting from the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[campaignSentTsTo] | string | Search by the date and time of sent campaigns up to the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[startSendTsFrom] | string | Search by the date and time of sent messages, starting from the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[startSendTsTo] | string | Search by the date and time of sent messages up to the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[statusUpdateTsFrom] | string | Search 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] | string | Search 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 . |
These parameters are created for structured (partial) output of the requested information.
Parameter | Type | Description |
---|---|---|
pagination[pageSize] | integer | Number of items displayed per page (25, 50, 100). |
pagination[currentPage] | integer | Current page Page numbering starts from 0. |
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.
Parameter | Description |
---|---|
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. |
Array of data:
Field | Type | Description |
---|---|---|
items | array | List of found messages (see the table List of Messages). |
totalItemCount | integer | Total number of found items. |
Each message contains fields:
Field | Type | Description |
---|---|---|
id | integer | Message identifier. |
campaignId | integer | Campaign identifier of the message. |
segNum | integer | Number of segments. |
segUserBuy | float | Cost of the message segment for the user Specified in the user's currency. |
from | string | Sender ID. |
to | string | Recipient number. |
text | string | Message text. |
status | string | Message status (see the table List of Possible Message Statuses). |
groups | string | Identifiers of contact groups that included the recipient number at the time of campaign creation. |
uuid | string | Internal message identifier. |
countryA2 | string | Recipient country code in ISO-3166 alpha2 format. |
operatorName | string | Recipient operator name. |
startSendTs | date | Message send date and time. Format: YYYY-MM-DD HH:MM:SS . |
statusUpdateTs | date | Date and time of the last message status update. Format: YYYY-MM-DD HH:MM:SS . |
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;
}
https://api.mobizon.com.br/service/Message/SendSmsMessage
This method allows you to send a single SMS message to a specified mobile phone number.
Parameter | Type | Description |
---|---|---|
recipient | string | The 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. |
text | string | The 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. |
from | string | Sender 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. |
params | array | Additional parameters (see the table Additional Parameters). |
Parameter | Type | Description |
---|---|---|
params[name] | string | Campaign name. |
params[deferredToTs] | string | Date 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] | integer | Class 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] | integer | Maximum 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). |
In case of successful message sending, the response contains an array with the following fields:
Field | Type | Description |
---|---|---|
campaignId | integer | ID of the created SMS campaign. |
messageId | integer | ID of the created SMS message. |
status | integer | Status of the SMS campaign sending. 1 – campaign awaiting moderation; 2 – campaign sent without moderation. |
Code | Description |
---|---|
0 | SMS message successfully sent. |
1 | If any parameter is specified incorrectly. |
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¶ms%5Bvalidity%5D=1440'
var data = "recipient=12223334455&text=Test+sms+message&from=YourAlpha¶ms%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;
}