SOAP Protocol Description for TurboSMS Gateway

SOAP is an extension of the XML-RPC protocol that allows for remote procedure calls. You can learn more about it on Wikipedia. To connect to our server via the SOAP protocol, you need to install the necessary modules and libraries for SOAP support in your development environment. If the required modules and libraries are unavailable, you can generate the required XML structure and send it to our server via RAW POST. The description of SOAP request structures can be found on Wikipedia.

To connect to our gateway using the SOAP protocol, you must check the "SOAP" option in the "Connection Methods" field in the gateway settings section.

The file describing available procedures and their prototypes is located at:
http://turbosms.in.ua/api/wsdl.html.

Please note!

Do not set a timeout on HTTP requests for sending messages because our server will fully process your request. However, you may not receive a response with message IDs, which might lead you to resend the message, creating duplicates of already sent messages.

Our Server Supports the Following Procedures:

  1. Auth — authenticates the user on the server
  2. GetCreditBalance — returns the user's account balance
  3. SendSMS — sends messages
  4. GetMessageStatus — returns the delivery status of a message

1. Auth — authenticates the user on the server

Input Parameters

Parameter Type Description Mandatory
login string Your gateway login Yes
password string Your gateway password Yes

Output Parameters

Parameter Type Description Possible Values Explanation
AuthResult string Authentication result Вы успешно авторизировались Authentication was successful
Не достаточно параметров для выполнения функции Not all required parameters were provided
Неверный логин или пароль The provided login and password were not found. Note that the login and password should not be the ones you use to log in to the website, but those specified in the "Gateway Connection" section. This message is also returned when the "SOAP" connection method is not enabled in the user gateway settings.
Ваша учётная запись не активирована, свяжитесь с администрацией For some reason, your account is not activated. You cannot use any TurboSMS services until your account is activated.
Ваша учётная запись заблокирована за нарушения, свяжитесь с администрацией Your account is blocked by the administrator. No TurboSMS services are available to you.
Ваша учётная запись отключена, свяжитесь с администрацией The administrator disabled your account. TurboSMS services are also unavailable to you.

2. GetCreditBalance — returns the user's account balance

Input Parameters

None.

Output Parameters

Parameter Type Description Possible Values Explanation
GetCreditBalanceResult string Remaining credits on the user's account Number The number of credits
Вы не авторизированы
  • The method was called without calling the Auth method
  • The Auth method did not return successful authentication
  • The authentication session was lost

3. SendSMS — sends messages

Input Parameters

Parameter Type Purpose Required
sender string Phone number or sender's signature Yes
destination string Recipient's phone number (in international format).
Multiple numbers can also be specified, separated by commas.
Yes
text string SMS text No 1
wappush string WAP Push link No 1

1 Note that either the "text" or "wappush" parameter must be provided. If neither is provided, you will receive a "missing parameters" error.

Output Parameters

Parameter Type Purpose Possible Values Description
SendSMSResult[0] string Message sending result Сообщения успешно отправлены 1
Не достаточно параметров для выполнения функции Not all required parameters were provided
Вы не авторизированы
  • The method was called without calling the Auth method
  • The Auth method did not return successful authorization
  • The authorization session was lost
Неправильная подпись.\nПодпись отправителя не должна быть длиннее 11 символов и может содержать буквы латинского алфавита, цифры, а также знаки: .-& The sender's signature does not comply with GSM standards
Данная подпись запрещена администратором You cannot use this sender's signature
Insufficient X credits to send SMS Not enough credits in the account to send the message
Не удалось распознать номер получателя 1 Some recipient numbers do not meet the standard
Невозможно отправить SMS
При отправке SMS возникли ошибки. Если ошибка будет повторяться, сообщите об этом в службу поддержки, указав свой логин, время отправки, подпись отправителя и текст сообщения.
Possible connection issues between our platform and operators' platforms
Не удалось отправить сообщение на некоторые номера 1 Some numbers were not recognized or were rejected by the operator
Не удалось сохранить данные сообщения, свяжитесь с администрацией Our database may be overloaded, or the message contains invalid characters
Не удалось распознать статус отправки сообщения, свяжитесь с администрацией, указав тип подключения, время отправки и данные отправляемого сообщения The SMS sending result was not recognized
SendSMSResult[1..X] 2 string ID of the sent message c9482a41-27d1-44f8-bd5c-d34104ca5ba9 Message IDs are provided in UUID format

1 The message "Сообщения успешно отправлены" may also include "Не удалось распознать номер получателя" or "Не удалось отправить сообщение на некоторые номера"

