Connection to the SMS-gateway, API

Navigation

You can connect to our SMS-gateway free of charge, no prior activation is needed. SMS-gateway allows to launch automatic SMS delivery and integrate SMS mailing with any project.

JSON API (recommended method)

Communication with the service is carried out by sending HTTP requests to the specified requests to the specified an address using the textual JSON data exchange format.

To authenticate the request, use "OAuth 2", with this type of authentication you need to use token, which can get in your account in the section "Profile". After that, respectively, turn on the given token in the request header, such as : 'Authorization: Bearer your_token'.

Attention!

Limiting the frequency of requests to the service should be no more than 9 requests in second from one client.

Sending messages

Service address:

https://im.smsclub.mobi/sms/send

Messages are sent by specifying the following parameters.

src_addr – Sender from which to send;
phone – An array of numbers, you can send up to 100 numbers for request;
message – Message text;
integration_id – Not required field. Fill when using the referral system;

After successful sending of the message to the partner’s system, an array will be returned, “info” in which the key is the id message in our system, by which you can get status later, and the value will be the phone number to which the message was sent. In the example below, “106 ”is id sms, 380989361131 is the recipient's number.

An example in JSON format::

{
 "success_request": {
    "info": {
        "106": "380989361131"
    }
 }
}

Getting the status of messages

Service address:

https://im.smsclub.mobi/sms/status

To receive message statuses, you need to pass a single parameter:

id_sms – Array of ID messages for which you want to get the status, the limit is not more than 100;

Example in "JSON" format:

{
    "id_sms": ["106"]
}

After a successful request, the system will return an “info” array, in which the key will be the message id, and its status will be the value.

{
 "success_request": {
    "info": {
        "106": "ENROUTE"
        }
    }
}

Statuses:

200 – Request successfully processed.

Possible message statuses:

ENROUTE – message sent;
DELIVRD – message delivered;
EXPIRED – life expired, message not delivered;
UNDELIV – unable to deliver message;
REJECTD – the message was rejected by the system (blacklist or other filters).

400 – Input parameter validation error.
401 – User authentication error.
429 – Too many requests per time unit. By requests for a given default, it is necessary to perform requests to the services of the service no more than 9 requests in 1 second.
500х – Service is temporarily unavailable.

Get a list of alpha usernames

Service address:

https://im.smsclub.mobi/sms/originator

To get a list of available alpha names, you need to make a request to the above URL without the body of the request using only authorized information user.

After a successful request, the system will return a list of active alpha names:

Sample answer:

{
 "success_request": {
    "info": [
        "test1",
        "test2"
        ]
    }
}

Getting user balance

Service Address:

https://im.smsclub.mobi/sms/balance

To get a balance, you need to make a request to the above URL without the body of the request using only authorized user information.

After a successful request, the system will return the user's balance, the array “info” where:

money - balance
currency - account currency

Sample answer:

{
 "success_request": {
    "info": {
        "money": "8111.1700",
        "currency": "UAH"
        }
    }
}

SMPP-gateway

The gateway corresponds to all standards of SMPP v3.4. protocol. If you want to test the gateway, please contact our managers.

HTTP-gateway

The connection with service is achieved through sending HTTP-query to an indicated service address via HTTP protocol (GET/POST methods). Content check and encoding validity are not available.

Each query may consist of the delivered messages and/or status requests.

Sending SMS messages

Service address:

https://gate.smsclub.mobi/token/

You can send messages by setting the parameters below (they are the same for SMPP and HTTP):

username – login of your user account;
token – token of your user account (you can find it in profile);
from – A-name, identifying the sender's id (11 Latin characters, numbers, space);
to – a list of recipients, separated with «;» (this symbol is not used after the last recipient);
text – a message written in Windows-1251 encoding, it is decoded into Base64 before being sent;
lifetime – setting a SMS life expectancy (in min).

Limitations:

for printed symbols (ASCII 0x01-0x7E) total length should not exceed 1071 characters;
the maximum length for symbols beyond that range is 469 characters.

Reports

For a received query the service returns either an error-report in Russian language or a text of similar type:

=IDS START=
000002
000003
=IDS END=

=IDS START=, =IDS END= - there will be a list of messages' IDs between these two codes, each ID in a new line (separated by the tag <br/>).

The list order corresponds to the order of recipients. If the message consists of several parts, the ID list would show SMS-parts that are sent consecutively to one recipient, then ID list of SMS-parts for the next recipient etc.

Query for SMS status

GET, POST methods: https://gate.smsclub.mobi/b/state.php

