Schedule SMS API

Description

Kaleyra's APIs allow you to schedule an SMS to be sent at a future point in time. You can schedule to send your SMS 15 minutes after the current time and within 3 months from the current date.

Prerequisites

You should have created a Sender ID in the Kaleyra.io Platform before you proceed with this API.

Base URL

"https://api.kaleyra.io/v1/"

To schedule your SMS, follow the below steps:

Schedule your SMS

1. Signup or Login to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key.

📘

Note:

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in Kaleyra.io.

2. API command to schedule your SMS

Request Format

To schedule your SMS, use the /messages endpoints.

curl --location --request POST 'https://api.kaleyra.io/v1/{sid}/messages' \
--header 'Content-Type: <CONTENT_TYPE>' \
--header 'api-key: {api_key}' \
--data-urlencode 'to=<TO_NUMBER>' \
--data-urlencode 'body=<BODY_CONTENT>' \
--data-urlencode 'sender=<SENDER_ID>' \
--data-urlencode 'type=<TYPE>' \
--data-urlencode 'time=<TIME>' \
--data-urlencode 'callback=<CALLBACK_URL>'

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

Below is the list of parameters and variables used:

Parameter

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

Yes

CONTENT_TYPE

Alphabet

The format in which the data is sent.

application/x-www-form-urlencoded

Yes

API_KEY

String

API Key generated by Kaleyra.io

Ac4XXXXX21f

Yes

TO_NUMBER

Integer

A valid number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

Example:

Note: You can add multiple recipients, separate each number using the comma (,) delimiter.

+1202XXXXXXX

Yes

BODY_CONTENT

Text

Content of the message.

Hi, your appointment with Dr Doolittle is scheduled for today at 4.00 PM"

Yes

SENDER_ID

String

Alphanumeric sender ID of the registered for the business from which the message is to be sent. This Id must be created in the Kaleyra.io platform.

KLRHXA

Yes

TYPE

String

Indicate the type of message being sent. Messages could be sent for marketing (MKT) or promotional (PMT) purposes
Example: MKT

DEFAULT or MKT or TXN

Optional

SCHEDULED_TIME

DD-MM-YY

The time at which the message will be sent to the recipient.
The time must be specified in the YYYY-MM-DDThh:mm:ss<Time_Zone>

2020-02-02T12:58:00+04:30

Yes

CALLBACK_URL

Object

The URL you want to receive the status of the message that is sent. This URL can be accessed publicly.

https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254

True

3. Response Format

This section provides you the success and failure JSON response formats of different scenarios.

Success Response

{
  "id": "0xxxxxxx-xxxx-4xxx-9xxx-2xxxxxxxxxxx",
  "sender": "KLRHXA",
  "type": "MKT",
  "body": "Hi, your appointment with Dr Doolittle is scheduled for today at 4.00 PM",
  "createdDateTime": "2020-02-11 07:03:12+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "0xxxxxxx-xxxx-4xxx-9xxx-2xxxxxxxxxxx:1",
      "recipient": "+1202XXXXXXX"
    }
  ],
  "dlrurl": null
}

Failure Responses

Invalid Time
You can schedule the SMS for 15 minutes from the current time and before three months from now.

{
  "code": "E402",
  "message": "Message can be scheduled for after 15 minutes from current time and before 3 months from now.",
  "error": {
    "time": "Message can be scheduled for after 15 minutes from current time and before 3 months from now."
  }
}

📘

Note:

In case of an error, ensure that the parameter values are correct in the above code. Refer to the Understand Error Codes page for detailed information.

Sample Request

curl --location --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: Ac4XXXXX21f' \
--data-urlencode 'to=+1202XXXXXXX' \
--data-urlencode 'body=<BODY_CONTENT>' \
--data-urlencode 'sender=KLRHXA' \
--data-urlencode 'type=DEFAULT or MKT or TXN' \
--data-urlencode 'time=07:03:12+00:00' \
--data-urlencode 'callback=https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254'

Did this page help you?