SMS messaging API documentation

Bulk SMS

Text2reach API has simple HTTP GET request interface and also JSON-RPC interface. To use JSON-RPC interface, please read the JSON-RPC Specification.

API rate limits

To ensure fair usage and system stability, we enforce rate limits on all API requests.
Requests Allowed: 300 per 10 seconds (per client).
Exceeding these limits will result in a 429 Too Many Requests HTTP error response.
If your application receives a 429 error, you must stop sending requests immediately and wait until the limit resets.
The response will include a standard HTTP header to indicate the required wait time: Retry-After. The time, in seconds, the client should wait before making a new request.
Best Practice: Implement logic in your application that reads the Retry-After header and dynamically pauses subsequent requests for the specified duration.

1. Send SMS

1.1 HTTP interface

To send a bulk message, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/send query string values are specified below in the parameters table. All parameters should be properly url-encoded. The returned HTML body for the request will be a message ID or an error code in plain text format (or a detailed JSON object if requested).

Example: https://api.text2reach.com/sms/send?api_key=XXXXXXXXXXXXX &phone=37126378162&from=29180083&message=Hello+world

1.2 JSON-RPC interface

To send a bulk message, SP must make a JSON-RPC request to address: https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXXXX

Method:

send( from, phone, message, type, unicode, timestamp, report_url, expires, schedule, blacklist )

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $msg_id = $j->send(
            'aaaaaaaaaa',
            '37125924564',
            'Hello world!',
            'txt',
            false,
            0,
            'http://www.yoursite.com/sms/report/handler/',
            0,
            0,
            false
    );
    // save the $msg_id in DB and use it for report requests
?>
                            

1.3 Custom fields

1.4 Parameters

1.5 Description

This bulk API call will send the text message to the provided phone number. Your account will be checked for the required funds. If the message cannot be sent, the response will be a negative integer representing the error.

The message will be considered as plain if all the characters are present in the GSM 7bit alphabet (see the table below). It is possible to send up to 1071 characters which will be split into seven parts, 153 characters per part. You will be charged for each part accordingly. 7 characters out of 160 are reserved to identify and concatenate multiple parts and applies only to messages having more than one part. If the message contains unicode characters then you can send up to 469 characters, 63 characters per part, max 7 parts. 7 characters out of 63 are reserved to identify and concatenate multiple parts and applies only to messages having more than one part.

The mandatory parameter “from” can be a telephone number in international format, a short code or a textual sender name. Maximum length of an international number is 15 digits not including “+” or “00” prefix. Maximum length of a textual sender name is 11 alphanumeric characters.

The optional parameter “type” specifies the format of the parameter “message”. In case the type is set to “bin”, parameter “message” should be in hexadecimal format.

The optional parameter “unicode” specifies the encoding used for parameter “message”. If it is set to “false”, then the message will be checked against GSM 7bit alphabet (see the table below) and all the symbols not in the table will be converted to the respective latin characters or completely removed. If the parameter “unicode” is set to “true” and the message contains characters not in the GSM 7bit alphabet, then the message will be considered as utf-8 and reduce the length of the message to 70 (469) characters.

The optional parameter “timestamp” specifies the time when the user opted in to receive the message. If an end user has signed up for your service and has provided a mobile phone number to receive advertisements or informational messages, then you should provide “timestamp” parameter with the sign-up time. If an owner of a mobile phone number is changed, number is closed or operator is changed, then the message will not be sent. If the new owner of a number opts in to receive messages, a new timestamp should be used.

The “report_url” parameter should be used to receive delivery reports for sent messages. Please see below for detailed request specification.

If the “expire” parameter is not specified, the operator default expire time is used. If specified and the message is not delivered in the specified amount of seconds, you will received “expired” status. Exact behavior depends on the end user mobile phone operator validity period of the message and is not guaranteed to match the expire time specified in the parameter.

The “schedule” parameter should be set if you want to delay the delivery of the message. The parameter must be in two weeks range from the current time.

2. Manual delivery reports

You can request a status of the sent message by an api call.

2.1 HTTP interface

To request a status, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/status query string values are specified below in the parameters table. The returned HTTP body will contain a status of the message.

Example:
https://api.text2reach.com/sms/status?api_key=XXXXXXXXXXXX&msg_id=1234567

2.2 JSON-RPC interface

To request a status, SP must make a JSON-RPC request to address: https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXX

Method:

status( msg_id )

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $status = $j->status(1234567);

    // save the status in DB for the msg_id=1234567
?>
                            

2.3 Parameters

3. Automatic delivery reports

Alternatively reports will be delivered to the “report_url” if it is provided in the send bulk api call. Delivery interface will be the same as used in the sending, e.g., if you used json-rpc interface to send a message, then the delivery report will be sent through json-rpc interface, too.

3.1 HTTP interface

SMSGW makes a HTTP GET request to a “report_url” address provided by SP with the parameters found below. The SP handler script must respond with text “OK” or else the report will be retried for a total of 10 times with 2n minutes interval (n – retries counter) and then discarded.

3.2  JSON-RPC interface