SMS statuses contain information about current delivery situation. They are updated regularly, and the query for SMS status can be sent any time. You can send query by setting the parameters below (they are the same for both methods):

username – login of your user account;
token – token of your user account;
smscid – a list of IDs, separated with «;» (this symbol is not used after the last ID).

For a received query the service returns either an error-report in Russian language or a text of similar type:

=IDS START=
ID_1: STATE
ID_2: STATE
…
ID_N: STATE
=IDS END=

=IDS START=, =IDS END= - there will be a list of messages' IDs and corresponding statuses (after a symbol ":") between these two codes, each ID in a new line (separated by the tag <br/>).

Codes of SMS statuses

The following codes are used to inform about SMS statuses:

ENROUTE – message accepted;
DELIVRD – message delivered;
FAILED – unable to deliver a message;
EXPIRED – the storage time of a message has expired;
UNDELIV – undeliverable message (the phone number might be turned off, connection failure or the number is added to a black list);
NOREPORT – delivery report is pending;
REJECTD - отклонено.

Examples of Get-query about SMS sending:

https://gate.smsclub.mobi/token/?username=user&token=user_token&from=SMS CLUB&to=380675126767&text=Hello from SMS CLUB

Examples of Get-query about SMS delivery:

https://gate.smsclub.mobi/token/state.php?username=user&token=user_token&smscid=000000

Online check of balance account

This method allows you to check current balance account and customer credit limit.

Examples of Get-request about balance account.

https://gate.smsclub.mobi/token/getbalance.php?username=user&token=user_token

Example of code for a balance account check:

<?php
    $ch = curl_init();
    $login = '380501234567';
    $token = '123456';
    $url = "https://gate.smsclub.mobi/token/getbalance.php?username=$login&token=$token";
    //or via POST
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL,$url);
    $result = curl_exec($ch);
    echo $result;
?>

XML-gateway

The connection with service is achieved through sending XML-query in UTF-8 encoding to an indicated service address via HTTP protocol (POST method). Content check and encoding validity are not available.

Each query may consist of the delivered messages and/or status requests.

SMS mailing (single and bulk)

Service address:
https://gate.smsclub.mobi/xml/

SMS mailing is provided using the XML-structure below. All data in tags is framed with the following tag: <![CDATA[]]>:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380501111111;380502222222]]></to>
      <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
</request_sendsms>

username – login of your user account;
password – password of your user account;
from – A-name, identifying the sender's id (11 Latin characters, numbers, space);
to – a list of recipients, separated with «;» (this symbol is not used after the last recipient);
text – a message written in UTF-8 encoding.

Limitations:

for printed symbols (ASCII 0x01-0x7E) total length should not exceed 1071 characters;
the maximum length for symbols beyond that range is 469 characters;
if you send a XML structure to the server of www.gate.smsclub.mobi, then it must contain no spaces or enter signs!!!

For a received query the service returns a XML-structure of similar type:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>

status – OK (successful operation) / ERROR (an error has occured);
text – text message about the result of the operation;
You will see No. of SMS and parts if a status is OK.
You will see the explanation in case of an ERROR status (Example: "login/password do not match").
ids – contains IDs of messages, assigned by SMSC;
The list order corresponds to the order of recipients. If the message consists of several parts, the ID list would show consecutively sent SMS-parts to one recipient, then ID list of SMS-parts for the next recipient etc.
mess – contains IDs of messages/parts of messages.

Sending personalized massages (single and bulk)

Service address:
https://gate.smsclub.mobi/xml/individual.php

Personalized mailout means sending SMS messages with an individual text for each recipient. Personalized SMS mailing is provided using the XML-structure below. All data in tags is framed with the following tag . Each separate SMS is a sequence of data in tags <to> and <text>:

SMS mailing is provided using the XML-structure below. All data in tags is framed with the following tag:

<?xml version='1.0' encoding='utf-8'?>
<request_sendsms>
      <username><![CDATA[username]]></username>
      <password><![CDATA[password]]></password>
      <from><![CDATA[XML]]></from>
      <to><![CDATA[380675126767]]></to>
      <text><![CDATA[Пример русского текста ЮТФ-8]]></text>
      ...
      <to><![CDATA[380997777662]]></to>
      <text><![CDATA[Example of text in UTF-8]]></text>
</request_sendsms>

username – login of your user account;
password – password of your user account;
from – A-name, identifying the sender's id (11 Latin characters, numbers, space);
to – recipient's phone number;
text – a message tag written in UTF-8 encoding.

Limitations:

