Comma separated list of destination numbers. Czech numbers can be without international
prefix (+420), other numbers must be with international (country) prefix.
Parameter is mandatory. There must be at least one valid phone number.
text
SMS text. Maximal length is 1000 characters. This parameter should contain URL in case of wappush.
System will create SMS parts automatically.
name
Wappush name. This parameter has no meaning in case of text SMS.
Parameter is only for text SMS (type text). For other types this
parameter is ignored.
delivery
Parameter defining that delivery report should be passed to registered address.
Use value 1, if you want to receive delivery report. You should
omit this parameter or pass 0, if you do not want to receive
delivery report.
address
Address (URL or email) where delivery report should be passed to.
You should use this parameter if you want to receive delivery reports on
other address than registered one (or you have no address registered).
If you pass both address and delivery parameters.
address has precedence.
senddate
Date and time when SMS will be sent. If you want to define, when SMS should be sent,
pass this parameter.
Default value is empty parameter - SMS will be sent immediately.
Billing is done at the time SMS is about to be sent. It is possible that API request
will be successful, but in case there are not enough credit on account, SMS will not be sent.
Valid value of this parameter is GNU date value (or PHP strtotime()
function value).
//possible values
"2011-03-05 15:00:00" = 3/5/2011, 15:00
(date and time in yyyy-mm-dd hh:ii:ss format = year, month, day, hour, minute, second)
"+1 hour" = in one hour
"next Monday" = next Monday (v 00:00)
"next Monday 15:15" = next Monday at v 15:15
source
Sender's number or identifier.
Default value is empty parameter - SMS will be sent from ProfiSMS number.
Valid value can be either phone number in international format (with prefix) or
text containing English letters, numbers and . and - (dot and dash).
Text source can be 11 characters long. In case source is longer or contains invalid
characters, such a source will be fixed by system.
If session exists, source is not used. If session is used, SMS is sent from regular MSISDN, session takes precedence.
Generally user can use only registered sources - numbers registered in
user interface.
If you want to use other identifiers (e.g. text one), you should contact our
business department.
currency
Account currency used to bill SMS. Values are listed in
constants.
Default value is CZK.
validity
Number of minutes this SMS is valid for.
Value represents number of minutes since SMS is passed to mobile operator (actually sent).
If SMS is not delivered in this time, SMS will expire
(see delivery states).
Default value is 2880 (2 days).
Maximal value is 2880, minimal value is 5.
pid
Random string, unique identifier of batch. Parameter has no meaning in case of sending
one SMS (this API description), since this API represents one batch.
Value 1 represents that SMS will not be listed,
value 0 represents that SMS will be listed.
Default value is 0.
userdata
Any textual data that will be saved with SMS.
usersource
Any textual data. Data should represent "source" of SMS. If user for example has more communications channels, departments, etc,
this parameter represents the name of such source. This source can be used for listing / filtering of SMS messages.
session
System provides ability to receive response to sent SMS. If SMS is sent to particular number, this parameter is set and system
receives SMS from that particular number (within one day), this SMS will be assigned to the user who sent the SMS from the system.
This setting (session) is valid for the last user, who sends SMS to particular number (for each number there can only be sessions from one user).
Session can only be used without text ident,source. If session is used, SMS is sent from regular MSISDN.
rm_diacritics
Parameter for Axima clients, parameter removes diacritics.
A value of 1 means that the characters will be removed, a value of 0 means that they will remain unchanged.
Value (if the parameter is not specified) is 0.
maxFragmentsLimit
Parameter for Axima clients, the parameter sets a limit for fragmentation of messages stored in the database.
Value (if the parameter is not specified) is null.
API request examples
example 1: Basic request to send SMS (PHP implementation)
If you want to send SMS to large number of phone numbers or if you want to send long SMS,
you should use POST protocol, since URL is limited to 2048 characters.
Array of invalid numbers.
SMS is sent to all valid numbers and this array contains with invalid numbers.
If all numbers are invalid (or no destination number is passed) such a call will end up with
SMSOUTSMS_MISSING_MSISDN
error.
sms
Array with SMS objects, see below.
credit
Balance on account used to bill sent SMS (after sending).
price
SMS sending price (without VAT). Currency is the requested one.
pricevat
SMS sending price (with VAT). Currency is the requested one.
address
Delivery report address (based on delivery or address parameters).
partsCount
Number of SMS parts for each SMS.
Parameter does not represents all SMS parts created by this request. This value is based
on valid destination numbers.
pid
Passed parameter pid.
Description of sms array
Object data contains sms property.
This property is an array containing objects representing SMS (already sent or queued).
There is an object for each valid destination number.
Each SMS object has following properties:
msisdn
Destination phone number (formated as international).
id
SMS unique identifier (it is not sequence number).
Value is a number at this point, but this parameter will change type to string in
the future.
This identifier is used for passing delivery reports and for SMS informations requests.
If at least one destination number is valid, SMS is sent to this number. No error occurred.
If SMS is not delayed (is to be charged with request), there must be enough credit
on account to sent SMS to all valid requested numbers, otherwise
BA_LOW_CREDIT
error is returned.
If SMS is delayed, each destination number sending is charged separately while sending.
Insufficient credit while requesting does not end up with error.
Delivery reports
Delivery reports are passed in case delivery or address parameters
are in request.
Delivery reports are sent to email or passed to URL with additional parameters attached
to identify delivery state.
Delivery reports are passed/sent for whole SMS and all SMS parts (with exception described below).
Delivery reports send to email address
In case delivery report should be sent to email than:
If SMS is sent as one (there is only one SMS part), only report for whole SMS is sent
(since SMS part report would be the same).
If there are more than 1 SMS part, email for every part is sent as parts change
delivery state. And once there are delivery states for all parts, email for whole
SMS is sent.
Delivery reports passed to URL
In case of delivery reports passed to URL, reports are passed for all parts and whole SMS
even if SMS was sent as one (there is only one SMS part).
Delivery report is passed using defined URL with additional parameters with
SMS or SMS part informations (thus using GET protocol).
In case SMS part delivery state changes, defined URL is called with parameters.
In case of whole SMS, defined URL is called with parameters once all parts change their
state.
Parameters passed in case of SMS part
Some passed parameters, their names and values types are inconsistent with requests parameters
due to compatibility issues.
msisdn
Destination number.
msg
First 500 characters of SMS part text.
queuetime
Date and time when SMS part was sent (yyyy-mm-dd hh:ii:ss) sent, not just queued.
deliveredtime
Date and time when SMS part changed its delivery state (yyyy-mm-dd hh:ii:ss). Value can be rounded down to minutes.
Parameter will have value 1,
if SMS part is delivered (Smsout::DELIVERY_DELIVERED), 0
in other cases.
smsid
SMS part identifier (see part property in response when sending SMS).
fullsmsid
SMS identifier (see id property in response when sending SMS).
example 9: URL calling
/**
Following example shows delivery report to defined URL for SMS with text
příliš žluťoučký kůň úpěl ďábelské ódy, PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY
which was dividend into 2 parts, both delivered.
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=p%C5%99%C3%ADli%C5%A1%20%C5%BElu%C5%A5ou%C4%8Dk%C3%BD%20k%C5%AF%C5%88%20%C3%BAp%C4%9Bl%20%C4%8F%C3%A1belsk%C3%A9%20%C3%B3dy,%20P%C5%98%C3%8DLI%C5%A0%20%C5%BDLU%C5%A4OU%C4%8CK%C3%9D%20K%C5%AE%C5%87%20%C3%9AP%C4%9AL%20%C4%8E
&queuetime=2010-12-28%2017:55:03&deliveredtime=2010-12-28%2017:56:00
&statdeliver=0&statdeliverstr=delivered&ok=1&smsid=44109244
&fullsmsid=1544185
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=%C3%81BELSK%C3%89%20%C3%93DY&queuetime=2010-12-28%2017:55:03
&deliveredtime=2010-12-28%2017:56:00&statdeliver=0
&statdeliverstr=delivered&ok=1&smsid=44109245
&fullsmsid=1544185
*/
Parameters passed in case of SMS
Some passed parameters, their names and values types are inconsistent with requests parameters
due to compatibility issues.
msisdn
Destination number.
msg
First 500 characters of SMS text.
queuetime
Date and time when last SMS part was sent (yyyy-mm-dd hh:ii:ss) sent, not just queued.
deliveredtime
Date and time when last SMS part changed its delivery state (yyyy-mm-dd hh:ii:ss). Value can be rounded down to minutes.
Parameter will have value 1,
if all SMS parts are delivered (Smsout::DELIVERY_DELIVERED), 0
in other cases.
smsid
Fixed value 0.
fullsmsid
SMS identifier (see id property in response when sending SMS).
example 10: URL call
/**
Following example shows delivery report to defined URL for SMS with text
příliš žluťoučký kůň úpěl ďábelské ódy, PŘÍLIŠ ŽLUŤOUČKÝ KŮŇ ÚPĚL ĎÁBELSKÉ ÓDY
SMS was delivered
http://test.company.cz/receive.php?msisdn=%2B420605582922
&msg=p%C5%99%C3%ADli%C5%A1%20%C5%BElu%C5%A5ou%C4%8Dk%C3%BD%20k%C5%AF%C5%88%20%C3%BAp%C4%9Bl%20%C4%8F%C3%A1belsk%C3%A9%20%C3%B3dy,%20P%C5%98%C3%8DLI%C5%A0%20%C5%BDLU%C5%A4OU%C4%8CK%C3%9D%20K%C5%AE%C5%87%20%C3%9AP%C4%9AL%20%C4%8E%C3%81BELSK%C3%89%20%C3%93DY
&queuetime=2010-12-28%2017:55:03&deliveredtime=2010-12-28%2017:55:00
&statdeliver=0&statdeliverstr=delivered&ok=1&smsid=0&fullsmsid=1544185
*/
SMS sent using PDU and UDH
SMS is sent using
PDU (message data) and
in case of some specific messages using
UDH (message type, message header).
If sending text SMS, even with diacritic, even long SMS (concatenated SMS) and wappushes,
PDU and UDH will be created by system if you use API described above.
But if you want to send other types of messages or you have PDU and UDH already calculated,
you can send such a messages directly.
API request parameters
API for sending messages using PDU and UDH is almost the same as API
descried above.
If some of the standard parameters
is missing in the list below, its meaning remains unchanged.
Standard values are 7 (for text SMS without diacritic - characters from ASCII7),
16 (for text SMS with diacritic - containing characters that are not from ASCII7) and
8 (for binary SMS).
udh
Message UDH.
UDH must contain bits describing its length. Parameter should be passed in hexadecimal format.
pdu
Message PDU.
In case of 7 bits encoding, parameter must contain message text (plain text).
In other cases, value should be passed in hexadecimal format.
Response format remain unchanged.
Example using UDH and PDU.
example 11: Request (PHP implementation)