SMS URL Shortening API

POST Method

Description

The SMS URL Shortening API feature allows users to send SMSs with shortened URLs. You can add a string {URL} in the kaleyra.io SMS API body and pass the original URL as a parameter. The original URL is shortened and replaces the {URL} string in the SMS text. The end customer will receive the SMS with a short URL.

📘

Note:

Please ensure the {URL} parameter passed in the message body must be in the place of any variable parameter {#var#} in the template configured on kaleyra.io.

Base URL

"https://api.kaleyra.io/v1/"

To use the SMS shortening URL, follow the below steps:

1. Signup or Login to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key.

📘

Note:

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.

2. API Command to use SMS Shortening URL

Request Format

To request an SMS URL Shortening API use the /messages endpoint.

POST Method
curl --location --request POST 'https://api.kaleyra.io/v1/<SID>/messages' \
--H 'api-key: <API_KEY>' \
--H 'channel: <CHANNEL_NAME>' \
--d 'to=<TO_NUMBER>' \
--d 'body=<BODY> ' \
--d 'sender=<SENDER_ID>' \
--d 'type=<MESSAGE_TYPE>' \
--d 'url_data={"shorten_url":1,"url":"https://kaleyra.com/","slug":"avi18","callback_url":"https://webhook.site/7a8f664e-e1df-4f59-8ddc-55abda875656","track_user":1}'

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

Below is the list of parameters and variables used:

Replace

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

API_KEY

String

The API Key that you have generated in the Kaleyra.io.

Ac4XXXXX21f

True

CHANNEL_NAME

String

Specifies the name of the channel used.

SMS

True

TO_NUMBER

Integer

Recipient's MSISDN.

+1XXXXXXXXXX

True

BODY

String

Body content.

Click here to get some exciting offers {URL}

True

SENDER_ID

String

Originator/Alphanumeric ID (default KLRHXA).

KLRHXA

True

MESSAGE_TYPE

Alphabets

Format of the message.

Text

True

URL_data

JSON

Specifies the JSON value format for the URL_data object.

shorten_url, track_user,
url, slug, and callback_url

If shortening URL is required, then it is set to True else False.

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 value can be of only alphabets, numbers, and dash in the url_data object.

offers

False

CALLBACK_URL (Optional)

Object

Specifies the URL details you receive each time when the shortened URL is clicked.

https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254

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

📘

Note:

  • Any URL passed in the parameters that are not “{URL}” or as a static part of the body will not be shortened.
  • If you want to shorten the SMS API URL parameter, then the user will hit the URL shortener API on the fly and replaces the URL with the shortened URL before sending it out to the carrier.

Response Format

This section provides you the success and failure JSON response format for different scenarios.

Success Response

{
    "body": "Hello, Test {URL} this is TXN message.",
    "sender": "KALYRA",
    "type": "M2M",
    "source": "API",
    "id": "aff47767-7c0f-4d19-800b-9988b7074661",
    "createdDateTime": "2021-05-19 09:11:09+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "aff47767-7c0f-4d19-800b-9988b7074661:1",
            "recipient": "919008005778"
        }
    ],
    "error": {}
}

Failure Response

{
    "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"
    }
}

Sample Request

curl --location --request POST '{url}/v1/SID/messages' 
--header 'api-key: A8a4472219725966870ada7963ddcf2dd' 
--form 'channel=sms' 
--form 'to=919040874780' 
--form 'body=hello {url} testinf {URL} your otp is 1234' 
--form 'sender=TEST' 
--form 'url_data={"shorten_url":1,"url":"https://google.com/%22,%22slug%22:%22avi18%22,%22callback_url%22:%22https://webhook.site/7a8f664e-e1df-4f59-8ddc-55abda875656%22,%22track_user%22:1%7D'

Did this page help you?