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
- 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.
- 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:
| 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). 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_OBJ | Object | This 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 |
- 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"]}}'
Updated about 1 year ago