SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

SMS URL Shortening API

POST Method

Suggest Edits

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_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.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 / HeadersData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXAP16XXXXXX97INTrue
api-keyStringThe API Key that you have generated in the Kaleyra.io.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3True
content-typeStringIndicates the format of the content the API will be processing.The only allowed value is application/json.True
channelStringSpecifies the name of the channel used. The following are the supported channels:

- SMS
- WhatsApp
- Email		smsTrue
toIntegerRecipient's MSISDN.+91XXXXXXXXXXTrue
bodyStringBody content. Must contain the dynamic variable {URL}.Click here to get some exciting offers {URL}True
senderStringOriginator/Alphanumeric ID (default KLRHXA).KLRHXATrue
typeAlphabetsFormat 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.MKTTrue
url_dataJSONSpecifies 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 / HeadersData TypeDescriptionExampleMandatory?
shorten_urlIntegerSpecifies if the URL should be shortened or not. The shorten_url value must be 0 or 1 inside the url_data object.0 or 1If shortening URL is required, then it is set to True else False.
urlStringSpecifies the original URL to be shortened and replace in the message body.http://www.kaleyra.ioTrue
slug (Optional)StringSpecifies 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.		offersFalse
callback_profile_id (Optional)ObjectSpecifies the URL details you receive each time when the shortened URL is clicked.IN_09b3dfa7-e05d-4d84-ab2d-6ed654272XXXFalse
track_user (Optional)IntegerSpecifies the user tracking for the URL.
The value must be 0 or 1 inside the url_data object.		0 or 1False

📘

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:

Updated about 15 hours ago