SMS URL Shortening API

POST Method

The SMS URL Shortening API feature allows you to send an SMS containing shortened URLs in the text message. You can also send a personalized URL to each recipient passing the URL as a dynamic variable called {URL} in the kaleyra.io SMS API body and passing the actual long URL as a parameter. The long URL is automatically shortened and the short URL is used to replace the {URL} placeholder in the SMS text. The end customer will receive the SMS with a short URL.

📘
Note:
Ensure that the {URL} parameter passed in the message body must be used as variable parameter {#var#} in the template configured on kaleyra.io.

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 Short URL

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

Request Format

The following is the request format to send SMS with short URL:

curl --location --request POST 'https://<api_domain>/v1/<sid>/sms' \
--H 'api-key:<api-key>' \
--H 'content-type:<content-type>' \
--H 'channel:<channel>' \
--d 'to=<to>' \
--d 'body=<body> ' \
--d 'sender=<sender>' \
--d 'type=<type>' \
--d 'url_data=
			{
				"shorten_url": "<shorten_url>",
        "url": "<url>",
        "slug": "<slug>",
        "callback_profile_id>": "<callback_profile_id>",
        "track_user": "<track_user>"
    	}'

Sample Request Format

The following is the sample request format to send SMS with short URL:

curl --location --request POST 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms' \
--H 'api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--H 'Content-Type:application/json' \
--H 'channel:sms' \
--d 'to=+91xxxxxxxxxx' \
--d 'body=Click here to get some exciting offers {URL}' \
--d 'sender=KLRHXA' \
--d 'type=MKT' \
--d 'url_data=
			{
				"shorten_url":1,
        "url":"https://www.kaleyra.com/",
        "slug":"offers",
        "callback_profile_id":"IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX",
        "track_user":1
      }'

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). Generated by Kaleyra.io while creating an API key.	HXAP16XXXXXX97IN	True
`api-key`	String	The API Key that you have generated in the Kaleyra.io.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	True
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	True
`channel`	String	Specifies the name of the channel used. The following are the supported channels: SMS WhatsApp Email	sms	True
`to`	Integer	Recipient's MSISDN.	`+91XXXXXXXXXX`	True
`body`	String	Body content. Must contain the dynamic variable {URL}.	Click here to get some exciting offers {URL}	True
`sender`	String	Originator/Alphanumeric ID (default KLRHXA).	KLRHXA	True
`type`	Alphabets	Format of the message. Note: This is not a mandatory field. For customers in the Indian region, the available SMS Types are OTP, Transactional (TNX), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) route types are available.	MKT	True
`url_data`	JSON	Specifies the JSON value format for the URL_data object.	See the specific table for details.	If shortening URL is required, then it is set to True else False.

The following table describes the different attributes used for the url_data JSON object:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`shorten_url`	Integer	Specifies if the URL should be shortened or not. The shorten_url value must be 0 or 1 inside the url_data object.	0 or 1	If shortening URL is required, then it is set to True else False.
`url`	String	Specifies the original URL to be shortened and replace in the message body.	`http://www.kaleyra.io`	True
`slug` (Optional)	String	Specifies unique alias endpoint for the shortened URL. The slug must have a unique value and it cannot exceed 10 characters. The slug value can be of only alphabets, numbers, and dash in the url_data object.	offers	False
`callback_profile_id` (Optional)	Object	Specifies the URL details you receive each time when the shortened URL is clicked.	`IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXX`	False
`track_user` (Optional)	Integer	Specifies the user tracking for the URL. The value must be 0 or 1 inside the url_data object.	0 or 1	False

📘
Notes:

Any URL passed in the parameters that are not “{URL}” or as a static part of the body will not be shortened.

If you are using the URL shortener in the SMS API URL parameter, then the original URL gets replaced with the shortened URL before sending it out to the carrier.

Success Response

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

{
    "body": "Click here to get some exciting offers {URL}.",
    "sender": "KALYRA",
    "type": "MKT",
    "source": "API",
    "id": "afxxxx67-7xxf-4xx9-8xxb-99xxxxxxxx61",
    "createdDateTime": "2023-05-19 09:11:09+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "afxxxx67-7xxf-4xx9-8xxb-99xxxxxxxx61:1",
            "recipient": "+91xxxxxxxxxx"
        }
    ],
    "error": {}
}

Failure Responses

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

{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "shorten_url": "shorten_url value must be 0 or 1 inside url_data object"
    }
}

{
    "code": "E413",
    "message": "Invalid/incorrect inputs",
    "data": [],
    "error": {
        "slug": "slug value can only have alphabets, numbers and dash in url_data object"
    }
}

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 6 days ago