To handle report requests through JSON-RPC interface, you must have the minimum implementation as provided below:

<?php
    require_once 'jsonRPCServer.php';

    class handler {
            public function report($msg_id, $status, $retries) {
                    // handle the report
                    return true;
            }
    }

    $server = new handler();
    jsonRPCServer::handle($server) or die('Invalid request');
?>
                            

3.3 Parameters

4. Extended delivery report

You can request a details of the sent message by an api call.

4.1 HTTP interface

To request a details, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/details query string values are specified below in the parameters table. The returned HTTP body will contain a status of the message.

4.2 JSON-RPC interface

To request a detailed status, SP must make a JSON-RPC request to address:https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXX

Method:

details( msg_id )

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $status = $j->status(1234567);

    // save the status in DB for the msg_id=1234567
?>
                                

4.3 Parameters

4.4 Returns

Error:

{
    "success" : 0,
    "message" : "Unknown msg_id",
    "data" : []
}

Successfull:

{
    "success" : 1,
    "message" : "ok",
    "data" : {
        "msg_id" : "1234567",
        "source" : "info",  // from number/alpha
        "destination" : "37129123456", // to number
        "country" : {
            "name" : "Latvia",
            "iso" : "lv",
            "mcc" : "247"
        },
        "operator" : {
            "name":"Best Mobile Operator",
            "mnc":"10"
        },
        "created" : "2017-01-01 10:00:00",
        "delivered" : "2017-01-01 10:00:03",
        "schedule" : "N",
        "scheduled" : null,
        "message" : "Hello World!",
        "multipart" : "N",
        "parts" : 1,
        "price: : 0.0232,
        "sum" : 0.0232,
        "status" : "delivered" // statuses: delivered | undelivered | expired | canceled | rejected | pending
    }
}

5. Cancel SMS

You can cancel pending/scheduled message by an api call.

5.1 HTTP interface

Example:
https://api.text2reach.com/sms/cancel?api_key=XXXXXXXXXXXX&msg_id=1234567

To cancel message sending, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/cancel query string values are specified below in the parameters table. The returned HTTP body will contain a status of the message.

5.2 JSON-RPC interface

To cancel message sending, SP must make a JSON-RPC request to address:https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXX

Method:

cancel( msg_id )

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $result = $j->cancel(1234567);

    // result = ok | forbidden | error | unknown
?>
                                

5.3 Parameters

6. Credits balance

Prepaid customers can request remains of credits on account.

6.1 HTTP interface

To request a balance, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/credit The returned HTTP body will contain a amount of credits.

Example:
https://api.text2reach.com/sms/credit?api_key=XXXXXXXXXXXX

6.2 JSON-RPC interface

To request a status, SP must make a JSON-RPC request to address:https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXX

Method:

credit()

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $prices = $j->credit();
?>

6.3 Parameters

7. Prices

7.1 HTTP interface

To get all available prices by countries, SP must make a HTTP GET request to address: https://api.text2reach.com/sms/prices query string values are specified below in the parameters table. The returned HTTP body will contain an json structure.

Example:
https://api.text2reach.com/sms/prices?api_key=XXXXXXXXXXXX&format=json

Are available follows formats (only HTTP interface):
json – Price in JSON format. This is default format.
csv – prices in csv-file with comma delimeter
xls – prices in Excel format file

7.2 JSON-RPC interface

To get all available prices by countries, SP must make a JSON-RPC request to address:https://api.text2reach.com/sms/?api_key=XXXXXXXXXXXX

Method:

prices()

Example:

<?php
    require_once 'jsonRPCClient.php';
    define("API_KEY", "XXXXXXXXXXXX");

    $j = new jsonRPCClient("https://api.text2reach.com/sms/?api_key=" . API_KEY);
    $prices = $j->prices();
?>
                                

7.3 Parameters

7.4 Returns

Example:

[
    ...
    {
        country : "Belgium",
        iso     : "be",
        code    : 32,
        operator: "Proximus",
        mcc	    : 206,
        mnc     : 1,
        type    : "all",
        price   : 0.123456,
        note    : null
    },
    ...
]

8. PIN / Verification code

Text2Reach API provides functionality to generate PIN code using custom fields in message body. To generate unique PIN code, you need to include custom field in any place of message body when sending SMS.

8.1 Custom field template

{PIN:<TYPE>:<length>:<validity_period>}

8.2 Custom field variables

8.3 Custom field example

To send PIN code that consists of Alpha and Numeric values, is 8 characters long and is valid for one hour you need to insert following custom fields in any place in message body

{PIN:*:8:3600}

8.4 Custom API endpoint

https://api.text2reach.com/sms/pin

8.5 Request parameters

8.6 Request example

https://api.text2reach.com/sms/pin?api_key=XXXXXXXXXXXX&phone=3712123123&pin=A1B2

8.7 Response codes

Error codes

If the message cannot be sent, the return value for msg_id will contain a negative integer which represents an error from the table below:

GSM 7bit characters

Extended GSM 7bit characters ¹

¹ – These additional characters, known as the Extended GSM character set, require two standard GSM characters for each extended GSM character because they use the escape character prefix.