2 If multiple numbers were provided, the response parameter key 1 will contain the message ID for the first number, key 2 for the second, and so on. If a message cannot be sent to a given number for any reason, the corresponding key will indicate the reason.

4. GetMessageStatus — returns the delivery status of a message

Input Parameters

Parameter Type Purpose Required
MessageId string Message ID in UUID format Yes

Output Parameters

Parameter Type Purpose Possible Values Description
GetMessageStatusResult string Current delivery status of the message The message with ID X was not found 1 The message ID is not present in the database
Не достаточно параметров для выполнения функции Not all required parameters were provided
Вы не авторизированы
  • The method was called without calling the Auth method
  • The Auth method did not return successful authorization
  • The authorization session was lost
Отправлено The delivery status has not been updated yet
В очереди The message has not been sent yet
Сообщение передано в мобильную сеть The message has been delivered to the operator's server
Сообщение доставлено получателю
Истек срок сообщения The delivery status was not received in time, the message was lost
Удалено оператором The message violates some operator rules
Не доставлено
Сообщение доставлено на сервер The message is on the sending server
Отклонено оператором The message violates some operator rules or cannot be delivered to the recipient
Неизвестный статус Contact the technical department for more information
Ошибка, сообщение не отправлено The message sending failed, contact the technical department for more information
Не достаточно кредитов на счете The message was not sent, replenish your internal account
Отправка отменена The message sending was canceled by the user or administrator
Отправка приостановлена The message sending was interrupted by the user or administrator
Удалено пользователем The user or administrator deleted the message

1 Note: If you have access to multiple accounts, you must check the delivery status of a message from the same account it was sent from.

Examples of Working with Our Service:

  1. PHP Code
  2. Project for .NET
  3. Module for Yii2 Framework
  4. Ruby Gateway Integration
  5. Golang Gateway Integration

1. PHP Code

<?php
/**
 * This example demonstrates how to send SMS messages
 * with a sender ID, check the user's credit balance,
 * and view the status of sent messages.
 * -----------------------------------------------------------------
 * To use this example, the SOAP extension must be enabled.
 */
// All data is returned in UTF-8 encoding
header('Content-type: text/html; charset=utf-8');
echo '<pre>';
try {
    // Connecting to the server
    $client = new SoapClient('http://turbosms.in.ua/api/wsdl.html');
    // View a list of available server methods
    print_r($client->__getFunctions());
    // Authentication data
    $auth = [
        'login' => 'your_login',
        'password' => 'your_password'
    ];
    // Authenticating on the server
    $result = $client->Auth($auth);
    // Authentication result
    echo $result->AuthResult . PHP_EOL;
    // Getting the available credit balance
    $result = $client->GetCreditBalance();
    echo $result->GetCreditBalanceResult . PHP_EOL;
    // The message text MUST be sent in UTF-8 encoding
    $text = iconv('windows-1251', 'utf-8', 'This message will be delivered to the specified number');
    // Sending a message to one number.
    // The sender ID can contain English letters and numbers. Maximum length - 11 characters.
    // The number must be in full format, including the plus sign and country code
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXXX',
        'text' => $text
    ];
    $result = $client->SendSMS($sms);
    // Sending a message to multiple numbers.
    // Numbers are separated by commas without spaces.
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXX1,+380XXXXXXXX2,+380XXXXXXXX3',
        'text' => $text
    ];
    $result = $client->SendSMS($sms);
    // Outputting the result of sending.
    echo $result->SendSMSResult->ResultArray[0] . PHP_EOL;
    // ID of the first message
    echo $result->SendSMSResult->ResultArray[1] . PHP_EOL;
    // ID of the second message
    echo $result->SendSMSResult->ResultArray[2] . PHP_EOL;
    // Sending a message with a WAPPush link
    // The link must include http://
    $sms = [
        'sender' => 'Rassilka',
        'destination' => '+380XXXXXXXXX',
        'text' => $text,
        'wappush' => 'http://super-site.com'
    ];
    $result = $client->SendSMS($sms);
    // Requesting the status of a specific message by ID
    $sms = ['MessageId' => 'c9482a41-27d1-44f8-bd5c-d34104ca5ba9'];
    $status = $client->GetMessageStatus($sms);
    echo $status->GetMessageStatusResult . PHP_EOL;
} catch(Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
}
echo '</pre>';
?>

2. Project for .NET

Download Archive

3. Module for Yii2 Framework

View on GitHub

4. Ruby Gateway Integration

View on GitHub

5. Golang Gateway Integration

View on GitHub

Ошибка