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/><SID>

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. To view the API Key and the SID, see View API Key and SID.

📘

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.

  1. 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_OBJ>'

📘

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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USYes
CONTENT_TYPEAlphabetThe format in which the data is sent.application/x-www-form-urlencodedYes
API_KEYStringAPI Key generated by Kaleyra.ioAc4XXXXX21fYes
TO_NUMBERIntegerA valid number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).

Note: You can add multiple recipients, separate each number using the comma (,) delimiter.
+1202XXXXXXXYes
BODY_CONTENTTextContent of the message.Hi, your appointment with Dr Doolittle is scheduled for today at 4.00 PM"Yes
SENDER_IDStringAlphanumeric 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.KLRHXAYes
TYPEStringIndicate the type of message being sent. Messages could be sent for marketing (MKT) or promotional (PMT) purposes
Example: MKT
DEFAULT or MKT or TXNOptional
SCHEDULED_TIMEDD-MM-YYThe 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:30Yes
CALLBACK_OBJObjectThis data allows Kaleyra to send back the statuses of the messages that you have sent. The callback URL can be accessed publicly.{
"url": "https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70

",
"method": "POST",
"header": {
"x-api-key": "qwxxxxxxxxxxxxxxxxdv",
"x-randoem-id": "23xxxxey"
},
"retry": {
"count": "3",
"interval": [
"10",
"10",
"10"
]
}
}

Note: Only url and method are mandatory attributes, others are optional.
No
  1. 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={"url":"https://webhook.site/0exxxxfd-axxc-4xx1-bxxe-cdxxxxxxxx70","method":"POST","header":{"x-api-key":"qwxxxxxxxxxxxxxxxxdv","x-randoem-id":"23xxxxey"},"retry":{"count":"3","interval":["10","10","10"]}}'