Registration

Module Campaign

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.

API methods

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

Adding Recipients to a Bulk SMS Campaign

https://api.mobizon.com.br/service/Campaign/AddRecipients

Only recipient data of one type is allowed in one request:

  • list of numbers/ID contact cards/contact IDs
  • list of group IDs from the contact book
  • file with recipient list.

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:

  • 98 - if not all recipients were added, but at least one recipient passed the check
  • 99 - if no recipients passed the check.

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.

Request Parameters

ParameterTypeDescription
idintegerCampaign identifier to which recipients need to be added
recipientsarray stringFor regular mailings (without using placeholder variables in the text), recipients can be transmitted as:
  • a string with recipient numbers separated by commas or line breaks;
  • a one-dimensional array where each array element corresponds to one recipient number;
  • a two-dimensional array where each element is an array containing an element with the recipient key and the recipient number as the value.
For template mailings, recipients must be transmitted as a two-dimensional array, where each element is an array containing an element with the 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).
recipientContactsarray stringAn array or string of contacts from the contact book separated by commas or line breaks. A contact can be specified as:
  • card ID. In this case, the value of the 'mobile phone number' field marked as the field for mailings will be used for the mailing;
  • {card ID}:{card field key} (e.g., 123456:mobile if the mobile phone field in your book has the 'mobile' key). The value of the specified card field will be used for the mailing.
If the mailing is template-based, data for filling in the placeholders in the text will be used from the corresponding contact card.
recipientGroupsarray stringAn 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.
recipientsFilefileUploaded 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).
paramsarrayAdditional settings (see the table Additional Settings).
Additional Settings
ParameterTypeDescription
params[replace]integerIndicates 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]integerProcessing 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]stringEncoding 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]integerIndicates 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]stringColumn delimiter in the file with recipient data, default: , (comma). If necessary, you can use any other character.
params[recipientsFileEnclosure]stringText 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.

Server Response

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:

FieldTypeDescription
recipientstringRecipient number being added to the campaign
codeintegerRecipient 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
messageIdintegerID of the added message, if the number was added, the status of the message can be obtained using the specified ID.
numberintegerThe original value of the recipient number transmitted by the user (if the recipient number was transmitted)
contactintegerThe 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.

Error Codes

CodeDescription
1If any parameters contain incorrect values.
2If the campaign with the specified ID is not found.
10If the specified campaign is locked by another recipient addition process or the campaign status does not allow recipient addition.
12If no recipient type is specified or multiple recipient types are specified in one request.
98If not all transmitted recipients were added to the campaign.
99If no recipient was added to the campaign as a result of the request.
100If a background task for adding recipients was started. For details on working with background tasks, see here.

Examples

Adding recipient numbers to a bulk mailing.

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.

Adding data for template mailing.

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

Creating a New Campaign

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.

Request Parameters

data array – Campaign parameters

ParameterTypeDescription
data[name]stringCampaign 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]stringText 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]integerCampaign 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]stringSender 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]integerThe 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]integerThe 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]stringDate 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]integerThe 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]integerThe 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]integerRecipient 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.

Server Response

integer – campaign identifier if it is successfully created.

API Response Codes

CodeDescription
0The campaign has been successfully created.
1If any parameters contain invalid values.

Examples

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

Deleting a Campaign

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.

Request Parameters

ParameterTypeDescription
idintegerCampaign identifier.

API Response Codes

CodeDescription
0Campaign successfully deleted.
2If the campaign with the specified ID is not found.
10If the campaign with the specified ID cannot be deleted.

Examples

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

Getting Campaign Basic Data

https://api.mobizon.com.br/service/Campaign/Get

This method allows you to get the basic data of a created campaign by its ID.

Request Parameters

ParameterTypeDescription
idintegerCampaign identifier.

Server Response

An array of data containing the following fields:

