Registration

Module Campaign

This module contains functions for creating SMS campaigns, adding recipients to them using one of the possible ways, launching a campaign, deleting of irrelevant campaigns, reviewing the list of campaigns and searching on them.

API methods

Adding recipients to a bulk SMS campaign
https://api.mobizon.gmbh/service/Campaign/AddRecipients

Creating of a new campaign
https://api.mobizon.gmbh/service/Campaign/Create

Full deletion of the campaign
https://api.mobizon.gmbh/service/Campaign/Delete

Getting of the main campaign data
https://api.mobizon.gmbh/service/Campaign/Get

Getting of the campaign's statistical data
https://api.mobizon.gmbh/service/Campaign/GetInfo

Receipt of campaign's short links
https://api.mobizon.gmbh/service/Campaign/GetLinks

Receipt of the campaigns list
https://api.mobizon.gmbh/service/Campaign/List

Launching of the campaign
https://api.mobizon.gmbh/service/Campaign/Send

Adding recipients to a bulk SMS campaign

https://api.mobizon.gmbh/service/Campaign/AddRecipients

Within one request it is only allowed to send one of the following recipients’ data source:

  • list of numbers / contact card ID / contact ID
  • list of groups ID from the contact book
  • file with the list of recipients.

If you try to send several different types of recipients at once, the error 12 will be returned.

If you need to add recipients from multiple sources to the same campaign, please proceed with several requests. When adding recipient numbers, contacts or contact cards, the maximum number of recipients in one request shouldn’t exceed 500 entries. If the limit is exceeded, an error 12 will be returned and none of the recipients will be added.

To add any desired number of contacts to the same campaign, divide the list into parts consisting of 500 or fewer elements and send each new part by a separate API request - the recipients will be added to the existing list unless the replace=1 parameter is specified.

Uploading of numbers, contacts and contact cards is performed within the main webserver thread and returns the result for each processed recipient as an array (check the returned data format below).

Import from a contact group or file creates a background task (asynchronous loading) and returns its ID for further status tracking. In this case the API response code will be 100.

Mobile numbers you are sending must be entered in international format. All extraneous characters will be removed automatically.

Each number will be verified through sending of a message to it using the country code and operator prefix.

All non-verified numbers will be rejected with the corresponding error code (code), and for each added number the generated message ID (messageId) will be returned to enable further status request.

If not all imported recipients were added successfully (some errors occurred), then the API returns one of the following response codes: - 98 - if not all recipients were added, but at least one recipient was verified - 99 - if no recipient was verified.

While the recipients are being added, the campaign is blocked for any other adding recipients' request, therefore simultaneous import is impossible.

Request parameters

ParameterTypeDescription
idintegerID of the campaign, you want to add recipients to
recipientsarray|stringRegular campain recipients can be sent as a:
  • string with recipient numbers separated by commas or line breaks;
  • one-dimensional array, where each element corresponds to one recipient number;
  • two-dimensional array, where each element is itself an array, containing an element with the recipient key and the recipient's number as a value.
