SMS URL Shortening API

POST Method

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/><SID>

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. To view the API Key and the SID, see View API Key and SID.

📘

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.

  1. 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:

ReplaceVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
API_KEYStringThe API Key that you have generated in the Kaleyra.io.Ac4XXXXX21fTrue
CHANNEL_NAMEStringSpecifies the name of the channel used.SMSTrue
TO_NUMBERIntegerRecipient's MSISDN.+1XXXXXXXXXXTrue
BODYStringBody content.Click here to get some exciting offers {URL}True
SENDER_IDStringOriginator/Alphanumeric ID (default KLRHXA).KLRHXATrue
MESSAGE_TYPEAlphabetsFormat of the message.TextTrue
URL_dataJSONSpecifies 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_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 value can be of only alphabets, numbers, and dash in the url_data object.
offersFalse
CALLBACK_URL (Optional)ObjectSpecifies the URL details you receive each time when the shortened URL is clicked.https://webhook.site/3cbfa310-7615-4bf6-b6f3-0e564493a254False
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

📘

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'