Search APIs helpdesk

Specification

You are here:

API URL

URL used to send HTTP requests:

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

POST /api/1.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
unicode Yes/true/1 for Unicode SMS, no/false/0 for 7bit SMS No false
flash Yes/true/1 for Flash SMS No false
sender_id Sender ID, see Sender ID type No gSystem
sender_id_value Sender value gOwn or gText No null
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.

Sender ID type sender_id

VALUE MEANING
gSystem System number
gShort Short Code
gText Text sender
gOwn Own number (requires number verification)
<int> Gretor SMS Profile ID

Example of full request:

POST /api/1.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"}}
    ],
    "unicode": true,
    "flash": false,
    "groups": [1, 2],
    "admins": [1, 4],
    "text": "Hello, <first_name> <last_name>",
    "sender_id": "gText",
    "sender_id_value": "GretorSms",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00"
}

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

POST /api/1.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, <first_name> <last_name>",
    "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:

{
  "error": "authentication_failed",
  "code": 401
}