Template campaign recipients must be sent as a two-dimensional array, where each element is itself an array, containing an element with the recipient key and the recipient's number as a value, it can also include (but not necessarily) elements with keys corresponding to the names of variables (placeholders) in the SMS text (without surrounding curly braces).
At the same time, if any of the placeholders contained in text was not passed, then processing will go on depending on the passed parameter placeholdersFlag (see the flag description below). Examples of requests are listed below.
recipientsCardIdsarray|stringThe array or the string of the contact cards' IDs from the contact book, separated by comma or line break, which will form the future campaign.
recipientsContactIdsarray|stringThe array or the string of the contact' IDs from the contact book.
If the campaign is template, then in order to fill in the placeholders in the text the data from the corresponding contact card, this contact belongs to, will be used.
recipientsGroupIdsarray|stringThe array or the string of the contact groups' IDs from the contact book, separated by comma or line break, which will form the future campaign.
recipientsFilefileThe object of the file with the recipients is the CSV or Excel (only XLS) file with recipients' numbers in the international format.
For regular campaign the numbers are distributed one per line.
For template campaign numbers are distributed one by one in a row in any of the columns with therecipient header, other columns may contain placeholders. Column headers must correspond to the placeholders in the text of SMS (without surrounding curly braces). To name a placeholder use only Latin letters and numbers or characters '_' and '-'. If there are columns with the same headings, an error will be returned.
At the same time, if there are no corresponding columns for any of the placeholders contained in the text, then processing will occur depending on the placeholdersFlag value passed to the params parameter (see the flag description below).
paramsarrayAdvanced settings (see Advanced settings table).
Advanced settings
ParameterTypeDescription
params[replace]integerIndicates whether it is necessary to delete all already added recipients and to start adding again:
0 - no, add recipients to previously added ones (default value);
1 - yes, delete all before adding new ones;
params[placeholdersFlag]integerProcessing of the missing variables (placeholders) for the template campaign.
If no variable values for the placeholder are found, then one of the following scenario is possible:
1 - the message is added to the campaign, but the placeholders remain in the text as they are (default scenario);
2 — the message is added, but placeholders are deleted (if you just need to send, not to reject the message);
3 — the message is rejected with an error indicating missing data for the placeholder in text.
params[recipientsFileEncoding]stringEncoding in the recipient data file, available are the following encodings: KOI8-R, CP866, WINDOWS-1252, WINDOWS-1251, UTF-8, ASCII, ISO-8859-1, UCS-2, default is: UTF-8.
params[recipientsFileSkipHeader]integerIndicates whether it is necessary to skip the first line of the file and start processing from the second. Can be of use if recipients are uploaded from a file in which the first line contains the columns' names. In this case, it is better to skip the first line and start processing the file from the second one. Possible values are:
0 - start from the first line (default value);
1 - skip the first line of the file and start processing from the second (used by default within the template campaign); < br> For the template campaign the value of this parameter is always set to 1 and can't be redefined, since the first line must contain the names of the placeholder variables.
params[recipientsFileDelimiter]stringColumn separator in the recipients; data file, by default: , (comma)
params[recipientsFileEnclosure]stringText separator in the recipients data file, default: ' (single quotes)

Server response

array | integer : When recipients are uploaded from a list of numbers, contacts or contact cards, an array is returned, each element of which contains data of the added recipients:

FieldTypeDescription
recipientstring Number of the recipient being added to the campaign
codeintegerRecipient adding result code:
0 - the number was successfully added to the campaign
1 - there is no phone number in the transferred data or the value is empty
2 - no phone number found in the transferred data (most likely the data was incorrectly formatted)
3 - the number doesn't correspond to the international format requirements
4 - the number was already added to the campaign (deletion of duplicates from a campaign)
5 - the number is included to the stop-list (it can be either your stop-list or the system stop-list)
6 - sending to the country of destination is limited by your account settings
7 - it is impossible to identify the operator and/or the country of destination
8 - the system is not able to send to this operator, please contact our technical support to clarify the possibility to send it
20 - sent data does not contain all necessary placeholders (if placeholdersFlag is set to 1 value)
30 - contact card was not found in the contact book (recipient equals to null)
31 - contact card does not contain a mobile number (recipient equals tonull)
32 - contact was not found in the contact book (recipient equals tonull)
51 - for technical reasons it is currently impossible to create a short link
99 - system error adding recipient number
messageIdintegerThe identifier of the added message; if the number was added, by the specified identifier you can check the status of the message.
numberintegerInitial value of the recipient's number, added by the user (if the recipient's number was transmitted)
contactIdintegerThe identifier of the added contact (when recipientsContactIds was sent)
contactCardIdintegerThe identifier of the added contact card(when recipientsCardIdswas sent)

When you upload a recipients' file or a list of contact groups, the numeric identifier of the background recipients' adding task is returned. Details for tasks servicing are to be checked here.

