SOAP API

Wstecz

This documentation refers to the SOAP API version 3.0.

The following examples are based on the ready-made library created by us for your convenonce, which can be downloaded here.

Introduction

SOAP API is available at https://promosms.com/api/soap/v3.0

The first call parameter for each method is an Authentication class object, containing login credentials.

Authentication

class definition  

FieldTypeRequired
login string yes
password string yes

 

login - user ID or email address

password - API access password (plaintext)

 

Rresponse codes:

Status codes for method execution are individual for each method (for codes 1-399)

  • 0 - operation was successful
  • 00 00012 (110) - 11 11112 (6310) - executed with warnings. Warnings are stored in individual bits and at the same time there can be more than one warning.
  • 100-199 - an error has occurred - not all required data has been provided
  • 200-299 - an error has occurred - the values of the transmitted data are invalid
  • 300-399 - an error has occurred - the account or system configuration does not allow for the execution of the operation
  • 400 - an authentication error (its cause may be an incorrect username/password pair, the IP is not on the list of authorized IP addresses, the limit of login attempts has been exceeded)
  • 401 - 403 - an unexpected error

Sending SMS messages

 

Example PHP

View source
<?php 
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->sendSms(
 $auth,
 new \PromoSms\Soap\SendSmsRequest(
 array(
 new \PromoSms\Soap\Message(
 'Wiadomość testowa', // text
 1, // type
 array('504304204') // recipients
 )
 )
 )
 );
 if ($response->status < 100) {
 echo 'Wiadomość została wysłana. Kosz wysyłki: ' . $response->points . PHP_EOL;
 } else {
 echo 'Error: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
SendSmsResponse sendSms (
 Authentication authentication, 
 SendSmsRequest request 
 )

SendSmsRequestclass definition 

FieldTypeRequired
messages Vector yes
returnRecipientResults boolean no (domyślno false)

 

  • messages - an array/vector of Message type objects
  • returnRecipientResults - the flag that specifies whether the responses in the object are to include the details of each recipient

Message class definition

FieldTypeRequired
text string yes
type integer yes
recipients Vector yes
sender string yes - dla MaxSMS i FasterSMS
specialChars boolean no (domyślno false)
longSms boolean no (domyślno false)
date integer no
binarySms boolean no (domyślno false)
udh string yes jeżeli binarySms = true
deliveryUrl string no
userIndexes Vector no

 

  • text - the contents of the sent message
  • type - the type of the sent SMS message. Permitted types include:
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FasterSMS
  • recipients - an array / vector of message recipients. Therefore, in the string array, there must be recipients' phone numbers (each item in the array is another recipient)
  • sender - SMS sender’s name (displayed instead of the phone number). To use the sender’s own name, it must be registered in advance. In the case of EkoSMS/FlashSMS, this parameter is optional
  • specialChars - by setting this value to “true”, special characters will not be converted to the corresponding standard characters, but the message will be sent in the transmitted form to the system. It must be remembered that sending special characters in the contents of the SMS message, the length of the SMS message will be reduced from the standard 160 characters to 70. Therefore, if you want the PromoSMS platform to remove all non-standard characters (special characters), you must set the value of this variable to “false”.
  • longSms - – by setting this value to “true”, the platform will also accept sending messages longer than 160 characters (or 70, if the specialChars variable is set to “true”). These messages will be delivered as a single message (colloquially: as a single SMS message), but the cost of delivery will be higher (depending on the number of the component messages)
  • date - a timestamp determining the moment when the message is to be sent (a UNIX timestamp expressed in seconds)
  • binarySms - an optional parameter. By setting this value to “true”, a binary SMS will be sent. In this case, you must define an UDH parameter value
  • udh - an UDH header value of the binary messages
  • deliveryUrl - an URL address of user’s server, to which delivery reports are to be transmitted. The URL address can contain the following special variables to be replaced with the relevant value by the system during the transmission of the report to the client server:
    • %smsID - ID of the sent message
    • %timestamp - the date of the report as a Unix timestamp
    • %number - the phone number to which the message was sent
    • %report - report ID (1 means that the message has been delivered)
    • %ownID - user's own ID
  • userIndexes - this parameter allows the user to define their own message identifiers. The number of items in the array/vector must be equal to the number of the defined message recipients. Then each message will be assigned the next item from the array. It is also possible to define one element for this array/vector, so that all sent messages are assigned the same identifier.

  SendSmsResponse class definition

FieldType
status integer
points float
sentSmsCount integer
contentIds Vector
recipientsResults Vector

 

  • status - response code
  • points - the cost of delivery (expressed in points)
  • sentSmsCount - the number of successfully sent messages
  • contentIds - vector of the sent content identifiers
  • recipientsResults - vector of the RecipientResult objects (or null if the returnRecipientResults input parameter has not been set to “true”)

 

SendSms method response codes:

CodeDescription
012 (110) The message has been forwarded for delivery in the future
102 (210) Some of these phone numbers are invalid
100 No recipients have been specified for delivery
101 Content not specified
102 Sender field not specified
103 UDH field not specified
104 No specified single object of the Message
200 All specified phone numbers are invalid
201 Sender name is too long
202 You cannot send messages to the past period
203 Number of own identifiers is incompatible with the number of recipients
204 The message is longer than 1 SMS message
205 Message is longer than 4 SMS messages (max.)
206 More than one recipient of the FasterSMS delivery has been specified
207 The content contains characters outside the Unicode set
208 One delivery contains recipients from various countries
209 Invalid message type
300 Account balance does not allow delivery
301 Sender's name has not been registered
302 Cannot send this type of message to the selected country
303 Account has not been adapted to use this API version

  RecipientResult class definition

FieldType
recipient string
contentId integer
smsId string
ownId string
status integer

 

  • recipient - recipient's phone number
  • contentId - content identifier (simultaneously sent messages with the same content are of equal value of this parameter)
  • smsId - individual identifier of the message
  • ownId - identifier assigned by the user
  • status - message transfer status
    • 0 - forwarded
    • 210 - invalid number

Delivery reports

 

Example PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->sendSms(
 $auth,
 new PromoSms\Soap\GetReportsRequest(
 array('098f6bcd4621d373cade4e832627b4f6'), // indexes
 null, // fromTime
 null, // toTime
 0 // indexType
 )
 )
 if ($response->status < 100) {
 var_dump($response->reports);
 } else {
 echo 'Error: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
GetReportsResponse getReports (
     Authentication authentication,
    GetReportsRequest request
 )

  class definition

GetReportsRequest
FieldTypeRequired
indexes Vector no
fromTime integer no
toTime integer no
indexType integer yes, if use indexes
limit integer no
offset integer no

 

  • indexes - the array or vector of message identifiers. Depending on the value of the indexType field, these are smsId identifiers, user identifiers (userIndex) or content identifiers (contentID)
  • fromTime - time (as a Unix timestamp), from which we want to get information about status codes of sent messages
  • toTime - time (as a Unix timestamp), until which we want to get information about status codes of sent messages
  • indexType - identifier type
    • 0 - smsId
    • 1 - userIndex
    • 2 - contentId
  • limit - option useful when you need to retrieve a large number of status codes (e.g. several tens of thousands). Then you can limit the number of returned items in the array/vector
  • offset - this field determines from what point the array/vector is to be returned. The value of this field is taken into account only when the limit parameter is applied,

  GetReportsResponse class definition

FieldType
status integer
reports Vector

 

  • status - response code
  • reports - reports array/vector

 

CodeDescription
012 (110) Part of message IDs is invalid
100 ID type not specified
101 Message IDs not specified
200 All specified IDs are invalid
201 Invalid timestamp
202 Invalid ID type
203 Invalid limit parameter value
204 Invalid offset parameter value

  Report class definition

FieldType
recipient string
smsId string
ownId string
contentId integer
status integer
lastUpdateTime integer

 

  • recipient - recipient's phone number
  • smsId - a unique message identifier
  • ownId - identifier assigned by the user
  • contentId - content identifier
  • status - delivery status
    • 0 - message waiting to be sent
    • 4, 8 - message has been sent
    • 1 - message was delivered to the recipient
    • 2, 16 - message has not been delivered - the most common causes of this status are incorrect phone number or too long inactivity of the recipient's phone
  • lastUpdateTime - status last update time

Receiving replies

 

To send a message using EkoSMS or MaxSMS feature using a purchased phone number, it is possible for the recipient of the message to reply. Such replies are available both through the Panel SMS and SOAP API.

 

Receiving messages is done by calling the getInbox method

 

Example PHP

View source
<?php require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->getInbox(
 $auth,
 new \PromoSms\Soap\GetInboxRequest(
 null, // lastMessageId
 strtotime('2015-08-01 00:00:00'), // fromTime
 null, // contentId
 null, // smsId
 null // ownId
 )
 );
 if ($response->status < 100) {
 var_dump($response->inboxMessages);
 } else {
 echo 'Error: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
GetInboxResponse getInbox (
 Authentication authentication, 
 GetInboxRequest request 
 )

  GetInboxRequest class definition

FieldTypeRequired
lastMessageId integer no
fromTime integer no
contentId integer no
smsId string no
ownId string no

 

  • lastMessageId - each received SMS message has a unique identifier in the form of a number. If you want to receive a message only from the specified message with a known identifier – you must specify it here. Therefore, if when receiving the message the last read message was numbered 359 and now you want the function to only return newer messages – then the value of this parameter should be given as 359.
  • fromTime - if you want to retrieve all messages from a specified moment instead of using the message ID, you must specify it here as a Unix timestamp.
  • contentId - if this parameter is set, replies are returned only to messages with the specified content identifier
  • smsId - a unique message identifier
  • ownId - message identifier assigned by the user

  GetInboxResponse class definition

FieldType
status integer
inboxMessages Vector

 

  • status - response code
  • inboxMessages - reply array/vector

 

CodeDescription
012 (110) No new replies
200 Invalid reply ID
201 Invalid timestamp
202 Invalid content ID

 InboxMessage class definition

FieldType
messageId integer
sender string
message string
originalMessage string
receiveTime integer

 

  • messageId - reply identifier
  • sender - phone number of the reply sender
  • message - message content
  • originalMessage - message contents to which the reply relates
  • receiveTime - the time the message was received (as a Unix timestamp)

 

Checking account status

 

The account status is checked by calling getBalance

 

Example PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->getBalance($auth); if ($response->status < 100) {
 echo 'Stan konta: ' . $response->pointsAvailable . PHP_EOL;
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
GetBalanceResponse getBalance (
 Authentication authentication 
 )

  GetInboxResponse class definition

FieldType
status integer
pointsAvailable integer
pointsBlocked integer
pointsCredit integer

 

  • status - reply code
  • pointsAvailable - the number of points available for use
  • pointsBlocked - number of blocked points (as a result of scheduled delivery)

 

CodeDescription
300 The account is not suitable for use this API version

Converting messages

 

While sending, the message is converted to the GSM standard, and then the number of component messages and the cost of such delivery is calculated. This conversion is done by calling convertMessage

 

Example PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $client->convertMessage(
 $auth,
 new PromoSms\Soap\ConvertMessageRequest(
 'W Mińsku lżą naftę Jóź. Gość brzydł. Pech!', // text
 false, // specialChars
 true, //longSms
 1, //smsType
 'PL', // countryCode
 null, //countryPrefix
 null //countryName
 )
 );
 
 if ($response->status < 100) {
 echo 'Wiadomość po konwersji: ' . $response->text . PHP_EOL 'Liczba znaków: ' . $response->charsNumber . PHP_EOL 'Liczba wiadomości składowych: ' . $response->smsParts . PHP_EOL 'Koszt wysyłki: ' . $response->points . PHP_EOL ; } else {
 echo 'Error: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
ConvertMessageResponse convertMessage (
 Authentication authentication, 
 ConvertMessageRequest request 
 )

  ConvertMessageRequest class definition

FieldTypeRequired
text string yes
specialChars boolean yes
longSms boolean no (domyślno true)
smsType integer no
countryCode string no
countryPrefix string no
countryName string no

 

  • text - message content, on the basis of which the number of characters and the number of component SMS messages is to be calculated
  • specialChars - if the parameter is set to “true”, then special characters are permitted in the message and they will not be replaced with counterparts in standard characters. If, however, the parameter is set to “false”, then all special characters will be converted, and only then the length of messages and the number of component SMS messages will be calculated.
  • longSms - if the field is set to “true”, the message will be cut to the length of one SMS message.
  • smsType - type of SMS messages. If this field, together with one countryCode / countryPrefix / countryName fields are not empty, the cost of sending the message to a single recipient will be included in the reply.
    • 0 - FlashSMS
    • 1 - EkoSMS
    • 3 - MaxSMS
    • 4 - FastSMS
  • countryCode - country code of the recipient in the form of two letters
  • countryPrefix - recipient’s country prefix
  • countryName - name of the recipient’s country

  ConvertMessageResponse class definition

FieldType
status integer
charsNumber integer
smsParts integer
text string
points float

 

  • status - reply code
  • charsNumber - total number of message characters
  • smsParts - the number of component SMS messages
  • text - message content. If the “false” value is assumed in bSpecialChars input parameters, then the original content of the message will not be returned here, but the content of the converted message
  • points - the calculated cost of delivery (if the request contains a specified type of the message and country of delivery)

 

CodeDescription
100 Content not specified
101 Type of SMS message not specified
200 Message too long (exceeding 4 component SMS messages)
201 Various countries of delivery have been specified
202 The specified country of delivery does not exist
300 Sending this type of messages to a specified country is not available

Validating the numbers

 

Metoda validateNumbers method makes it possible to validate numbers in terms of syntax. Therefore, we check if, for example, number +48531100112 has the correct form and if this number is possible.

 

Example PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->validateNumbers(
 $auth,
 new \PromoSms\Soap\ValidateNumbersRequest(
 '48', // countryPrefix
 array('504304204') // numbers
 )
 );
 if ($response->status < 100) {
 $number = $response->numbers[0]; if ($number->isValid) { echo 'Numer ' . $number->formatted . ' jest poprawny' . PHP_EOL; } else { echo 'Number' . $number->original . ' numer jest nopoprawny' . PHP_EOL; } } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
ValidateNumbersResponse validateNumbers (
 Authentication authentication, 
 ValidateNumbersRequest request 
 )

  ValidateNumbersRequest class definition

FieldTypeRequired
countryPrefix string yes
numbers Vector yes

 

  • countryPrefix - the prefix of the country from which a call is initiated. For example, if it is 48, then the following numbers are treated as Polish numbers: 512345678, 48512345678, +48512345678. In addition, this is the same number recorded in different ways. However, if the field is set to 49, then only the latest example will be treated as a Polish number.
  • numbers - an array/vector of numbers. If the number has a different country prefix than the number specified in the countryPrefix field, then use the + (plus) symbol

  ValidateNumbersResponse class definition

FieldType
status integer
numbers Vector

 

  • status - the response code
  • numbers - an array / vector with detailed information about the phone number

 

CodeDescription
012 (110) Some of the specified numbers are invalid
102 (210) All specified numbers are invalid
100 No phone numbers have been specified

  Number class definition

FieldType
originalNumber string
isValid boolean
isValidForRegion boolean
probablyExists boolean
countryPrefix string
countryCode string
formatted string
type integer

 

  • originalNumber - the form in which the number has been specified in the request
  • isValid - the flag that determines if the number is valid
  • isValidForRegion - the flag that determines if the number belongs to a given prefix zone
  • probablyExists - the flag that determines if the number is probably true
  • countryPrefix - country prefix
  • countryCode - country code in the form of two letters
  • formatted - phone number with a country prefix
  • type - phone number type:
    • 1 - Landline phone number
    • 2 - Mobile phone number
    • 3 - Landline or mobile phone number
    • 4 - Toll-free number (e.g. the number with a 800 ... prefix)
    • 5 - Premium rate number
    • 6 - The cost of the call is shared between the recipient and the sender (e.g. the number with a 801 ... prefix)
    • 7 - VoIP number
    • 8 - it is possible that one number is also the number of the mobile phone/landline phone (see: http://en.wikipedia.org/wiki/Personal_Numbers )
    • 9 - Pager
    • 10 - the so-called Universal Access Numbers or Company Numbers (one company number, but the connection can be properly switched over)
    • 10 lub -1 - invalid or different number, unidentified number type

 

Warning! The validateNumbers method checks the number for semantics. This is not a check of the number with the operator!

 

Adding contacts

 

SOAP API allows you to add contacts to the address book using addContacts

 

Example PHP

View source
<?php
 require_once('Client.php');
 
 $promoSms = new \PromoSms\Soap\Client();
 $auth = new \PromoSms\Soap\Authentication('login@example.com', 'secretPassword');
 
 $response = $promoSms->addContacts(
 $auth,
 new \PromoSms\Soap\AddContactsRequest(
 array( new \PromoSms\Soap\Contact( '504304204', // phone 'PromoSMS', // name ) ), array('Grupa testowa'), // groups true // createGroupsIfNotExist )
 );
 if ($response->status < 100) {
 echo 'Dodano następującą liczbę konyestów: ' . $response->contactsCount . PHP_EOL;
 } else {
 echo 'Wystąpił błąd: ' . $response->status . PHP_EOL;
 }

 

Definition

View source
AddContactsResponse addContacts (
 Authentication authentication, 
 AddContactsRequest request 
 )

  AddContactsRequest class definition

FieldTypeRequired
contacts Vector yes
groups Vector no
createGroupsIfNotExist boolean no (implicitly false)

 

  • contacts - an array / vector of Contact objects
  • groups - an array / vector of contact group identifiers
  • createGroupsIfNotExist - the flag that determines whether or not to create a new group when the value specified in the groups field does not exist in the system

  Contact class definition

FieldTypeRequired
phone string yes
name string no
firstName string no
lastName string no
customField1 string no
customField2 string no
customField3 string no
customField4 string no
customField5 string no
customField6 string no

 

  • phone - Phone number
  • name - Contact name. By default, it has the same value as the phone field
  • firstName - First name
  • lastName - Last name
  • customField1 - customField6 - additional fields that can be used to send personalized messages

  AddContactsResponse class definition

FieldType
status integer
contactsCount integer

 

  • status - reply code
  • contactsCount - number of contacts added

 

CodeDescription
100 Contacts not specified
101 No phone number in the contact
200 Invalid phone numbers
300 The account does not have a fixed default country of delivery