Send an Authentication Template Message

POST Method

The Send an Authentication Template Message API allows you to send WhatsApp messages using the approved authentication templates.

To send an Authentication Template Message, perform the following steps:

  1. Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
  2. A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on Kaleyra.io.
    To set up a WhatsApp account on Kaleyra.io, see: https://developers.kaleyra.io/docs/manual-signup
    And https://developers.kaleyra.io/docs/embedded-signup
  3. Send an Authentication Template Message API request.

Base URL

<https://api.kaleyra.io/v1/><SID>

API request to send Authentication Template Message

To send an authentication template message, use the /messages endpoint.

Request Format

The following is the request format to send the message using the authentication template.

curl --location 'https://api.kaleyra.io/v1/<sid>/messages' \
--header 'api-key: <api_key>' \
--form 'to: <to_number>' \
--form 'type: <message_type>' \
--form 'template_name: <template_name>' \
--form 'channel: <channel>' \
--form 'from: <from_number>' \
--form 'verification_code: <verification_code>' \
--form 'callback_url: <callback_url>' 

Sample Request Format

Following is the sample request format for the authentication template message:

curl --location 'https://api.kaleyra.io/v1/HXIN178XXXXXXXIN/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--form 'to: "91936XXXXX09"' \
--form 'type: "authenticationtemplate"' \
--form 'template_name: "auth1"' \
--form 'channel: "whatsApp"' \
--form 'from: "91806XXXXX81"' \
--form 'verification_code: "81XXX23"' \
--form 'callback_url: "https://webhook.site/c16bXXXX-733b-4124-a97d-90bXXXXX8efb"'

Parameters and Data Types

Following is the list of parameters and data types supported:

ParameterData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).HXXXXXXX071USYes
api-keyStringAPI key generated from kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes
to_numberIntegerA valid WhatsApp number of the recipient. Make sure that the country code is prefixed to the number. (E164 format).

Notes: You can add multiple recipients and separate each number using the comma (,) delimiter. You can either pass the numbers by using with and without +.
91936XXXXX09 OR +91936XXXXX09Yes
message_typeStringType of the message to be sent as defined by Meta. authenticationtemplateYes
template_nameStringName of the WhatsApp media template that was created in the kaleyra.io portal. Note: The template_name must be approved by WhatsApp before you start using this API.auth1Yes
channel_nameStringChannel on which the message must be sent.
For WhatsApp channel, the only allowed value is WhatsApp.
WhatsAppYes
from_numberStringThe 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).91806XXXXX81 OR +91806XXXXX81Yes
verification codeString or IntegerThis field contains the verification code for the user. This value will be copied once the COPY CODE button is tapped. The maximum value supported is 15 characters. 81XXX23Yes
callback_profileStringSpecifies the callback profile to receive notifications regarding the WhatsApp message status (sent, delivered, read, and failed). For more information related to callback profiles, see callback profiles page.
Note: You can also use "callback URL" for the WhatsApp channel.
sample_26fb2aa3-d2eb-4799-9503-b1eabXXXX9fcNo

Sample Success Response

The following success message appears with status 202 Accepted:

{
    "id": "854d2ba9-d95d-4bxx-a76d-5bb8bxxxx948",
    "type": "authenticationtemplate",
    "body": null,
    "createdDateTime": "2023-12-14 08:23:44+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "854xxxd9-d95d-4b5e-a76d-5bb8xxxxxb9e:0",
            "recipient": "9163xxxxx835"
        }
    ],
    "error": {}
}

Sample Failure Response

{
    "code": "WAE0021",
    "message": "verification_code is required for Authentication templates",
    "data": [],
    "error": {
        "error": "verification_code is required for Authentication templates"
    }
}

Error Codes

For information related to the WhatsApp error code, see WhatsApp Error Codes.