Error codes

CodeDescription
1If any parameter contains invalid values.
2If the campaign with specified ID is not found.
10If the specified campaign is blocked by another recipients' adding process or campaign status doesn't allow adding of recipients.
12If none of the recipients type is sent or multiple types of recipients are sent in a single request.
98If at least one of all sent recipients is not added to the campaign.
99If in the query processing result none of the recipients is added to the campaign.
100If the background recipients' adding task was started. Details for tasks servicing are to be checked here.

Examples

Adding recipient's numbers to a bulk SMS campaign.

To add the list of recipients to the campaign, send the array, containing them, like this:

recipients[]=380971112233&recipients[]=79101112233&recipients[]=77071112233

or like that:

recipients=380971112233,79101112233,77071112233

Both entry formats are identical.

Adding data to the template campaign.

Let's suppose, that SMS contains the following text: Hello, {name}! Your balance as at {date} equals to {balance}{currency}. In this case parameter recipients should send these types of data:

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 HTTP request fields sent to the server should be prior encoded in the URL encoded string (each programming language has a corresponding function for this).

Creating of a new campaign

https://api.mobizon.gmbh/service/Campaign/Create

This method creates a new campaign with the specified parameters, then you can add recipients to it using the method of recipients' uploading.

Request parameters

data : array Campaign parameters (compulsory parameter)

ParameterTypeDescription
data[name]stringCampaign name
data[text]stringFull text of the message or template text with placeholders.
Placeholders should be framed with curly brackets {}, for placeholder text it is only allowed to use Latin letters and numbers or characters '_', '-', which will later be replaced with a unique text for each message. To create a template campaign, you also need to pass the appropriate campaign type. If there are short links in the text and the recipient tracking is enabled (trackShortLinkRecipients flag), those short links that need to be monitored should be framed with placeholders [[...]] (two square quotes). Such links will be replaced with links containing the recipient tracking code, and placeholders will be removed.
For example, a message with the text: "Simple short link - http://mbzn.co/FbT, link with recipient tracking - [[http://mbzn.co/FbT]" will be sent to the recipient's phone as:" Simple short link - http://mbzn.co/FbT, recipient tracking link - http://mbzn.co/XxDxSa2A". The recipient tracking code length is always fixed and equals to 8 characters.
data[type]integerCampaign type, 2 - regular, 3 - template, default: 2. When creating template campaign type, do not forget to include placeholders in the text.
data[from]stringSender's signature, displayed on the recipient's phone.
data[rateLimit]integerSending limit by the quantity of messages. It is used together with the ratePeriod parameter. Allows you to prolongate the campaign to provide gradual receipt of messages by subscribers.
data[ratePeriod]integerSending limit by the time period. To be ignored, if rateLimit is not set or equals to 0.
data[deferredToTs]stringDate and time of the campaign, if you want to start sending at a specified time.It should start not later than in 14 days and not earlier than in an hour from the actual time. Format: 2013-12-31 15:34:55
data[mclass]integer0, 1, 2, 3, default 1 - messages are saved to the Incoming messages folder in the phone, 0 - are displayed as a popup and are not saved (flashSMS), is supported not by all phones, 2 - are saved to SIM-card, 3 - SIM Toolkit SMS
data[ttl]integerMessage lifetime in minutes makes from 1 min to 3 days (4320 min) from the moment of sending (the parameter is only available for SMS campaigns)
data[trackShortLinkRecipients]integerTo track specified short links' recipients - 1, by default is not tracked - 0

Server response

integer : campaign ID, if the campaign was successfully created

Error codes

CodeDescription
1If any of the parameters contains invalid values.

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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+%7Bname%7D%21+Your+balance+by+%7Bdate%7D+is+%7Bbalance%7D%7Bcurrency%7D.'
var data = "data%5Btype%5D=3&data%5Bfrom%5D=Alpha&data%5Btext%5D=Hello+%7Bname%7D%21+Your+balance+by+%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.gmbh/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.gmbh');

