Send OTP SMS

POST Method

kaleyra.io provides an API that simplifies sending critical and high priority SMS containing a one-time password. Use this API to send OTP SMS to your customers.

Prerequisites

Before sending the SMS, you must configure the SMS channel in kaleyra.io.
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.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

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

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to send OTP SMS

To send OTP SMS use the <api_domain>/v1/<sid>/sms endpoint with the following request method:

Request Format

The following is the request format to send the OTP SMS for non-Indian companies:

curl -X POST "https://<api_domain>/v1/<sid>/sms" \
     -H "Content-Type:<content-type>" \
     -H "api-key:<api-key>" \
     -d "to=<to>" \
     -d "type=<type>" \
     -d "sender=<sender>" \
     -d "body=<body>" \
     -d "callback_profile_id=<callback_profile_id>"

The following is the request format to send the OTP SMS for customers from India:

curl -X POST "https://<api_domain>/v1/<sid>/sms" \
     -H "Content-Type:<content-type>" \
     -H "api-key:<api-key>" \
     -d "to=<to>" \
     -d "type=<type>" \
     -d "sender=<sender>" \
     -d "body=<body>" \
     -d "callback_profile_id=<callback_profile_id>" \
     -d "template_id=<template_id>"

Sample Request Format

The following is the sample request format to send OTP SMS for non-Indian companies:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "Content-Type:application/json" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -d "to=+91XXXXXXXXXX"\
     -d "sender=KLRHXA" \
     -d "type=OTP" \
     -d "body=Dear Customer, 1234 is your OTP (One Time Password) for the transaction."\
     -d "callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX"

The following is the sample request format to send OTP SMS for customers from India:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "Content-Type:application/json" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -d "to=+91XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "type=OTP" \
     -d "body=Dear Customer, 1234 is your OTP (One Time Password) for the transaction." \
     -d "callback_profile_id=IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX" \
     -d "template_id=101XXXXXX012"

📘
Note:
The template_id should be the one registered in the DLT system.

URL Parameters and Headers

Following is the list of parameters and headers to send the outgoing message request:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	`HXAP16XXXXXX97IN`	Yes
`api-key`	String	API key generated from kaleyra.io account.	`Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3`	Yes
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`to`	String	Phone number of the end customer you want to send a message to.	`+91XXXXXXXXXX`	Yes (valid phone numbers only)
`sender`	String	Alphanumeric Sender ID displayed on recipient devices.	KLRHXA	Yes

Following is the list of attributes to be used in the payload to send the OTP SMS message:

Parameter	Data Type	Description	Example	Mandatory?
`type`	String	Route type. Note*: To send an OTP, the only allowed value is OTP.	OTP	Yes
`body`	String	Body of the SMS. It is required if `template_id` is not provided.	"Dear Customer, 1234 is your OTP (One Time Password) for the transaction."	Conditional
`callback_profile_id`	String	The callback profile ID of the callback profile to be used to send webhook to your system about SMS status updates. For more information related to callback profiles, see callback profiles page	IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX	Yes
`template_id`	String	Template ID for pre-registered templates. Required if the body is not provided. `template_id` must be 12 to 30 digits and exist as a tag.	101XXXXXX012	Conditional

📘
Note:
For template_id, if the body parameter is passed together with a template ID and template data, then the Body will have priority, and the template ID and template data will have less priority.

Success Response

The following success response is received when the JSON script has the correct syntax:

Success response for non-Indian companies.

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "OTP",
  "body": "Hello! Your OTP is 1234.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Success response for Indian customers.

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "OTP",
  "template_id": "2xxxxxxxxxxxx",
  "body": "Hello! Your OTP is 1234.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Response

The following failure response are received when the JSON script has an incorrect syntax:

Multiple Mobile Numbers
Multiple Mobile Numbers are not allowed for the OTP type message. Check the To parameter for the multiple numbers.

{
  "code": "E404",
  "message": "If Type is OTP then only one mobile number is allowed.",
  "error": {
    "time": "If Type is OTP then only one mobile number is allowed."
  }
}

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:

For information related to SMS error codes, see SMS Error Codes.
For information related to SMS status and status trace codes, see SMS Status and Status Trace Codes.

Updated 13 days ago