Registration

Module Message

Creation, sending and other functions to work with single messages (not campaigns).

API methods

Getting of SMS message delivery status report
https://api.mobizon.gmbh/service/Message/GetSMSStatus

Getting of the list of SMS messages
https://api.mobizon.gmbh/service/Message/List

Sending of a single message
https://api.mobizon.gmbh/service/Message/SendSmsMessage

Getting of SMS message delivery status report

https://api.mobizon.gmbh/service/Message/GetSMSStatus

The method accepts both a string with one message ID and an array of message IDs. Regardless of the type of the input parameter, the returned result is always represented as an array. If you send non-existent or not-owned by the user message IDs, the result will not contain information about these messages.

List of possible message statuses

See List of possible statuses of messages table.

Request parameters

ParameterTypeDescription
idsarray | stringMessage ID(s) is (are) an array or a string of Ids, separated by commas. Maximum equals to 100 characters.

Server response

FieldTypeDescription
idintegerMessage ID
statusstringMessage status
segNumintegerNumber of segments in the message
startSendTsstringMessage sending start time
statusUpdateTsstringLast status update of the message

Errors codes

CodeDescription
2If none of the message ID was specified
12If more then 100 message Ids were specified.

Examples

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

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

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

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

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

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

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

Getting of the list of SMS messages

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

Request parameters

ParameterTypeDescription
criteriaarraySearch criteria (see Search criteria)
paginationarrayPagination display options (see Pagination display options)
sortarraySorting options (see Sorting options)
withNumberInfointegerRecipient information retrieval flag, by default - 0
Search criteria
ParameterTypeDescription
criteria[id]integerMessage ID
criteria[campaignId]integerCampaign ID
criteria[campaignIds]arraySearch by campaign IDs; the parameter should be passed as an array or a string of IDs, separated by commas, the maximum number of IDs equals to 10; when this limit is exceeded, the search will occur on the first 10 entries of the list (if this parameter is set, then a forced limitation on the creation date is not used and search runs on all campaigns ever created)
criteria[from]stringSender's signature
criteria[to]stringRecipient number
criteria[text]stringMessage text
criteria[status]integerMessage status
criteria[groups]stringMessage recipient groups
criteria[contentProviderId]integerSMS centre ID
Pagination display options
ParameterTypeDescription
pagination[pageSize]integerNumber of visible elements on the page
pagination[currentPage]integerCurrent page
Sorting options
ParameterTypeDescription
sort[id]integerMessage ID
sort[campaignId]integerCampaign ID
sort[from]stringSender's signature
sort[to]stringRecipient number
sort[text]stringMessage text
sort[status]integerMessage status
sort[groups]stringMessage recipient groups
sort[contentProviderId]integerSMS centre ID

Server response

Data array

FieldTypeDescription
itemsarrayList of found messages (see List of messages)
totalItemCountintegerTotal number of the elements found
List of messages

Each of the messages contains the following fields:

FieldTypeDescription
idintegerMessage ID
campaignIdintegerCampaign ID
segNumintegerNumber of segments
segUserBuyfloatSegment purchase price for a user in his currency
fromstringSender's signature
tostringRecipient number
textstringMessage text
statusstringMessage status (See List of possible statuses of messages table)
groupsstringMessage recipient group ID, this number belonged to at the time of the campaign
uuidstringInternal message ID
countryA2stringRecipient's country code
operatorNamestringRecipient's operator

Examples

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

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

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

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

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

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

// API method call
if ($api->call(
    'message',
    '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 ID ascending
            'campaignId' => 'ASC'
        )
    )
)
) {
    // Getting the result of an API request
    $result = $api->getData();
} else {
    // An error occurred during execution. Error code and message text output
    echo '[' . $api->getCode() . '] ' . $api->getMessage() . PHP_EOL;
}

Sending of a single message

https://api.mobizon.gmbh/service/Message/SendSmsMessage This message allows to send a single message to a specified mobile phone number.

Request parameters

ParameterTypeDescription
recipientstringSMS message recipient - number in international format, if the number contains + in the beginning, it should be encoded in the URL entity %2B or delete, leaving numbers only.
textstringSMS message text, encoded in the URL entity. If whilst attempting to send a message using a GET request, the system does not return the response with the message data, you should first check the presence of special characters in the request body, such as: ? / \ & + and [space] .
fromstringSender's signature. It is ok not to specify it, then in case there isn't any valid signature, the general system signature will be used.
Note: The signature may be different for each operator and may be changed without a prior notice at any time. If there are any confirmed signatures, the one, for which the "By default" flag is set, will be used.
paramsarrayAdvanced settings (see Advanced settings).

Advanced settings

ParameterTypeDescription
params[name]stringName fo the campaign
params[deferredToTs]stringDate and time of the campaign, if it is necessary to postpone the campaign until the specified time. Should start not later than 14 days and not earlier than an hour from the current time. Format: 2013-12-31 15:34:55
params[mclass]integerThe method of SMS processing by a mobile device.
0 - are displayed as a popup and are not saved (flashSMS), is supported not by all phones;
1 (by default) - messages are saved to the Incoming messages folder in the recipient's phone;
2 - are saved to SIM-card;
3 - SIM Toolkit SMS
params[validity]integerSMS message expiration time in minutes makes from 1 min to 3 days (4320 min) from the moment of sending. By default: 1440 (24 hours)

Server response

FieldTypeDescription
campaignIdintegerSMS campaign ID (using it, you can later check various parameters of the campaign, request a list of segments, their statuses and other information of the campaign module)
messageIdintegerSMS message ID (using it, you can check the message delivery status with a help of message::getsmsstatus
statusintegerSMS campaign sending status .
1 - campaign awaits moderation,
2 - campaign was sent without prior moderation

Errors codes

CodeDescription
1If at least one parameter is invalid

Examples

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

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

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

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

xhr.send(data);
<?php

use 'Mobizon\MobizonApi.php';

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

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

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