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. Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
  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.

  1. Send a text message.

You can use the below APIs to send a text message through WhatsApp account.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

Request Format - POST

curl --location --request POST 'https://<api_domain>/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 'ref="<OPTIONAL_PARAMETER>"' \
--form 'ref1="<OPTIONAL_PARAMETER1>"' \
--form 'ref2="<OPTIONAL_PARAMETER2>"' \
--form 'body="<BODY>"'

Sandbox Request

curl --location --request POST "https://<api_domain>/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.in.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_domain>/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.

HXXXXXXX071IN

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.

WhatsApp

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
should send information to when your number receives a response. This URL can be accessed publicly.
Click here for an example.

False

REF(Optional parameter)

Include the contextual information in this parameter. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only.

Customer Name

False

REF1(Optional Parameter)

Include the contextual information in this parameter. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only.

Company Name

False

REF2(Optional Parameter)

Include the contextual information in this parameter. For Example, Name, Customer ID, and many more.
Limit: The variable can be 255 characters long only.

Designation

False

BODY

Body of the message.

Hi, Your order has been shipped.

True

  1. Response Format

Success message response of both POST and GET method will be shown as below:

{
    "id": "cc8074ae-990d-40f5-b604-11XXX9e2ab32",
    "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-115XXXe2ab32: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 CodeParameterDescription
E13008from_invalidInvalid or in-correct input of the From number.
E13009to_invalidInvalid or in-correct input of the TO number.
E413all parameters except for bodyInvalid or In-Correct input for passing HTML tags in parameters.




© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.