Specification 2.0
API URL
The URL used to send the HTTP requests:
https://sms.gretor.net/api/2.0/simple/transactional
POST /api/2.0/advanced/transactional HTTP/1.1 Host: sms.gretor.net Content-Type: application/json Cache-Control: no-cache
It is strictly prohibited to exploit transactional SMS for promotional/marketing uses. It must be used for notification purposes only – as an SMS notification.
Parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| application_id | Application indentificator | Yes | – |
| application_token | Application authentication token | Yes | – |
| number | Recipient number | Yes | – |
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 enconding. It is possible to add variables to the template from the variables array (another parameter) | Yes | – |
| variables | Associative array to add variables to text. | No | [] |
| variables | Associative array to add variables to text | No | [] |
| channel | Alternative channels. Channels are listed in a cascade, if we are unable to deliver your message via highest priority channel, channels lower in the cascade list will be used. If none of them manages to deliver sms will be used instead. | No | SMS object |
| country | Provide the recipients’ numbers in an international format (with prefix, e.g. 44) or add the country code in ISO 3166-1 alpha-2 format (7820125799 + GB = 447820125799). See the country example request. If null, your set timezone will be used to fill the information |
No | null |
| schedule | Schedule the sending time and date in unix timestamp, or ISO 8601. | No | Now |
| duplicates_check | Select on to prevent sending duplicate messages to the same phone number. Messages with the same text sent to the same number will be removed if there is a time interval shorter than 5 mins. If off no duplicates will be removed. |
No | off |
SMS object parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) | Yes, if general text isn’t used. If SMS object contains text parameter as well as general text parameter, SMS text will be used instead | – |
| sender_id | Sender ID, see sender ID type | No | gSystem |
| sender_id_value | Sender value – gOwn (e.g. “420 777 777 777”), gText (e.g. “GretorSMS”), gProfile (e.g. “423”), gMobile or gPush (KEY) | No | null |
| unicode | Yes/true/1 for Unicode SMS, no/false/0 for 7bit SMS | No | false |
Sender ID type sender_id
| VALUE | DESCRIPTION |
|---|---|
gSystem |
System number |
gShort |
Short Code |
gText |
Text sender |
gMobile |
Mobile Connect |
gPush |
Mobile Connect push – Sends a notification to the Mobile Connect app |
gOwn |
Own Number (number verification required) |
gProfile |
Gretor SMS Profile ID |
<int> |
Gretor SMS Profile ID |
Viber object parameters table
| PARAMETER NAME | VALUE | MANDATORY | DEFAULT VALUE |
|---|---|---|---|
| text | Text of SMS message (max. 612 characters, or 268 characters if Unicode is used), UTF-8 encoding. It is possible to add variables to the template from the variables array (another parameter) | Yes, if general text isn’t used. If Viber object contains text parameter as well as general text parameter, Viber text will be used instead | – |
| sender_id | Sender | Yes | “” |
| expiration | Time limit after which alternative channel will be used | No | 120 |
Example of full request:
POST /api/2.0/advanced/transactional HTTP/1.1
Host: sms.gretor.net
Content-Type: application/json
Cache-Control: no-cache
{
"application_id": "****",
"application_token": "******************************",
"application_product": "http-advanced",
"number": "440111222333",
"text": "example text <first_name>",
"variables": {"first_name": "Lt. Mosley"},
"country": "gb",
"schedule": "2018-05-14T18:30:00-01:00",
"channel": {
"viber": {
"sender": "Lt. Hagan",
"expiration": 100,
"text": "example text"
},
"sms": {
"sender_id": "gText",
"sender_id_value": "Lt-Hagan",
"unicode": true,
"text": "example text"
}
}
}
Response to this command may be:
In case of success:
{
"data": {
"status": "accepted",
"sms_id": "tmpde1bcd4b1d1",
"price": 0.02,
"credit": 215.81380,
"number": "447700900000"
}
}
In case of error:
{
"type": "invalid_phone_number",
"code": 400,
"error": "Invalid phone number",
"detail": null
}
{
"type": "unknown_identity",
"code": 401,
"error": "Unknown identity / unauthorized / empty application_id",
"detail": null
}
Where:
- type and error (description of the error) can be found in the error types table,
- code represents http error
- detail is an additional info about the error
See all the error types for Simple API and Advanced API here.
