Search APIs helpdesk

Specification

PostedSeptember 30, 2019

Last Updated OnSeptember 30, 2019

Bygretor

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
}