Schedule SMS and Validity period

Schedule SMS sending and set a validity period for your messages.

Apart from sending messages in real-time, our API enables you to take control over the message delivery schedule, message status and the message expiration time window.

Message scheduling:

Message status:

Validity period:

Schedule SMS message 

https://api.infobip.com/sms/1/text/advanced

If you want to schedule your SMS to be sent later you can use the sendAt parameter in the Fully-featured textual message API method. This will set a specific date and time when the message will be sent.

Date and time format for SMS scheduling: 2015-07-07T17:00:00.000+01:00.

Rescheduling requirements

Please note that in order to use the advantage of message rescheduling, certain requirements must be met. See the Message rescheduling section for details.

The example bellow shows how to schedule your message:

  • JSON
POST /sms/1/text/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
   "messages":[
      {
         "from":"41793026700",
         "destinations":[
            {
               "to":"41793026785"
            }
         ],
         "text":"A long time ago, in a galaxy far, far away... It is a period of civil war. Rebel spaceships, striking from a hidden base, have won their first victory against the evil Galactic Empire.",
         "sendAt":"2015-07-07T17:00:00.000+01:00"
      }
   ]
}

And here is the response you will receive:

  • JSON
HTTP/1.1 200 OK
Content-Type: application/json

{
  "bulkId": "b86c5f0f-40ed-47b7-9b7f-57eb9707b104",
  "messages": [
    {
      "to": "41793026785",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "PENDING_ACCEPTED",
        "description": "Pending Accepted"
      },
      "messageId": "36397015-149a-41de-bccc-f7e365a7f89a"
    }
  ]
}

Get message schedule info 

http://api.infobip.com/sms/1/bulks?bulkId={bulkId}

This method will return information about the scheduled time for a unique bulk message. Canceling and rescheduling is supported only when the advanced SMS request contains only one message and the message bulkId is unique.

Request example:

  • JSON
GET /sms/1/bulks?bulkId=a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

Response:

  • JSON
{
  "bulkId": "a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc",
  "sendAt": "2021-08-25T16:00:00.000+0000"
}

Reschedule SMS message 

http://api.infobip.com/sms/1/bulks?bulkId={bulkId}

Messages scheduled with the sendAt parameter can be paused, resumed or canceled by changing the message status, or rescheduled using the bulkId parameter as an identifier.

Rescheduling and status update requirements

Please note that canceling and rescheduling is supported only when the advanced SMS request contains only one message per bulk and the message bulkId is unique.

If you don’t provide the bulkId through the initial SMS send request, the system will create a unique id for you and include it as bulkId in response. This ID can be used later to retrieve delivery information, change status and date/time of message delivery.

Multiple messages in one bulk send request CAN NOT BE UPDATED since each message may contain a different delivery date and time and have a different status.

Request example:

  • JSON
PUT /sms/1/bulks?bulkId=a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
    "sendAt": "2021-08-25T16:00:00.000+0000"
}

Response:

  • JSON
{
  "bulkId": "a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc",
  "sendAt": "2021-08-26T16:00:00.000+0000"
}

Get message status info 

http://api.infobip.com/sms/1/bulks/status?bulkId={bulkId}

This method will return the current status of the bulk message.

Request example:

  • JSON
GET /sms/1/bulks/status?bulkId=a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

Response:

  • JSON
{
  "bulkId": "a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc",
  "status": "CANCELED"
}

Below is a list of possible message statuses. Only PENDING and PAUSED status can be updated.

Status Can be updated to
PENDING PAUSED,  CANCELED
PAUSED PENDING, CANCELED
CANCELED n/a
PROCESSING n/a
FINISHED n/a
FAILED n/a

Update message status 

http://api.infobip.com/sms/1/bulks/status?bulkId={bulkId}

Messages scheduled with the sendAt parameter can be paused, resumed or canceled by changing the message status, or rescheduled using the bulkId parameter as an identifier. The following statuses can be updated:

Status Can be updated to
PENDING PAUSED,  CANCELED
PAUSED PENDING, CANCELED

Rescheduling and status update requirements

Please note that canceling and rescheduling is supported only when the advanced SMS request contains only one message per bulk and the message bulkId is unique.

If you don’t provide the bulkId through the initial SMS send request, the system will create a unique id for you and include it as bulkId in response. This ID can be used later to retrieve delivery information, change status and date/time of message delivery.

Multiple messages in one bulk send request CAN NOT BE UPDATED since each message may contain a different delivery date and time and have a different status.

Status update

PENDING and PAUSED statuses can be changed back and forth until the message starts to process (scheduled time is up and message is sent).

Once a message is CANCELED it cannot be rescheduled or updated with a new status! The message will remain undelivered regardless of the scheduled date and time.

Request example:

  • JSON
PUT /sms/1/bulks/status?bulkId=a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
    "status": "PAUSED"
}

Response:

  • JSON
{
  "bulkId": "a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc",
  "status": "PAUSED"
}

Set validity period 

https://api.infobip.com/sms/1/text/advanced

Besides scheduling messages, you can also set the validity period for every SMS sent over Fully featured textual message API method.

The message validityPeriod parameter should be set in minutes. The message sending will not be allowed after the set period expires. The maximum validity period is 48 hours and if you put a longer period, we will automatically set it to 48h.

Request example:

  • JSON
POST /sms/1/text/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
   "messages":[
      {
         "from":"InfoSMS",
         "destinations":[
            {
               "to":"41793026727"
            },
            {
               "to":"41793026731"
            }
         ],
         "text":"The time-traveling is just too dangerous. Better that I devote myself to study the other great mystery of the universe: women!",
         "validityPeriod": 1440
      }
   ]
}

Response:

  • JSON
HTTP/1.1 200 OK
Content-Type: application/json

{
  "bulkId": "a6e6bf50-ade1-4dd5-8900-d5b3bb18c0cc",
  "messages": [
    {
      "to": "41793026727",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ENROUTE",
        "description": "Message sent to next instance"
      },
      "messageId": "239a1bed-91d0-4454-a437-6663938465aa"
    },
    {
      "to": "41793026731",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ENROUTE",
        "description": "Message sent to next instance"
      },
      "messageId": "77a6e601-c12d-4a66-8e16-d8ec8c5fbc03"
    }
  ]
}
Prev: Custom Bulk ID and Message ID Next: Delivery reports on Notify URL