Specification 2.0

Search APIs helpdesk

Specification 2.0

You are here:

API URL

URL used to send HTTP requests:

https://sms.gretor.net/api/2.0/advanced/promotional

POST /api/2.0/advanced/promotional HTTP/1.1
Host: sms.gretor.net
Content-Type: application/json
Cache-Control: no-cache

Parameters table

PARAMETER NAME VALUE MANDATORY DEFAULT VALUE
application_id Application ID Yes
application_token Application token Yes
number Array of recipients – Value number Yes or admins or groups
groups Array of numbers of groups in Gretor SMS address book. More info Yes or number or admins
admins Array of numbers of Gretor SMS administrators receiving notifications. More info Yes nebo number nebo groups
text Text of the SMS message (max. 612 characters, or 268 characters, if Unicode is activated), UTF-8 encoding Yes, if number is given by the array of numbers or the parameter groups or admin is used
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 recipient numbers in international format (with prefixem, for e.g 44), or add country code (7820125799 + GB = 447820125799). See the example of a country requirement. If the value is null, your set time zone will be used to fill in the information No null
schedule Schedule the sending time and date in unix timestamp, or ISO 8601. See examples below No Now
duplicates_check Select same_text to prevent sending duplicate messages to the same phone number. Disable the possibility to send a message with either the same or different text to the same number with same_number. If null no duplicates will be removed. No null

Value number

The value number can be written in two ways:

  • Array of phone numbers
[
    "447820125799",
    "447820100234", 
    "42060612345"
]
  •  Associative array with diagram number,text, and variables', where the only required parameter is number. Ifnumber` is not filled in, the message skips.
[
    {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
    {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
    {"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
]

You can add variables from the array variables into the template of parameter text.

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 MEANING
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. 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 Sender Yes “”
expiration Time limit after which alternative channel will be used No 120
button Mandatory structure that creates a button in the message Yes Button object

Button object parameters table

PARAMETER NAME VALUE MANDATORY DEFAULT VALUE
caption Button text Yes OK
url URL address Yes #

Example of full request:

POST /api/2.0/advanced/promotional HTTP/1.1
Host: sms.gretor.net
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": [
        {"number": "447820125799", "text": "test1 <a>", "variables": {"a": 5}},
        {"number": "447820100234", "text": "test2 <a>", "variables": {"b": 5}},
        {"number": "42060612345", "text": "test3 <b> <d>", "variables": {"c": 3, "d": "abc"}}
    ],
    "groups": [1, 2],
    "admins": [1, 4],
    "text": "Hello, <first_name> <last_name>",
    "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"
        }
        }
}

Example of a request to enter recipients by the array of numbers and to schedule the time in the unix timestamp:

POST /api/2.0/advanced/promotional HTTP/1.1
Host: sms.gretor.net
Content-Type: application/json
Cache-Control: no-cache

{
    "application_id": "APPLICATION_ID",
    "application_token": "APPLICATION_TOKEN",   
    "number": [
        "447820125799",
        "447820100234", 
        "42060612345"
    ],
    "text": "Hello,  ",
    "schedule": "1526992636"
}

Response to this command may be:

In case of success:

{
  "data": {
    "total": {
      "price": 0.0522,
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "tmpde1f00539c7",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820125799"
      },
      {
        "status": "scheduled",
        "sms_id": "tmpde1f0053f0c",
        "price": 0.0261,
        "credit": 215.81380,
        "number": "447820100234"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "42060612345"
      }
    ]
  }
}

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.

Go to Top