FieldTypeDescription
idstringCampaign identifier.
moderationStatusstringCurrent 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.
commonStatusstringCurrent 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.
groupsListarrayList 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.
typeintegerCampaign type:
1 – Single message (sending to one number);
2 – Mass mailing;
3 – Template campaign;
7 – Functional (service) campaign.
msgTypestringType of campaign messages.
Currently, only the "SMS" type is supported.
rateLimitintegerThe limit on the number of messages sent over the period specified in the ratePeriod field.
ratePeriodintegerThe period in seconds over which the number of SMS specified in the rateLimit field will be sent.
sendStatusstringCampaign send status:
SENT – the campaign is sent;
DONE – the campaign is completed.
isDeletedintegerFlag indicating that the campaign is deleted:
0 – the campaign is available;
1 – the campaign is deleted.
deferredToTsstringThe date and time of the deferred campaign send.
Format: YYYY-MM-DD HH:MM:SS.
createTsstringThe date and time of the campaign creation.
Format: YYYY-MM-DD HH:MM:SS.
startSendTsstringThe date and time of the actual start of the campaign send.
Format: YYYY-MM-DD HH:MM:SS.
endSendTsstringThe date and time of the end of sending all campaign messages.
Format: YYYY-MM-DD HH:MM:SS.
namestringCampaign name.
fromstringSender ID chosen for sending the campaign.
textstringFull message text or template text with placeholders.
validityintegerThe maximum waiting time for message delivery if the recipient cannot receive it immediately, in minutes from the time of sending.
mclassintegerThe 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.
trackShortLinkRecipientsintegerWhether the recipient tracking feature was used:
0 – the feature was not used;
1 – the feature was used.
groupsstringIdentifiers of contact groups used in the campaign, separated by commas.
globalCommentstringModerator comment if the campaign is declined.

Examples

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

Retrieving Campaign Statistics

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

Request Parameters

ParameterTypeDescription
idintegerCampaign identifier.
getFilledTplCampaignTextintegerFormat of returned data:
0 – campaign text with placeholders;
1 – return template campaign text filled with real recipient data (default).

Server Response

FieldTypeDescription
idintegerCampaign identifier.
moderationStatusstringCurrent 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.
commonStatusstringCurrent 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.
groupsListarrayList 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.
typeintegerCampaign type:
1 – Single message (sending to one number);
2 – Bulk mailing;
3 – Template campaign;
7 – Functional (service) campaign.
msgTypestringCampaign message type.
Currently only "SMS" type is supported.
rateLimitintegerLimit on the number of messages sent during the period specified in the ratePeriod field.
ratePeriodintegerPeriod during which the number of SMS specified in the rateLimit field will be sent.
sendStatusstringCampaign sending status:
SENT – campaign sent;
DONE – campaign completed.
isDeletedintegerFlag indicating that the campaign is deleted:
0 – campaign available;
1– campaign deleted.
deferredToTsstringDate and time of the deferred sending of the campaign.
Format: YYYY-MM-DD HH:MM:SS.
createTsstringDate and time of campaign creation.
Format: YYYY-MM-DD HH:MM:SS.
startSendTsstringDate 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.
endSendTsstringDate 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.
namestringCampaign name.
fromstringSender ID selected for sending the campaign.
textstringFull message text or template text with placeholders.
validityintegerMaximum message delivery waiting time if the recipient cannot receive it immediately, in minutes from the moment of sending.
mclassintegerClass 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.
trackShortLinkRecipientsintegerWhether the recipient tracking function is used:
0 – function not used;
1 – function used.
groupsstringIDs of contact groups used in the campaign, separated by commas.
globalCommentstringModerator's comment if the campaign is declined.
creationWayintegerCampaign creation method:
1 – using an Internet browser;
5functional (service) campaign.
countersarrayVarious campaign counters described in the table Fields of the counters object.
Fields of the counters Object
FieldTypeDescription
updateTsdatetimeTime of the last counter update.
To reduce system load, counter updates may occur with a delay.
Format: YYYY-MM-DD HH:MM:SS.
totalNewSegNumintegerTotal number of segments with status NEW.
totalAcceptdSegNumintegerTotal number of segments with status ACCEPTD.
totalDelivrdSegNumintegerTotal number of segments with status DELIVRD.
totalRejectdSegNumintegerTotal number of segments with status REJECTD.
totalExpiredSegNumintegerTotal number of segments with status EXPIRED.
totalUndelivSegNumintegerTotal number of segments with status UNDELIV.
totalDeletedSegNumintegerTotal number of segments with status DELETED.
totalUnknownSegNumintegerTotal number of segments with status UNKNOWN.
totalPdlivrdSegNumintegerTotal number of segments with status PDLIVRD.
totalSegNumintegerTotal number of segments in the campaign. Updated when recipients are added.
totalNewMsgNumintegerTotal number of messages with status NEW.
totalAcceptdMsgNumintegerTotal number of messages with status ACCEPTD.
totalDelivrdMsgNumintegerTotal number of messages with status DELIVRD.
totalRejectdMsgNumintegerTotal number of messages with status REJECTD.
totalExpiredMsgNumintegerTotal number of messages with status EXPIRED.
totalUndelivMsgNumintegerTotal number of messages with status UNDELIV.
totalDeletedMsgNumintegerTotal number of messages with status DELETED.
totalUnknownMsgNumintegerTotal number of messages with status UNKNOWN.
totalPdlivrdMsgNumintegerTotal number of messages with status PDLIVRD.
totalMsgNumintegerTotal number of messages (not segments). Updated during the processing (before sending) of campaign messages/segments.
totalNewMsgCostfloatTotal cost of all segments with status NEW.
totalAcceptdMsgCostfloatTotal cost of all segments with status ACCEPTD.
totalDelivrdMsgCostfloatTotal cost of all segments with status DELIVRD.
totalRejectdMsgCostfloatTotal cost of all segments with status REJECTD.
totalExpiredMsgCostfloatTotal cost of all segments with status EXPIRED.
totalUndelivMsgCostfloatTotal cost of all segments with status UNDELIV.
totalDeletedMsgCostfloatTotal cost of all segments with status DELETED.
totalUnknownMsgCostfloatTotal cost of all segments with status UNKNOWN.
totalPdlivrdMsgCostfloatTotal cost of all segments with status PDLIVRD.
totalCostfloatTotal campaign cost.
recipientsRejectedintegerNumber of rejected recipients (not included in the campaign). Updated when recipients are added.