for printed symbols (ASCII 0x01-0x7E) total length should not exceed 1071 characters;
the maximum length for symbols beyond that range is 469 characters;
if you send a XML-structure to the server of www.gate.smsclub.mobi, then it must contain no spaces or enter signs!!!

For a received query the service returns a XML-structure of similar type:

<?xml version="1.0" encoding="utf-8"?>
<response>
       <status>STATUS</status>
       <text>RESULT_TEXT</text>
       <ids>
       <mess>ID_1</mess>
       <mess>ID_2</mess>
         …
       <mess>ID_N</mess>
       </ids>
</response>

status – OK (successful operation) / ERROR (an error has occurred);
text – text message about the result of the operation;
You will see No. of SMS and parts if a status is OK.
You will see the explanation in case of an ERROR status (Example: "login/password do not match").
ids – contains IDs of messages, assigned by SMSC;
The list order corresponds to the order of recipients. If the message consists of several parts, the ID list would show consecutively sent SMS-parts to one recipient, then ID list of SMS-parts for the next recipient etc.
mess – contains IDs of messages/parts of messages.

Query for SMS statuses

Service address:
https://gate.smsclub.mobi/xml/state.php

SMS statuses contain information about current delivery situation. They are updated regularly, and the query for SMS status can be sent any time. The status query is provided using the XML-structure below. All data in tags is framed with the following tag :

<?xml version="1.0" encoding="utf-8"?>
<request_getstate>
            <username><![CDATA[user]]></username>
            <password><![CDATA[pass]]></password>
            <smscid><![CDATA[000000;000001;000002;000003]]></smscid>
</request_getstate>

username – login of user account;
password – password of user account;
smscid – a list of IDs, separated with «;» (this symbol is not used after the last ID).

The service sends back a XML-structure containing statuses of the requested messages or error codes of similar type:

    <?xml version="1.0" encoding="utf-8"?>
        <response>
        <status>OK</status>
        <text></text>
        <entries>
                 <entry>
                         <smscid>ID_1</smscid>
                         <state>STATE</state>
                 </entry>
                 <entry>
                         <smscid>ID_2</smscid>
                         <state>STATE</state>
                 </entry>
                 …
                <entry>
                        <smscid>ID_N</smscid>
                        <state>неверно указан id</state>
                </entry>
         </entries>
</response>

status – OK (successful operation) / ERROR (an error has occured);
text – text message about the result of the operation;
You will see No. of SMS and parts if a status is OK.
You will see the explanation in case of an ERROR status (Example: "login/password do not match").
entries – contains IDs of messages, assigned by SMSC, and their corresponding statuses;
Might be absent in case of an error.
entry – contains ID of a single messages and its status.
smscid – a list of IDs, separated with «;» (this symbol is not used after the last ID).
state – corresponding status.

Codes for SMS statuses.

The following codes are used to inform about SMS statuses:

ENROUTE – message delivered;
DELIVRD – unable to deliver a message;
EXPIRED – the storage time of a message has expired;
UNDELIV – undeliverable message (the phone number might be turned off, connection failure or the number is added to a black list);
NOREPORT - delivery report is pending;
REJECTD - a message has been rejected by mobile provider.

An example of XML-query code.

This code has been tested so we guarantee positive result. There is no information about using other codes.

PHP-version:

    <?php
      $xml = "
      <?xml version='1.0' encoding='utf-8'?>
      <request_sendsms>
            <username><![CDATA[username]]></username>
            <password><![CDATA[password]]></password>
            <from><![CDATA[XML]]></from>
            <to><![CDATA[380675126767]]></to>
            <text><![CDATA[Пример русского ЮТФ-8 текста]]></text>
      </request_sendsms>";
      $ch = curl_init();
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, array("xmlrequest" => $xml));
      curl_setopt($ch, CURLOPT_URL, 'https://gate.smsclub.mobi/xml/');
      $result = curl_exec($ch);
      echo $result;
    ?>

Download scripts

Here you can download examples of scripts for a particular gateway

Method	HTTP	XML
Single
Bulk
Individual
Balance account
Reports

Navigation

Sending messages

Getting the status of messages

Get a list of alpha usernames

Getting user balance

SMPP-gateway

HTTP-gateway

Sending SMS messages

Reports

Query for SMS status

Codes of SMS statuses

Online check of balance account

XML-gateway

SMS mailing (single and bulk)

Sending personalized massages (single and bulk)

Query for SMS statuses

Codes for SMS statuses.

An example of XML-query code.

Download scripts

Clients login