Send a Text Message through WhatsApp
POST and GET Method
Kaleyra's WhatsApp Business allows you to exchange WhatsApp messages with your customers. The messages could be for alerts, notifications, customer support related information, or two-factor authentication.
WhatsApp has mandated companies must start any conversation with template message, before you can start sending a text message. The recipient is given a 24-hour window to respond to the template message.
NOTE
You can only send text messages if your user responds to the template message.
1. Sign up for free
Before you get started, sign up for a Kaleyra.io account for free and create an API key.
2. Pre-requisites
Below listed are the pre-requisites for using Kalyera WhatsApp API’s
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
For more details, read what WhatsApp has to say about creating a business account.
3. Send a text message
You can use the below API’s to send text message via WhatsApp account
Request Format - POST
curl --location --request POST "https://api.kaleyra.io/v1/<SID>/messages" \ \
--header 'Content-Type: <CONTENT_TYPE>'\
--header 'api-key: <API_KEY>' \
--form 'to="<TO_NUMBER>"' \
--form 'type="<TYPE>"' \
--form 'channel="<CHANNEL>"' \
--form 'from="<FROM_NUMBER>"' \
--form 'callback_url="<CALLBACK_URL>"'
--form 'body="<BODY>"'
Sandbox Request
curl --location --request POST "https://api.kaleyra.io/v1/<SID>/messages" \ \
--header 'Content-Type: <CONTENT_TYPE>'\
--header 'api-key: <API_KEY>' \
--form 'to="<TO_NUMBER>"' \
--form 'type="<TYPE>"' \
--form 'channel="<CHANNEL>"' \
--form 'from="<FROM_NUMBER>"' \
--form 'callback_url="<CALLBACK_URL>"'
--form 'template_name="<NAME>"' \
--form 'params="<TEMPLATE_BODY_PARAMETERS>"' \
--form 'source="sandbox"'
Sandbox Request Sample
curl --location --request POST 'https://api.kaleyra.io/v1/HXAP1XXXXXX17XX/messages' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'api-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--form 'to="XXXXXXXXXXXX"' \
--form 'type="template"' \
--form 'params="\"Raman\""' \
--form 'template_name="british_council"' \
--form 'channel="whatsapp"' \
--form 'from="XXXXXXXXXXXX"' \
--form 'callback_url="https://webhook.site/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"' \
--form 'source="sandbox"'
Request Format - GET
curl --location --request GET 'https://api.kaleyra.io/v1/<SID>/messages?channel=<CHANNEL_NAME>&to=<TO_NUMBER>&from=<FROM_NUMBER>&type=<MESSAGE_TYPE>&callback_url=<CALLBACK_URL>'
--header 'api-key: <API_KEY>'
NOTE
Replace the placeholders above with relevant values as mentioned below.
Replace | With | Examples | Mandatory? |
|---|---|---|---|
SID | Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key. | HXXXXXXX071US | True |
CONTENT_TYPE | Indicates the format of the content the API will be processing. | application/json | True |
API_KEY | Your API Key generated by Kaleyra.io. | Ac4XXXXX21f | True |
TO_NUMBER | A valid WhatsApp 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 | True |
MESSAGE_TYPE | Message format for the message. | text | True |
CHANNEL_NAME | Channel on which message must be sent. | True | |
FROM_NUMBER | The number registered with WhatsApp business from which the message is to be sent. Ensure that the country code is prefixed to the number. (E164 format). | +1202XXXXXXX | True |
CALLBACK_URL | The URL that Kaleyra.io | False | |
BODY | Body of the message. | Hi, Your order has been shipped. | True |
developers.kaleyra.io4. Response Format
Success message response of both POST and GET method will be shown as below:
{
"id": "cc8074ae-990d-40f5-b604-1150b9e2ab32",
"type": "text",
"body": "Hi, your order has been shipped",
"createdDateTime": "2020-01-29 06:22:21+00:00",
"totalCount": 1,
"data": [
{
"message_id": "cc8074ae-990d-40f5-b604-1150b9e2ab32:0",
"recipient": "1202XXXXXXX"
}
],
"error": {}
}
Error Codes
The below table provides information about the error codes you would receive when executing the WhatsApp Text Message API.
Error Code | Parameter | Description |
|---|---|---|
E13008 | from_invalid | Invalid or in-correct input of the From number. |
E13009 | to_invalid | Invalid or in-correct input of the TO number. |
E413 | all parameters except body | Invalid or In-Correct input for passing HTML tags in parameters. |
Updated 6 months ago