// 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 by {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;
}

Full deletion of the campaign

https://api.mobizon.gmbh/service/Campaign/Delete

You can delete the campaign, which has not yet started, but if the campaign was postponed, there should be not less than 5 minutes left till start.

Request parameters

ParameterTypeDescription
idintegerCampaign ID

Server response

boolean true - if the deletion was successfully completed

Errors codes

CodeDescription
2If the campaign with specified ID was not found
10If the campaign with specified ID can't be deleted

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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.gmbh/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.gmbh');

// API method call
if ($api->call(
    'campaign',
    'delete',
    array(
        //campaign ID
        '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 of the main campaign data

https://api.mobizon.gmbh/service/Campaign/Get

Request parameters

ParameterTypeDescription
idintegerCampaign ID

Sever response

Data array

FieldTypeDescription
namestringCampaign name
textstringFull message text or template text with placeholders, which will later be replaced with a unique text for each message
msgTypestringCampaign message type, at the moment only SMS is supported
fromstringSender's signature
rateLimitintegerSending limit by the quantity
ratePeriodintegerSending limit for the time period. To be ignored, if rateLimit is not set or equals to 0
deferredToTsstringDate and time of the campaign, when it is necessary to start sending in the specified time. It should start not later than in 14 days and not earlier than in an hour from the actual time. Format: 2013-12-31 15:34:55
mclassinteger0, 1, 2, 3, by default 1 - messages are saved to the Incoming messages folder in the phone, 0 - are displayed as a popup and are not saved (flashSMS), is supported not by all phones, 2 - are saved to SIM-card, 3 - SIM Toolkit SMS
ttlintegerMessage lifetime in minutes makes from 1 min to 3 days (4320 min) from the moment of sending (the parameter is only available for SMS campaigns)

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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.gmbh/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.gmbh');

// API method call
if ($api->call(
    'campaign',
    'get',
    array(
        //campaign ID
        '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 of the campaign's statistical data

https://api.mobizon.gmbh/service/Campaign/GetInfo

It is used to obtain preliminary information about the cost of the campaign, taking into account the current situation in the system, as well as to obtain information on the number of sent and delivered messages, the amount of money spent and other statistics related to the campaign.
IMPORTANT! Because of the campaign's calculation technical features, data on the preliminary cost of the campaign are specified at the time of recipients' adding and do not change over time, unless you upload the recipients again or edit the campaign data (if you edit the data, all recipients and calculations will be reset and reloading will be necessary).

Request parameters

ParameterTypeDescription
idintegerCampaign ID
getFilledTplCampaignTextbool1 - to return the text of the template campaign filled out with real recipient data, by default 0 - campaign's text containing placeholders

Server response

FieldTypeDescription
namestringCampaign name
textstringFull message text, or template text with placeholders, which will later be replaced with a unique text for each message
msgTypestringCampaign message type, at the moment only SMS is supported
fromstringSender's signature
rateLimitintegerSending limit by the quantity
ratePeriodintegerSending limit for the time period. To be ignored, if rateLimit is not set or equals 0
deferredToTsstringDate and time of the campaign, when it is necessary to start sending in the specified time. It should start not later than in 14 days and not earlier than in an hour from the current time. Format: 2013-12-31 15:34:55
mclassinteger0, 1, 2, 3, by default 1 - messages are saved to the Incoming messages folder in the phone, 0 - are displayed as a popup and are not saved (flashSMS), is supported not by all phones, 2 - are saved to SIM-card, 3 - SIM Toolkit SMS
ttlintegerMessage expiration time in minutes makes from 1 min to 3 days (4320 min) from the moment of sending (the parameter is only available for SMS campaigns)
countersobjectDifferent campaign counters. See below for details
counters object fields
FieldTypeDescription
updateTsdatetimeLast counters update time. Format: 2013-12-31 15:34:55
totalNewSegNumintegerTotal number of segments with NEW status
totalAcceptdSegNumintegerTotal number of segments with ACCEPTD status
totalDelivrdSegNumintegerTotal number of segments with DELIVRD status
totalRejectdSegNumintegerTotal number of segments with REJECTD status
totalExpiredSegNumintegerTotal number of segments with EXPIRED status
totalUndelivSegNumintegerTotal number of segments with UNDELIV status
totalDeletedSegNumintegerTotal number of segments with DELETED status
totalUnknownSegNumintegerTotal number of segments with UNKNOWN status
totalPdlivrdSegNumintegerTotal number of segments with PDLIVRD status
totalSegNumintegerTotal number of segments in the campaign. Updates when processing (before sending) messages/campaign segments.
totalNewMsgNumintegerTotal number of messages with NEW status
totalAcceptdMsgNumintegerTotal number of messages with ACCEPTD status
totalDelivrdMsgNumintegerTotal number of messages with DELIVRD status
totalRejectdMsgNumintegerTotal number of messages with REJECTD status
totalExpiredMsgNumintegerTotal number of messages with EXPIRED status
totalUndelivMsgNumintegerTotal number of messages with UNDELIV status
totalDeletedMsgNumintegerTotal number of messages with DELETED status
totalUnknownMsgNumintegerTotal number of messages with UNKNOWN status
totalPdlivrdMsgNumintegerTotal number of messages with PDLIVRD status
totalMsgNumintegerTotal number of messages (not segments). Updates when processing (before sending) messages/campaign segments.
totalNewMsgCostfloatTotal cost of all segments with NEW status
totalAcceptdMsgCostfloatTotal cost of all segments with ACCEPTD status
totalDelivrdMsgCostfloatTotal cost of all segments with DELIVRD status
totalRejectdMsgCostfloatTotal cost of all segments with REJECTD status
totalExpiredMsgCostfloatTotal cost of all segments with EXPIRED status
totalUndelivMsgCostfloatTotal cost of all segments with UNDELIV status
totalDeletedMsgCostfloatTotal cost of all segments with DELETED status
totalUnknownMsgCostfloatTotal cost of all segments with UNKNOWN status
totalPdlivrdMsgCostfloatTotal cost of all segments with PDLIVRD status
totalCostfloatTotal cost of all segments of the campaign. Updates when processing (before sending) messages/campaign segments.
recipientsRejectedintegerNumber of rejected recipients (not included in the campaign). Updates when processing (before sending) messages/campaign segments.

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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.gmbh/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.gmbh');

// API method call
if ($api->call(
    'campaign',
    'getInfo',
    array(
        //campaign ID
        '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.gmbh/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

Receipt of the campaigns list

https://api.mobizon.gmbh/service/Campaign/List

If the filter by campaign creation date or the launch date is not set, then the system automatically sets the filter by creation date for the last 24 hours from the current time(from 00:00:00 of the last 24 hours to the current moment by the user's time). The maximum sampling interval by creation date/launch date makes 90 days when trying to search for a longer interval only the results for the last 90 days before the date of the end of the search interval will return. If you set the start date or the end date only, the second date will be calculated and installed automatically at a distance of 90 days from the set one. If the date range is invalid (the end date is greater than the start date), then the result will be empty. When installing only dates, the time is set automatically - for start dates to 00:00:00, and for end dates to 23:59:59 according to user timezone settings.

Request parameters

ParameterTypeDescription
criteriaarraySearch criteria (see Search criteria)
paginationarrayPagination display options (see Pagination display options)
sortarraySorting options (see Sorting options)
Search criteria
ParameterTypeDescription
criteria[id]integerSearch for # campaign (if this parameter is set, then the compulsory limit by creation date is not used and the search is performed on all campaigns ever created)
criteria[ids]arraySearch for campaign IDs, the parameter should be passed as an array or IDs string, separated by commas,
maximum IDs number makes 10, if this limit is exceeded, the search will occur on the first 10 from the list.
(if this parameter is set, then the compulsory limit by creation date is not used and the search is performed on all campaigns ever created)
criteria[recipient]stringSearch for recipient's number
criteria[from]stringSearch for sender's signature (alfaname)
criteria[text]stringSearch for text of the campaign
criteria[status]stringSearch for campaign status; the list of possible statuses see in documentation
criteria[createDateFrom]stringSearch for campaign creation date, starting from the specified date (date format YYYY-MM-DD)
criteria[createTimeFrom]stringSearch for campaign creation date, starting from the specified date, taking into account the exact time on this day (time format HH:MM:SS) - if the date is not specified, this field is to be ignored
criteria[createDateTo]stringSearch for campaign creation date before the specified date (date format YYYY-MM-DD)
criteria[createTimeTo]stringSearch for campaign creation date before the specified date, taking into account the exact time on this day (time format HH:MM:SS) - if the date is not specified, this field is to be ignored
criteria[sentDateFrom]stringSearch for campaign launch date, starting from the specified date (date format YYYY-MM-DD)
criteria[sendTimeFrom]stringSearch for campaign launch date, starting from the specified date, taking into account the exact time on this day (time format HH:MM:SS) - if the date is not specified, this field is to be ignored
criteria[sentDateTo]stringSearch for campaign launch date before the specified date (date format YYYY-MM-DD)
criteria[sentTimeTo]stringSearch for campaign launch date before the specified date, taking into account the exact time on this day (time format HH:MM:SS) - if the date is not specified, this field is to be ignored
criteria[type]integerSearch for campaign type; the list of available campaign types see in documentation
Pagination display options
ParameterTypeDescription
pagination[pageSize]integerNumber of visible elements on the page
pagination[currentPage]integerCurrent page
Sorting options
ParameterTypeDescription
sort[id]integerCampaign ID
sort[recipient]stringRecipient's number
sort[from]stringSender's signature
sort[text]stringCampaign text
sort[status]stringCampaign status
sort[type]integerCampaign type

Server response

Data array

FieldTypeDescription
itemsarrayList of found campaigns (see Campaigns' list)
totalItemCountintegerTotal number of the elements found
List of campaigns

Every campaign contains the following fields:

FieldTypeDescription
userIdintegerUser ID
partnerIdintegerPartner ID
typeintegerCampaign type
namestringCampaign name
msgTypeintegerMessage type
fromstringSender's signature
textstringMessage text or template in case of template campaign
startTsstringCampaign start time
createTsstringTime of creation
rateLimitintegerSending limit by quantity
ratePeriodintegerTime period for quantity limit
statusintegerCurrent campaign status. See List of possible campaign statuses for details.
creationWayintegerMethod of campaign creation: 1 - WEB,3 - SMPP, 5 - system (e.g. SMS with confirmation code for the form)
isDeletedintegerCampaign deleted: 1 - yes, 0 - no
extrastringSerialized parameters' value (udh, ttl, mclass)
groupsstringCampaign recipients' groups
countersobjectDifferent campaign counters. See below for details

##### counters object fields

FieldTypeDescription
updateTsdatetimeLast counters update time. Format: 2013-12-31 15:34:55
totalNewSegNumintegerTotal number of segments with NEW status
totalAcceptdSegNumintegerTotal number of segments with ACCEPTD status
totalDelivrdSegNumintegerTotal number of segments with DELIVRD status
totalRejectdSegNumintegerTotal number of segments with REJECTD status
totalExpiredSegNumintegerTotal number of segments with EXPIRED status
totalUndelivSegNumintegerTotal number of segments with UNDELIV status
totalDeletedSegNumintegerTotal number of segments with DELETED status
totalUnknownSegNumintegerTotal number of segments with UNKNOWN status
totalPdlivrdSegNumintegerTotal number of segments with PDLIVRD status
totalSegNumintegerTotal number of segments in the campaign. Updates when processing (before sending) messages/campaign segments.
totalNewMsgNumintegerTotal number of messages with NEW status
totalAcceptdMsgNumintegerTotal number of messages with ACCEPTD status
totalDelivrdMsgNumintegerTotal number of messages with DELIVRD status
totalRejectdMsgNumintegerTotal number of messages with REJECTD status
totalExpiredMsgNumintegerTotal number of messages with EXPIRED status
totalUndelivMsgNumintegerTotal number of messages with UNDELIV status
totalDeletedMsgNumintegerTotal number of messages with DELETED status
totalUnknownMsgNumintegerTotal number of messages with UNKNOWN status
totalPdlivrdMsgNumintegerTotal number of messages with PDLIVRD status
totalMsgNumintegerTotal number of messages (not segments). Updates when processing (before sending) messages/campaign segments.
totalNewMsgCostfloatTotal cost of all segments with NEW status
totalAcceptdMsgCostfloatTotal cost of all segments with ACCEPTD status
totalDelivrdMsgCostfloatTotal cost of all segments with DELIVRD status
totalRejectdMsgCostfloatTotal cost of all segments with REJECTD status
totalExpiredMsgCostfloatTotal cost of all segments with EXPIRED status
totalUndelivMsgCostfloatTotal cost of all segments with UNDELIV status
totalDeletedMsgCostfloatTotal cost of all segments with DELETED status
totalUnknownMsgCostfloatTotal cost of all segments with UNKNOWN status
totalPdlivrdMsgCostfloatTotal cost of all segments with PDLIVRD status
totalCostfloatTotal cost of all segments of the campaign. Updates when processing (before sending) messages/campaign segments.
recipientsRejectedintegerNumber of rejected recipients (not included in the campaign). Updates when processing (before sending) messages/campaign segments.
List of possible campaign statuses
StatusDescription
NEWThe campaign has been created, but the user has not yet sent it. Adding recipients is allowed in this status.
MODERATIONWaiting for the moderator to check for compliance with the service rules.
DECLINEDRejected by the moderator because it does not comply with the service rules or the requirements of operators whose numbers are present in the campaign.
READY_FOR_SENDThe campaign is accepted and will be sent.
AUTO_READY_FOR_SENDThe campaign does not need moderation and will be sent.
NOT_YET_SENTStatus for the search. Includes all statuses while a campaign has not yet been sent. Campaigns cannot have this status.
RUNNINGThe campaign is being sent.
DEFERREDCampaign is deferred and will be sent at the specified time.
SENTAll messages have been sent to operators and are waiting for statuses.
DONEAll statuses have been received or reached the maximum status pending time for all SMS and statuses have not been received (default is 24 hours). Once this status is set, no campaign counters are changed.

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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.gmbh/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.gmbh');

// API method call
if ($api->call(
    'campaign',
    'list',
    array(
        //search criteria
        'criteria' => array(
            //alphanumeric sender ID
            'from' => 'Alpha'
        ),
        //pagination parameters
        'pagination' => array(
            //current page
            'currentPage' => '2',
            //number of displayed items per page
            'pageSize' => '50'
        ),
        //sorting parameters
        'sort' => array(
            //sorting by campaign type ascending
            '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;
}

Launching of the campaign

https://api.mobizon.gmbh/service/Campaign/Send

Depending on the moderation flags of the user, who created the campaign, it will end up on moderation or will be immediately queued for sending

Request parameters

ParameterTypeDescription
idintegerCampaign ID

Server response

integer campaign status: 1 - moderation, 2 - sending

Errors codes

CodeDescription
2If the campaign was not found.
10If campaign status failed to change.

Examples

curl -X POST \
  'https://api.mobizon.gmbh/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.gmbh/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.gmbh');

// API method call
if ($api->call(
    'campaign',
    'send',
    array(
        //campaign ID
        '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;
}