Rezervē laiku sarunai ar Text2reach speciālistuRezervēt laiku

SMS sūtīšanas API dokumentācija

Izveido SMS kontu, veic apmaksu ar maksājumu karti, ģenerē API KEY un sāc lietot SMS API tulīt.

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.

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

1.2 Custom fields

NameDescription
{sms_unsubscribe_link}Unsubscribe link – This custom field will include unique link in message for each recipient where recipient can unsubscribe from future SMS. Link will take recipient to landing page where he will be asked to confirm unsubscribe process. If recipient confirms unsubscribe process recipients’ number will be added to client account Blacklist and future SMS sending’s to this numbers will be rejected until number is removed from blacklist. Number in blacklist are added recipient number + sender name which means that recipient unsubscribes only from specific sender name / brand messages.
{pin:*:6:3600}PIN / Verification code – this custom field will include unique code in message body which will be sent to recipient. Sent code can be validated over API request. More information about PIN code variables and verification process see section 8. PIN / Verification code

1.3 Parameters

NameRequiredDefault valueDescription
api_keyyesYour registered Bulk API key
fromyessource address of the message
phoneyesdestination address in international form
messageyesplain text message up to 160 (1071) characters, Unicode message up to 70 (469) characters
typenotxtmessage type (“txt” for text, “bin” for binary)
unicodenotrueif set to false, characters not in GSM 7bit alphabet will be converted (ā => a) or removed
timestampno0Unix timestamp of a time when end user opted in to receive messages. If parameter is not set the current timestamp is used.
report_urlnofalseURL for delivery reports
expiresno0Delivery time in seconds
schedulenoUnix timestamp of a time when the message is scheduled for delivery
blacklistnofalseChecks if the number is in blacklist before sending. Returns error -503 if found
shortlinkno0Set 1 if you need to curtail web-links in message by Bitly service. Links must begins with “http://”

1.4 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=05A256117C15DE668784DC8CF6863AF2&msg_id=1234567

2.2 Parameters

NameRequiredDefault valueDescription
api_keyyesyour registered Bulk API key
msg_idyesmessage ID from “bulk send” api call

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.

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 HTTP status code 200 or 201 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 Parameters

NameDescription
msg_idmessage id of the message this report belongs to, provided as a result of sending the message
statusstatus of the sent message,
delivered – the message was delivered successfully
undelivered – the message was not delivered
expired – the delivery reached time limit and was considered undelivered
canceled – the message was canceled before scheduled sendout
rejected – the message was rejected by SMSGW and was not charged
pending – the message is not jet delivered (this status is only reported using manual delivery checking)
unknown – message status is not known
retrieshow many times platform tried to deliver report to the “report_url”

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 Parameters

NameRequiredDefault valueDescription
api_keyyesyour registered Bulk API key
msg_idyesmessage ID from “bulk send” api call

4.3 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=05A256117C15DE668784DC8CF6863AF2&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 Parameters

NameRequiredDefault valueDescription
api_keyyesyour registered Bulk API key
msg_idyesmessage ID from “bulk send” api call

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=05A256117C15DE668784DC8CF6863AF2

6.2 Parameters

NameRequiredDefault valueDescription
api_keyyesyour registered Bulk API key

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=05A256117C15DE668784DC8CF6863AF2&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 Parameters

NameRequiredDefault valueDescription
api_keyyesyour registered Bulk API key

7.3 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

VariableMandatoryDescription
Typeyes* – Alpha + numeric PIN code (A1B2)
N – Only Numeric PIN code (1234)
A – Only Alpha PIN code (ABCD)
LengthyesSymbol count in numeric value
Validity periodyesValidity period in seconds

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

ParameterDescription
api_keyAPI key that was used to request pin code generation
phonePhone number to verify
pinPIN code to verify

8.6 Request example

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

8.7 Response codes

ResponseDescription
VALIDPIN code is valid and matches to the one that was sent to phone number.
UNKNOWNPIN code does not match to the one that was sent to phone number.
EXPIREDPIN code has expired

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:

ValueDescription
-10Geneal system error
-11Wrong API KEY for the request
-12Wrong Message ID
-14Wrong source address
-15Wrong destination address
-16Wrong “type”, must be “txt” or “bin”
-17Wrong message length (empty)
-18Wrong message length (too long)
-19Wrong “schedule” value
-20Wrong “expires” value
-21Phone in blacklist
-22No route destination
-34Message failed
-35Client undefined

GSM 7bit characters

CharacterUnicodeUTF-8CharacterUnicodeUTF-8CharacterUnicodeUTF-8
@004040+002B2BV005656
£00A3C2A3,002C2CW005757
$002424002D2DX005858
¥00A5C2A5.002E2EY005959
è00E8C3A8/002F2FZ005A5A
é00E9C3A90003030Ä00C4C384
ù00F9C3B91003131Ö00D6C396
ì00ECC3AC2003232Ñ00D1C391
ò00F2C3B23003333Ü00DCC39C
Ç00C7C3874003434§00A7C2A7
000A0A5003535¿00BFC2BF
Ø00D8C3986003636a006161
ø00F8C3B87003737b006262
000D0D8003838c006363
Å00C5C3859003939d006464
å00E5C3A5:003A3Ae006565
Δ0394CE94;003B3Bf006666
_005F5F<003C3Cg006767
Φ03A6CEA6=003D3Dh006868
Γ0393CE93>003E3Ei006969
Λ039BCE9B?003F3Fj006A6A
Ω03A9CEA9¡00A1C2A1k006B6B
Π03A0CEA0A004141l006C6C
Ψ03A8CEA8B004242m006D6D
Σ03A3CEA3C004343n006E6E
Θ0398CE98D004444o006F6F
Ξ039ECE9EE004545p007070
 00A0C2A0F004646q007171
Æ00C6C386G004747r007272
æ00E6C3A6H004848s007373
ß00DFC39FI004949t007474
É00C9C389J004A4Au007575
002020K004B4Bv007676
!002121L004C4Cw007777
002222M004D4Dx007878
#002323N004E4Ey007979
¤00A4C2A4O004F4Fz007A7A
%002525P005050ä00E4C3A4
&002626Q005151ö00F6C3B6
002727R005252ñ00F1C3B1
(002828S005353ü00FCC3BC
)002929T005454à00E0C3A0
*002A2AU005555   
1000C0C1005C5C1007C7C
1005E5E1005B5B€ 120ACE282AC
1007B7B1007E7E   
1007D7D1005D5D   
  1 – GSM 7bit single part message may contain up to 160 7bit septets. Marked characters use two septets in the message.