API

This section is the technical documentation for integrating our SMS sending service with your application / website To obtain the necessary token to use the API you need to create an account.

Sending SMS

To send or schedule an SMS you have to do a request via method POST to address: https://www.smsadvert.io/api/sms/ type application/json

Example of sending SMS using your own devices

Delivery of the SMS is done immediately after your request.

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "This is the content of the SMS message"
}

Example of SMS sending using your own devices with failover

If you do not have any of your own connected devices or the GSM operator responds with an error message, the SMS will be sent via smsadvert.io network

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "This is the content of the SMS message",
  "failover": "short"
}

Example of sending SMS via smsadvert.io network

Delivery of the SMS is done immediately after your request.

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "This is the content of the SMS message",
  "sendAsShort": true
}

Example of sending schedules SMS

Delivery of the SMS is done according to the parameters startDate and endDate.

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "This is the content of the SMS message",
  "startDate": 1486883578036,
  "endDate": 1486889778036
}

Example SMS sending with multiple recipients

Delivery of the SMS to the recipients is done one by one, immediately after your request.

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456,+40740123457,+40740123458",
  "shortTextMessage": "This is the content of the SMS message"
}

Example of sending SMS with delivery report callback

Delivery of the SMS is done immediately after your request. You will then receive a request to the address from the parameter callback with delivery report.

POST https://www.smsadvert.io/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "This is the content of the SMS message",
  "callback": "http://youraddress.com/callback-url/"
}

Description of parameters

  • phone

    string, mandatory
  • It represents the recipient's phone number.
    The number must be in the international format E.164 (Ex: +40740123456)

    For multiple recipients, you can enter your phone numbers separated by commas, ex. "+40740123456,+40740123457".
    Up to 1000 phone numbers, and the numbers that are duplicates will not be recorded for submission.
    Warning! Comma is not accepted at the end of the list.
  • shortTextMessage

    string, mandatory
  • It represents the content of the SMS message and must consist of a minimum of 3 and a maximum of 480 characters.
  • sendAsShort

    boolean, optional
  • To send SMS via smsadvert.io network this parameter must contain the value true. In the case where this parameter has value false or it is not present, the message will be sent through your devices.
  • startDate

    integer, optional
  • It represents the date / hour / minute / second after which the sending of the message will start. The format is UNIX time (miliseconds).
  • endDate

    integer, optional
  • It represents the date / hour / minute / second after which the sending of the message will stop. The format is UNIX time (miliseconds).
  • failover

    string, optional
  • It represents the secondary sending channel.
    If the message can not be delivered through your devices (there is not at least one connected device or GSM operator responds with an error message) the sending will be attempted via the secondary channel.

    If the parameter failover is set as "short" then the SMS will be sent via smsadvert.io network.
  • callback

    string, optional
  • Represents the web address (URL) where you will receive a request containing the delivery status of the message.

    The request will be of type POST (application/json) and will contain two parameters: status with value "delivered" or "failed" and msgId representing the id of the message that you received it as a response from the sending request.

    Example of request that you receive to your callback URL

    POST http://youraddress.com/callback-url/ HTTP/1.1
    Content-Type: application/json
    {
      "status": "delivered",
      "msgId": "xxxxxx"
    }

Response

The response received by the request is of type application/json.

Example of successful response

{
  "successMessage": "Your message has been successfully submitted!",
  "msgId": "xxxxxx"
}

Examples of error response

{
  "errors": {
    "phone": "Invalid phone number!",
    "shortTextMessage": "Enter minimum 3 characters!"
  }
}
{
  "errorMessage": "There was a database error!"
}