Examples

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

Receipt of campaign's short links

https://api.mobizon.com.br/service/Campaign/GetLinks

Request parameters

ParameterTypeDescription
campaignIdintegerCampaign ID

Server response

Data array for each link

FieldTypeDescription
idintegerLink ID
codestringShort link code
fullLinkstringFull link
shortLinkstringShort link
clickCntintegerNumber of clicks
redirectCntintegerNumber of transitions
commentstringComment

Errors codes

CodeDescription
2If the campaign was not found.

Examples

Getting Campaign List

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.

Request Parameters

ParameterTypeDescription
criteriaarraySearch criteria (see the table Search Criteria).
paginationarrayPagination parameters (see the table Pagination Parameters).
sortarraySorting parameters (see the table Sorting Parameters).

Search Criteria

The following are the fields by which the search is performed. The search can be done by one or several fields simultaneously.

ParameterTypeDescription
criteria[id]integerSearch for a single campaign by its ID.
criteria[ids]arraySearch 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]stringSearch 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]stringSearch by sender ID used in the campaign.
criteria[text]stringSearch by campaign message text.
Performed based on the complete match of the search value.
criteria[status]stringSearch by campaign status.
criteria[createTsFrom]stringSearch for campaigns created from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[createTsTo]stringSearch for campaigns created up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[sentTsFrom]stringSearch for campaigns sent from the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[sentTsTo]stringSearch for campaigns sent up to the specified date and time.
Format: YYYY-MM-DD HH:MM:SS.
criteria[type]integerSearch 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]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.

Pagination Parameters

These parameters are intended 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 campaign creation date in ascending order – sort[createTs]=ASC.
Sort by campaign ID in descending order – sort[id]=DESC.

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

Server Response

Contains an array of two fields:

FieldTypeDescription
itemsarrayList of found campaigns.
For a description of the campaign fields, see the description of the campaign/getInfo method.
totalItemCountintegerTotal number of found items.
Campaign Statuses
StatusDescription
NEWThe campaign is created, but the user has not sent it yet.
Adding recipients is allowed in this status.
MODERATIONUnder moderation to comply with the service rules.
DECLINEDDeclined 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_SENDThe campaign is ready to be sent, but the sending has not started yet.
AUTO_READY_FOR_SENDNo moderation is required. The campaign will be sent without moderation.
NOT_YET_SENTIncludes all statuses when the campaign has not yet been sent.
This value is used only for search. Campaigns cannot have it.
RUNNINGThe campaign is running, the sending process to the operator is ongoing.
DEFERREDThe campaign send is scheduled for a specific time.
This value is used only for search. Campaigns cannot have it.
SENTThe campaign is fully sent, but not all messages have received a delivery report from the mobile operators yet.
DONEThe campaign is fully processed, all final delivery reports have been received.
After this status is set, no campaign counters are changed.

Examples

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

Sending a Campaign

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.

Request Parameters

ParameterTypeDescription
idintegerCampaign identifier.

Server Response

integer: campaign sending status.

Possible values:

1 – campaign is being reviewed by a moderator;
2 – campaign sent.

API Response Codes

CodeDescription
0Campaign successfully sent.
2If the campaign is not found.
10If the campaign status could not be changed.

Examples

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