This module contains functions for creating SMS campaigns, adding recipients to them in one of the possible ways, launching the campaign for sending, deleting outdated campaigns, viewing the list of campaigns, and searching through them.
Adding Recipients to a Bulk SMS Campaign
https://api.mobizon.com.br/service/Campaign/AddRecipients
Creating a New Campaign
https://api.mobizon.com.br/service/Campaign/Create
Deleting a Campaign
https://api.mobizon.com.br/service/Campaign/Delete
Getting Campaign Basic Data
https://api.mobizon.com.br/service/Campaign/Get
Retrieving Campaign Statistics
https://api.mobizon.com.br/service/Campaign/GetInfo
Receipt of campaign's short links
https://api.mobizon.com.br/service/Campaign/GetLinks
Getting Campaign List
https://api.mobizon.com.br/service/Campaign/List
Sending a Campaign
https://api.mobizon.com.br/service/Campaign/Send
https://api.mobizon.com.br/service/Campaign/AddRecipients
Only recipient data of one type is allowed in one request:
Attempting to transmit multiple different types of recipients at once will return an error 12. If you need to add recipients from multiple sources to one campaign, this should be done in several requests.
When adding recipient numbers, contacts, or contact cards, the maximum number of recipients uploaded in one request cannot exceed 500 numbers. If the limit is exceeded, an error 12 will be returned and the recipients will not be added.
To upload any desired number of contacts to one campaign, you should split the list into portions of 500 or fewer and upload each portion with a separate API call – recipients will be added to the existing list, unless the parameter replace=1 is specified.
Uploading numbers, contacts, and cards is done in the main thread of the web server and returns the result for each processed recipient as an array (see the format of the returned data below).
Uploading from a contact group or file creates a background task (asynchronous upload) and returns its ID for further status tracking. In this case, the API response code will be 100.
Recipient numbers must be transmitted in international format. All extraneous characters will be removed from the number automatically.
Each number is checked for the possibility of sending a message to it by the country and operator code to which it belongs.
All numbers that fail the check will be rejected with an appropriate error code (code), and for each added number, the ID of the created message (messageId) will be returned for the possibility of subsequent status requests.
If not all transmitted recipients were added (errors occurred), the API may return one of two response codes:
For the entire time recipients are being added, the campaign is blocked from being added by other processes, so parallel addition in several threads to one campaign is impossible.
Parameter | Type | Description |
---|---|---|
id | integer | Campaign identifier to which recipients need to be added |
recipients | array string | For regular mailings (without using placeholder variables in the text), recipients can be transmitted as:
recipient key and the recipient number as the value. Also, this array may contain elements with keys corresponding to the names of variables (placeholders) in the SMS text (without the surrounding curly brackets).In this case, if some of the placeholders contained in the text are not transmitted in the data array, processing will occur depending on the value passed in the params[placeholdersFlag] parameter (see the description of this parameter below). |
recipientContacts | array string | An array or string of contacts from the contact book separated by commas or line breaks. A contact can be specified as:
|
recipientGroups | array string | An array or string of group IDs from the contact book separated by commas or line breaks, from which the campaign will be formed. If the same contact is contained in multiple groups, it will only be added to the campaign once. If multiple contacts contain the same phone number, only the first one will be added. |
recipientsFile | file | Uploaded file object with recipients – CSV or Excel (only XLS) file with recipient numbers in international format. For regular mailings (without using placeholder variables in the text) – numbers one per line. For template mailings – numbers one per line in one of the columns with the header recipient , with other columns possibly containing data for substitution in the placeholders. The headers of such columns (in the first row of the table) must strictly correspond to the placeholders in the SMS text (without the surrounding curly brackets, considering case sensitivity). Placeholder names are only allowed to contain Latin letters and numbers, as well as '_ ', '- '. If there are columns with the same headers, an error will be returned.In this case, if there are no corresponding columns for any of the placeholders contained in the text, processing will occur depending on the value passed in the params[placeholdersFlag] parameter (see the description of this parameter below). |
params | array | Additional settings (see the table Additional Settings). |
Parameter | Type | Description |
---|---|---|
params[replace] | integer | Indicates whether to remove all already added recipients and start adding again: 0 - no, add recipients to those already added previously (default value); 1 - yes, remove all previously added recipients before adding new ones; |
params[placeholdersFlag] | integer | Processing of missing variables (placeholders) for template mailings. If some values of variables for substitution in the text are not found, one of the following behaviors is possible: 1 - the message is added to the mailing, but the placeholders remain in the text as is, no replacement occurs (default behavior); 2 - the message is added, and the placeholders are removed (this can be useful if you use curly brackets in the text and do not want them to be removed when sending); 3 - the message is rejected with an error indicating missing data for substitution in the text. |
params[recipientsFileEncoding] | string | Encoding of the file with recipient data. Available encodings: KOI8-R, CP866, WINDOWS-1252, WINDOWS-1251, UTF-8, ASCII, ISO-8859-1, UCS-2. Default: UTF-8. |
params[recipientsFileSkipHeader] | integer | Indicates whether to skip the first line of the file and start processing from the second. Useful if the recipient upload is from a file where the first line contains column names. In this case, it is better to skip the first line and start processing the file from the second line. Possible values: 0 - start from the first line (default value); 1 - skip the first line of the file and start processing from the second (forcibly set for template mailings); In the case of template mailings, the value of this parameter is always 1 and cannot be overridden, as the first line should contain the names of the variables for substitution. |
params[recipientsFileDelimiter] | string | Column delimiter in the file with recipient data, default: , (comma). If necessary, you can use any other character. |
params[recipientsFileEnclosure] | string | Text enclosure character in the file with recipient data, default: ' (single quote). This character should enclose text on both sides in columns containing the delimiter character so that the system can correctly parse the file into columns. |
array | integer: When loading recipients from a list of numbers, contacts, or contact cards, an array is returned, each element of which contains data about the uploaded recipients:
Field | Type | Description |
---|---|---|
recipient | string | Recipient number being added to the campaign |
code | integer | Recipient addition result code: 0 - number successfully added to the campaign 1 - no phone number or its value is empty in the transmitted data 2 - no phone number found in the transmitted data (most likely the data is incorrectly formatted) 3 - number does not conform to the international phone number format 4 - number has already been added to the campaign (duplicates excluded from the mailing) 5 - number is in the stop list (this can be either your stop list or the system's stop list) 6 - sending to the destination country is restricted by your account settings 7 - it is impossible to determine the operator and/or destination country 8 - the system does not support sending to this operator, contact our support for clarification 20 - the transmitted data does not contain all the necessary placeholders (if placeholdersFlag is set to 1 )30 - contact card not found in the contact book ( recipient will be null )31 - contact card does not contain a mobile number ( recipient will be null )32 - contact not found in the contact book ( recipient will be null )51 - for technical reasons, it is currently impossible to create a short link 99 - system error when adding recipient number |
messageId | integer | ID of the added message, if the number was added, the status of the message can be obtained using the specified ID. |
number | integer | The original value of the recipient number transmitted by the user (if the recipient number was transmitted) |
contact | integer | The ID of the transmitted contact (if recipientContacts were transmitted) |
When loading a file with recipients or a list of contact groups, a numeric identifier of the background task of adding recipients is returned. For details on working with background tasks, see here.
Code | Description |
---|---|
1 | If any parameters contain incorrect values. |
2 | If the campaign with the specified ID is not found. |
10 | If the specified campaign is locked by another recipient addition process or the campaign status does not allow recipient addition. |
12 | If no recipient type is specified or multiple recipient types are specified in one request. |
98 | If not all transmitted recipients were added to the campaign. |
99 | If no recipient was added to the campaign as a result of the request. |
100 | If a background task for adding recipients was started. For details on working with background tasks, see here. |
To add a list of recipients to a mailing, you can pass their array like this:
recipients[]=380971112233&recipients[]=79101112233&recipients[]=77071112233
or like this:
recipients=380971112233,79101112233,77071112233
Both forms of writing are identical.
Assume the SMS text is as follows: Hello, {name}! Your balance as of {date} is {balance}{currency}.
In this case, the recipients
parameter should contain data of the following type:
recipients[0][recipient]=380971112233
&recipients[0][name]=%D0%92%D0%B0%D1%81%D0%B8%D0%BB%D0%B8%D0%B9
&recipients[0][date]=26.10.17
&recipients[0][balance]=123.45
&recipients[0][currency]=%D0%B3%D1%80%D0%BD
&recipients[1][recipient]=380971112255
&recipients[1][name]=%D0%9E%D0%BB%D1%8C%D0%B3%D0%B0
&recipients[1][date]=26.10.17
&recipients[1][balance]=3222.99
&recipients[1][currency]=%D1%80%D1%83%D0%B1
&recipients[2][recipient]=4901122211112
&recipients[2][name]=Markus
&recipients[2][date]=26.10.17
&recipients[2][balance]=555.45
&recipients[2][currency]=eur
All data in the fields transmitted to the server in the HTTP request must be pre-encoded in a URL encoded string (there is a corresponding function for this in each programming language).
https://api.mobizon.com.br/service/Campaign/Create
This method allows you to create a new SMS campaign. After creating the campaign, you need to add recipients, and then send it.
data array
– Campaign parameters
Parameter | Type | Description |
---|---|---|
data[name] | string | Campaign name. This field makes it easier to navigate through the created campaigns. For example: "Black Friday Discounts" or "Reminder of Negative Balance". The maximum length of the campaign name is 255 characters. |
data[text] | string | Text of the SMS message to be sent. For template campaigns (data[type]=3), this text should contain variables that will be replaced with values unique to each recipient. The variable should be written with Latin letters, numbers, and symbols «_» ,«-» , and enclosed in curly braces, for example: {name} or {clientBalance} .SMS text requirements. In the message text, you can use short links and recipient tracking feature to see who among the recipients clicked on your link. |
data[type] | integer | Campaign type: 1 – Single message (sent to one number); 2 – Mass mailing (set by default); 3 – Template campaign (the message text may contain placeholders that will be replaced with text unique to each recipient). |
data[from] | string | Sender ID. To use a custom sender ID, it must be registered in advance. If the sender ID is not specified, the default or standard service sender ID will be used. |
data[rateLimit] | integer | The limit on the number of messages sent over the period specified in the ratePeriod field.This option allows you to slow down the speed of sending a large SMS mailing to distribute the load on your Call Center. The sending speed limit is no more than 100 messages per second when calculated per second. Messages are sent at equal intervals in batches of 10, based on the specified rateLimit per ratePeriod . For example, if you specify a speed of 600 and a period of 60, 600/60=10 SMS will be sent each second. |
data[ratePeriod] | integer | The period in seconds over which the number of SMS specified in the rateLimit field will be sent.It can be: 60 – 1 minute; 3600 – 1 hour; 86400 – 1 day. |
data[deferredToTs] | string | Date and time of the deferred campaign send. The start of sending can be set no earlier than an hour later, and no later than 14 days. Format: YYYY-MM-DD HH:MM:SS . |
data[mclass] | integer | The class of the sent message: 0 – messages are displayed as a pop-up window and are not saved anywhere (flashSMS); 1 – messages are saved to the phone's Inbox folder (default). |
data[validity] | integer | The maximum waiting time for message delivery if the recipient cannot receive it immediately. For example, if the phone is off or out of network coverage. Specified in minutes from the time of sending: from 60 (1 hour) to 1440 (24 hours). |
data[trackShortLinkRecipients] | integer | Recipient tracking feature. Available for use only if there are short links created in our service in the message text (in the data[text] field).0 – do not use the feature (default); 1 – use the feature. |
integer
– campaign identifier if it is successfully created.
Code | Description |
---|---|
0 | The campaign has been successfully created. |
1 | If any parameters contain invalid values. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/create?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=Hello%2C+%7Bname%7D%21+Your+balance+on+%7Bdate%7D+is+%7Bbalance%7D%7Bcurrency%7D.'
var data = "data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=Hello%2C+%7Bname%7D%21+Your+balance+on+%7Bdate%7D+is+%7Bbalance%7D%7Bcurrency%7D.";
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/campaign/create?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(
'campaign',
'create',
array(
//campaign parameters
'data' => array(
//campaign type
'type' => '3',
//sender ID
'from' => 'Alpha',
//message text
'text' => 'Hello, {name}! Your balance on {date} is {balance}{currency}.'
)
)
)
) {
// 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/Campaign/Delete
This method allows you to delete a campaign by its ID.
A campaign can be deleted if its sending has not yet started.
If the campaign is scheduled: a scheduled campaign can be deleted provided that there are at least 5 minutes left before the start of sending.
Parameter | Type | Description |
---|---|---|
id | integer | Campaign identifier. |
Code | Description |
---|---|
0 | Campaign successfully deleted. |
2 | If the campaign with the specified ID is not found. |
10 | If the campaign with the specified ID cannot be deleted. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/delete?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/delete?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(
'campaign',
'delete',
array(
//campaign identifier
'id' => '123'
)
)
) {
// 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/Campaign/Get
This method allows you to get the basic data of a created campaign by its ID.
Parameter | Type | Description |
---|---|---|
id | integer | Campaign identifier. |
An array of data containing the following fields:
Field | Type | Description |
---|---|---|
id | string | Campaign identifier. |
moderationStatus | string | Current moderation status: MODERATION – the campaign is under moderation; DECLINED – the campaign is declined by the moderator; READY_FOR_SEND – the campaign is approved by the moderator; AUTO_READY_FOR_SEND – the campaign is sent without moderation. |
commonStatus | string | Current campaign status: MODERATION – the campaign is under moderation; DECLINED – the campaign is declined by the moderator (the reason for the decline is specified in the globalComment field); READY_FOR_SEND – the campaign is ready to be sent but has not started yet; RUNNING – the campaign is in the process of sending; SENT – the campaign is fully sent, but not all messages have received a delivery report from the mobile operator yet; DONE – the campaign is completely finished: all final delivery reports have been received, and the counters contain final values. |
groupsList | array | List of contact groups included in the campaign. For each group, it contains: id – group number; name – group name; cardsCnt – the number of contacts in the group available for sending messages. If groups were not used in the campaign, this field will be empty. |
type | integer | Campaign type: 1 – Single message (sending to one number); 2 – Mass mailing; 3 – Template campaign; 7 – Functional (service) campaign. |
msgType | string | Type of campaign messages. Currently, only the "SMS" type is supported. |
rateLimit | integer | The limit on the number of messages sent over the period specified in the ratePeriod field. |
ratePeriod | integer | The period in seconds over which the number of SMS specified in the rateLimit field will be sent. |
sendStatus | string | Campaign send status: SENT – the campaign is sent; DONE – the campaign is completed. |
isDeleted | integer | Flag indicating that the campaign is deleted: 0 – the campaign is available; 1 – the campaign is deleted. |
deferredToTs | string | The date and time of the deferred campaign send. Format: YYYY-MM-DD HH:MM:SS . |
createTs | string | The date and time of the campaign creation. Format: YYYY-MM-DD HH:MM:SS . |
startSendTs | string | The date and time of the actual start of the campaign send. Format: YYYY-MM-DD HH:MM:SS . |
endSendTs | string | The date and time of the end of sending all campaign messages. Format: YYYY-MM-DD HH:MM:SS . |
name | string | Campaign name. |
from | string | Sender ID chosen for sending the campaign. |
text | string | Full message text or template text with placeholders. |
validity | integer | The maximum waiting time for message delivery if the recipient cannot receive it immediately, in minutes from the time of sending. |
mclass | integer | The class of the sent message: 0 – messages are displayed as a pop-up window and are not saved anywhere (flashSMS); 1 – messages are saved to the phone's Inbox folder. |
trackShortLinkRecipients | integer | Whether the recipient tracking feature was used: 0 – the feature was not used; 1 – the feature was used. |
groups | string | Identifiers of contact groups used in the campaign, separated by commas. |
globalComment | string | Moderator comment if the campaign is declined. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/get?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/get?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(
'campaign',
'get',
array(
//campaign identifier
'id' => '123'
)
)
) {
// 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/Campaign/GetInfo
This method allows you to retrieve the main and statistical data of a campaign by its ID.
Statistics are generated using various counters that are displayed in the counters
field.
IMPORTANT!
Due to the technical features of calculating the campaign cost, the data on the possible cost of the campaign are indicated at the time of adding recipients and do not change over time.
Changes can occur only when recipients are re-uploaded or when campaign data is edited (in case of data editing, all recipients and calculations are reset – re-uploading is required).
Parameter | Type | Description |
---|---|---|
id | integer | Campaign identifier. |
getFilledTplCampaignText | integer | Format of returned data: 0 – campaign text with placeholders; 1 – return template campaign text filled with real recipient data (default). |
Field | Type | Description |
---|---|---|
id | integer | Campaign identifier. |
moderationStatus | string | Current moderation status: MODERATION – campaign is under moderation; DECLINED – campaign declined by moderator; READY_FOR_SEND – campaign approved by moderator; AUTO_READY_FOR_SEND – campaign sent without moderation. |
commonStatus | string | Current campaign status: MODERATION – campaign is under moderation; DECLINED – campaign declined by moderator (reason for rejection is indicated in the globalComment field);READY_FOR_SEND – campaign ready to be sent but sending has not yet started; RUNNING – campaign in the process of sending; SENT – campaign fully sent but not all messages have received delivery reports from the operator; DONE – campaign fully processed, all final delivery reports received. |
groupsList | array | List of contact groups included in the campaign. For each group contains: id – group number; name – group name; cardsCnt – number of contacts in the group available for message sending. If groups were not used in the campaign, this field will be empty. |
type | integer | Campaign type: 1 – Single message (sending to one number); 2 – Bulk mailing; 3 – Template campaign; 7 – Functional (service) campaign. |
msgType | string | Campaign message type. Currently only "SMS" type is supported. |
rateLimit | integer | Limit on the number of messages sent during the period specified in the ratePeriod field. |
ratePeriod | integer | Period during which the number of SMS specified in the rateLimit field will be sent. |
sendStatus | string | Campaign sending status: SENT – campaign sent; DONE – campaign completed. |
isDeleted | integer | Flag indicating that the campaign is deleted: 0 – campaign available; 1– campaign deleted. |
deferredToTs | string | Date and time of the deferred sending of the campaign. Format: YYYY-MM-DD HH:MM:SS . |
createTs | string | Date and time of campaign creation. Format: YYYY-MM-DD HH:MM:SS . |
startSendTs | string | Date and time of the actual start of the campaign sending. If sending has not started, this field contains NULL. Format: YYYY-MM-DD HH:MM:SS . |
endSendTs | string | Date and time of the end of sending all campaign messages. If message sending has not been completed, this field contains NULL. Format: YYYY-MM-DD HH:MM:SS . |
name | string | Campaign name. |
from | string | Sender ID selected for sending the campaign. |
text | string | Full message text or template text with placeholders. |
validity | integer | Maximum message delivery waiting time if the recipient cannot receive it immediately, in minutes from the moment of sending. |
mclass | integer | Class of the sent message: 0 – messages displayed as a pop-up and not saved anywhere (flashSMS); 1 – messages saved in the phone's Inbox folder. |
trackShortLinkRecipients | integer | Whether the recipient tracking function is used: 0 – function not used; 1 – function used. |
groups | string | IDs of contact groups used in the campaign, separated by commas. |
globalComment | string | Moderator's comment if the campaign is declined. |
creationWay | integer | Campaign creation method: 1 – using an Internet browser; 5 – functional (service) campaign. |
counters | array | Various campaign counters described in the table Fields of the counters object. |
counters
ObjectField | Type | Description |
---|---|---|
updateTs | datetime | Time of the last counter update. To reduce system load, counter updates may occur with a delay. Format: YYYY-MM-DD HH:MM:SS . |
totalNewSegNum | integer | Total number of segments with status NEW . |
totalAcceptdSegNum | integer | Total number of segments with status ACCEPTD . |
totalDelivrdSegNum | integer | Total number of segments with status DELIVRD . |
totalRejectdSegNum | integer | Total number of segments with status REJECTD . |
totalExpiredSegNum | integer | Total number of segments with status EXPIRED . |
totalUndelivSegNum | integer | Total number of segments with status UNDELIV . |
totalDeletedSegNum | integer | Total number of segments with status DELETED . |
totalUnknownSegNum | integer | Total number of segments with status UNKNOWN . |
totalPdlivrdSegNum | integer | Total number of segments with status PDLIVRD . |
totalSegNum | integer | Total number of segments in the campaign. Updated when recipients are added. |
totalNewMsgNum | integer | Total number of messages with status NEW . |
totalAcceptdMsgNum | integer | Total number of messages with status ACCEPTD . |
totalDelivrdMsgNum | integer | Total number of messages with status DELIVRD . |
totalRejectdMsgNum | integer | Total number of messages with status REJECTD . |
totalExpiredMsgNum | integer | Total number of messages with status EXPIRED . |
totalUndelivMsgNum | integer | Total number of messages with status UNDELIV . |
totalDeletedMsgNum | integer | Total number of messages with status DELETED . |
totalUnknownMsgNum | integer | Total number of messages with status UNKNOWN . |
totalPdlivrdMsgNum | integer | Total number of messages with status PDLIVRD . |
totalMsgNum | integer | Total number of messages (not segments). Updated during the processing (before sending) of campaign messages/segments. |
totalNewMsgCost | float | Total cost of all segments with status NEW . |
totalAcceptdMsgCost | float | Total cost of all segments with status ACCEPTD . |
totalDelivrdMsgCost | float | Total cost of all segments with status DELIVRD . |
totalRejectdMsgCost | float | Total cost of all segments with status REJECTD . |
totalExpiredMsgCost | float | Total cost of all segments with status EXPIRED . |
totalUndelivMsgCost | float | Total cost of all segments with status UNDELIV . |
totalDeletedMsgCost | float | Total cost of all segments with status DELETED . |
totalUnknownMsgCost | float | Total cost of all segments with status UNKNOWN . |
totalPdlivrdMsgCost | float | Total cost of all segments with status PDLIVRD . |
totalCost | float | Total campaign cost. |
recipientsRejected | integer | Number of rejected recipients (not included in the campaign). Updated when recipients are added. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/getInfo?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/getInfo?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(
'campaign',
'getInfo',
array(
//campaign identifier
'id' => '123'
)
)
) {
// 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/Campaign/GetLinks
Parameter | Type | Description |
---|---|---|
campaignId | integer | Campaign ID |
Data array for each link
Field | Type | Description |
---|---|---|
id | integer | Link ID |
code | string | Short link code |
fullLink | string | Full link |
shortLink | string | Short link |
clickCnt | integer | Number of clicks |
redirectCnt | integer | Number of transitions |
comment | string | Comment |
Code | Description |
---|---|
2 | If the campaign was not found. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/getLinks?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'campaignId=123'
var data = "campaignId=123";
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/campaign/getLinks?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(
'campaign',
'getLinks',
array(
//campaign identifier
'campaignId' => '123'
)
)
) {
// 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/Campaign/List
This method allows you to get a list of created campaigns. The search can be performed by ID and other 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). |
The following are the fields by which the search is performed. The search can be done by one or several fields simultaneously.
Parameter | Type | Description |
---|---|---|
criteria[id] | integer | Search for a single campaign by its ID. |
criteria[ids] | array | Search for multiple campaigns by their ID. 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 in the list. |
criteria[recipient] | string | Search by recipient's phone number or 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[from] | string | Search by sender ID used in the campaign. |
criteria[text] | string | Search by campaign message text. Performed based on the complete match of the search value. |
criteria[status] | string | Search by campaign status. |
criteria[createTsFrom] | string | Search for campaigns created from the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[createTsTo] | string | Search for campaigns created up to the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[sentTsFrom] | string | Search for campaigns sent from the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[sentTsTo] | string | Search for campaigns sent up to the specified date and time. Format: YYYY-MM-DD HH:MM:SS . |
criteria[type] | integer | Search by campaign type: 1 – Single message (sent to one number); 2 – Mass mailing (default); 3 – Template campaign (the message text may contain placeholders that will be replaced with text unique to each recipient). |
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. |
These parameters are intended 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 campaign creation date in ascending order – sort[createTs]=ASC
.
Sort by campaign ID in descending order – sort[id]=DESC
.
Parameter | Description |
---|---|
sort[id] | Sort by campaign ID. |
sort[name] | Sort by campaign name. |
sort[from] | Sort by sender ID. |
sort[counters.totalMsgNum] | Sort by the number of phone numbers in the campaign. |
sort[counters.totalCost] | Sort by campaign cost. |
sort[createTs] | Sort by campaign creation date and time. |
sort[startSendTs] | Sort by campaign send start date and time. |
sort[endSendTs] | Sort by campaign send end date and time. |
Contains an array of two fields:
Field | Type | Description |
---|---|---|
items | array | List of found campaigns. For a description of the campaign fields, see the description of the campaign/getInfo method. |
totalItemCount | integer | Total number of found items. |
Status | Description |
---|---|
NEW | The campaign is created, but the user has not sent it yet. Adding recipients is allowed in this status. |
MODERATION | Under moderation to comply with the service rules. |
DECLINED | Declined by the moderator as it does not comply with the service rules or the requirements of the operators whose numbers are present in the campaign. |
READY_FOR_SEND | The campaign is ready to be sent, but the sending has not started yet. |
AUTO_READY_FOR_SEND | No moderation is required. The campaign will be sent without moderation. |
NOT_YET_SENT | Includes all statuses when the campaign has not yet been sent. This value is used only for search. Campaigns cannot have it. |
RUNNING | The campaign is running, the sending process to the operator is ongoing. |
DEFERRED | The campaign send is scheduled for a specific time. This value is used only for search. Campaigns cannot have it. |
SENT | The campaign is fully sent, but not all messages have received a delivery report from the mobile operators yet. |
DONE | The campaign is fully processed, all final delivery reports have been received. After this status is set, no campaign counters are changed. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/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%5Btype%5D=ASC'
var data = "criteria%5Bfrom%5D=Alpha&pagination%5BcurrentPage%5D=2&pagination%5BpageSize%5D=50&sort%5Btype%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/campaign/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(
'campaign',
'list',
array(
//search criteria
'criteria' => array(
//sender ID
'from' => 'Alpha'
),
//pagination parameters
'pagination' => array(
//current page
'currentPage' => '2',
//number of items displayed per page
'pageSize' => '50'
),
//sorting parameters
'sort' => array(
//sorting by campaign type
'type' => '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/Campaign/Send
This method allows you to send a created campaign by its ID.
Please note! Depending on conditions such as suspicion of spam, presence of suspicious content in the message text, restriction for a certain direction, etc., as well as terms of cooperation (contract), the campaign may go to moderation.
Parameter | Type | Description |
---|---|---|
id | integer | Campaign identifier. |
integer
: campaign sending status.
1 – campaign is being reviewed by a moderator;
2 – campaign sent.
Code | Description |
---|---|
0 | Campaign successfully sent. |
2 | If the campaign is not found. |
10 | If the campaign status could not be changed. |
curl -X POST \
'https://api.mobizon.com.br/service/campaign/send?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'id=123'
var data = "id=123";
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/campaign/send?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(
'campaign',
'send',
array(
//campaign identifier
'id' => '123'
)
)
) {
// 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;
}