Send SMS Over IP (SOIP)

POST Method

Kaleyra.io offers an API that accepts raw data in JSON format to send messages to single or multiple numbers on the Xiaomi device, using SMS over Internet Protocol (SOIP) technology framework.

📘

Note:

You must have MI message feature enabled on your Xiaomi device to receive SMS Over IP.

👍

Base URL

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

To send messages to single or multiple numbers using raw data in JSON format, perform the following 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.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 request to Send SMS using raw data in JSON format

Request Format

Basic Text Message (TXT)
To send a normal text message, use the messages/soip endpoints in the following request format:

curl -X POST "https://api.kaleyra.io/v1/<SID>/messages/soip" \
    -H "Content-Type: <CONTENT_TYPE>" \
    -H "api-key: <API_KEY>" \
    -d "data-raw" '{
            "source": "SOURCE",
            "type": "TYPE",
            "route": "ROUTE",
            "to": "TO_NUMBER",
            "from": "FROM",
            "body": "MESSAGE_BODY",
            "callback_profile_id": "CALLBACK"
        }'
Rich Media Message (RMC) To Send Rich Media with Actionable Content you can use the RMC type with messages/soip endpoints in the following request format:
curl -X POST "https://api.kaleyra.io/v1/<SID>/messages/soip" \
    -H "Content-Type: <CONTENT_TYPE>" \
    -H "api-key: <API_KEY>" \
    -d "data-raw" '  {
            "to": "TO_NUMBER",
            "from": "FROM",
            "body": "BODY",
            "source": "SOURCE",
            "type": "TYPE",
            "route": "ROUTE",
            "title": ["TITLE"],
            "category": "CATEGORY",
            "sub_category": "SUB_CATEGORY",
            "rich_media": [
                {
                    "media_type": MEDIA_TYPE,
                    "url": "URL",
                    "display_ratio": "DISPLAY_RATIO",
                    "cover":"COVER"
                }
            ],
            "actions": [
                {
                    "action_type": ACTION_TYPE,
                    "action_content": "ACTION_CONTENT",
                    "action_rank": "ACTION_RANK",
                    "action_to": "ACTION_TO"
                },
                {
                    "action_type": ACTION_TYPE,
                    "action_content": "ACTION_CONTENT",
                    "action_rank": "ACTION_RANK",
                    "action_to": "ACTION_TO"
                }
        ],
    "callback_profile_id": "CALLBACK"
  }
Call To Action (CTA) To Send Actionable buttons you can use the CTA type with messages/soip endpoints in the following request format:
curl -X POST "https://api.kaleyra.io/v1/<SID>/messages/soip" \
    -H "Content-Type: <CONTENT_TYPE>" \
    -H "api-key: <API_KEY>" \
    -d "data-raw" '  {
            "to": "TO_NUMBER",
            "from": "FROM",
            "body": "BODY",
            "source": "SOURCE",
            "type": "TYPE",
            "route": "ROUTE",
            "title": ["TITLE"],
            "category": "CATEGORY",
            "sub_category": "SUB_CATEGORY",
            "core_entity": "CORE_ENTITY",
            "actions": [
                {
                    "action_type": ACTION_TYPE,
                    "action_content": "ACTION_CONTENT",
                    "action_rank": "ACTION_RANK",
                    "action_to": "ACTION_TO"
                },
                {
                    "action_type": ACTION_TYPE,
                    "action_content": "ACTION_CONTENT",
                    "action_rank": "ACTION_RANK",
              "action_to": "ACTION_TO"
                },
                {
                    "action_type":ACTION_TYPE,
                    "action_content": "ACTION_CONTENT",
                    "action_rank": "ACTION_RANK",
                    "action_to":{
                    "date": "DATE",
                    "time": "TIME",
                    "title": "TITLE",
                "   event": "EVENT"
            }
            },
            {
                "action_type": ACTION_TYPE,
                "action_content": "ACTION_CONTENT",
                "action_rank": "ACTION_RANK",
                "deep_links": [
                {
                        "action": "ACTION",
                        "packageName": "PACKAGE_NAME",
                        "className": "CLASS_NAME"
                }
            ]
            }
        ],
        "callback_profile_id": "CALLBACK"
    }

Parameters and Variables

TXT Parameters and Variables

The following table displays the parameter and variables used for Normal Text Message:

Parameter

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier).

HXXXXXXX071US

True.

CONTENT_TYPE

String

The format in which the data is sent.

application/x-www-form-urlencoded

True.

API_KEY

Alphanumeric

API key generated from Kaleyra.io account.

Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3

True.

SOURCE

String

Select the source type. If no value is passed or kept empty, the default value is API.

API

False.

TYPE

String

Type of message. For example - TXT, RMC, or CTA.

TXT

True.

ROUTE

String

Route type. If no value is passed or for empty field, the default is MKT.
For example - MKT, TXN, or OTP.

MKT

False.

TO_NUMBER

String

Mobile number to which SMS is Sent. You can add multiple mobile numbers separated by “,“ (comma).
Mobile number should contain country code with or without +.

+13236xxxxx7

True.

FROM

String

Sender ID assigned to the account from which the SMS will be sent over IP.

TEST-NUM

True.

MESSAGE_BODY

String

Message contents that need to be sent.

Message Body

True.

TITLE

Array

Mandatory for RMC and CTA. It can have either one title or maximum up to four titles.

title0

True for RMC and CTA.

CATEGORY

String

Enter the category. Mandatory for RMC and CTA.

Category

True for RMC and CTA.

SUB_CATEGORY

String

Define sub category which will be displayed in the message.

Sub Category

False.

RICH_MEDIA

JSON Array

The rich Media holds JSON object for adding images and videos in the message.

media_type, url, and display_ratio

True for RMC and CTA.

CORE_ENTITY

String

The Core Entity is mandatory in case of CTA.

Core Entity

True for CTA.

ACTIONS

JSON Array

The Action contains JSON object for adding actionable buttons.

action_type, action_content, action_rank, and action_to

True for CTA.

CALLBACK

String

Unique callback profile ID is set for each account for a callback.

SG_0xxxxxx8-2xxd-4xx3-bxxe-b6xxxxxxxxe4

False.

RMC Parameters and Variables

Apart from the Parameters and Variables listed for Normal Text Messages, use the following parameters and variables additionally for RMC:

Parameter

Variable

Description

Example

Mandatory

COVER

String

Cover Image URL which is exposed publicly for media type 2.

1

False

MEDIA_TYPE

Numeric

Type of media needs to be sent in the message. For example:
1 - Image
2 - video

1

True

URL

String

Media URL exposed for all the users.

https://net-sms.s3.ap-south-1.amazonaws.com/2/dxxxxxb.png

True

DISPLAY_RATIO

Display Ratio of the media. Valid values are normal and tall.

normal

True

CTA Parameters and Variables Apart from the Parameters and Variables listed for basic Text Messages, use the following parameters and variables additionally for CTA:

Parameter

Variable

Description

Example

Mandatory

ACTION_TYPE

Numeric

Type of Actionable content needs to be added. Example for Supported values - 1,2,3,4, and 5.

1 - Open Link

2 - Add Calender Event

3 - Open External App

4 - Copy Content

5 - Phone Call.

1

True

ACTION_CONTENT

String

Actionable content.

Track Order

True

ACTION_RANK

String

Priority for actionable data.

1

True

ACTION_TO

String

Mandatory for type 1, 2, 4, 5, Support Actionable string or JSON content.

  • For Type 1, 4, and 5 Actionable String
  • For Type 2 JSON Content.

https://www.google.com

True

DEEP_LINKS

JSON Array

Mandatory for type 3 (Open App) contains array of JSON.

action, packageName, and className

True

Action To Fields Parameters and Variables The following table displays the mandatory parameters and variable for type 2 (Add to Calendar):

Parameter

Variable

Description

Example

Mandatory

DATE

String

Date on which the event needs to be created. Date format “YYYY-MM-DD”.

2021-10-19

True

TIME

String

Time on which the event needs to be created. Time format “Minute:Second“ (24 hour format).

22:30

True

TITLE

String

Title of the event.

Title of the event

True

EVENT

String

Description of the event

Description of the event

True

Deep links Fields Parameters and Variables The following table displays the mandatory parameters and variable for type 3 (Open App):

Parameter

Variable

Description

Example

Mandatory

ACTION

String

Android Application intent

android.intent.action.MAIN

True

PACKAGE_NAME

String

Android Application Package Name

com.flipkart.android

True

CLASS_NAME/URI_BASE

String

Android Screen Class name or play store URL

com.flipkart.android.SplashActivity

True

Response Format

This section provides you with the success and failure JSON response format for different scenarios. Refer to the below sections for more information:

Sample Success Response

Basic successful response with raw data in JSON format to specific numbers on the Xiaomi mobile.

{
    "actions": [
        {
            "action_content": "Open Link",
            "action_rank": "1",
            "action_to": "https://www.kaleyra.com",
            "action_type": 1
        },
        {
            "action_content": "Contact",
            "action_rank": "2",
            "action_to": "+13236xxxxx7",
            "action_type": 5
        },
        {
            "action_content": "Open App",
            "action_rank": "3",
            "action_type": 3,
            "deep_links": [
                {
                    "action": "android.intent.action.MAIN",
                    "className": "com.flipkart.android.SplashActivity",
                    "packageName": "com.flipkart.android"
                }
            ]
        }
    ],
    "body": "This is Test Message",
    "callback_profile_id": "SG_axxxxxxd-2xx5-4xxe-bxxb-98xxxxxxxx44",
    "data": [
        {
            "message_id": "ccfae36f-4a99-443e-ac8a-b6f5c7c98ae1:0",
            "recepient": "+13336xxxxx7"
        }
    ],
    "from": "TEST-NUM",
    "kid": "ccxxxx6f-4xx9-4xxe-axxa-b6xxxxxxxxe1",
    "rich_media": [
        {
            "cover": "https://net-sms.s3.ap-south-1.amazonaws.com/2/d7xxxxxxxx28.jpg",
            "display_ratio": "tall",
            "media_type": 2,
            "url": "http://techslides.com/demos/sample-videos/small.mp4"
        }
    ],
    "route": "TXN",
    "type": "RMC"
}

Sample Failure Response

Basic response with an invalid number (to) or empty number

If your response fails due to the invalid number (to) or empty number, please re-execute the command providing a valid number.

{
  "error": {
    "code": "E750",
    "type": "VALIDATION_ERROR",
    "parameter": "to",
    "message": "to parameter is mandatory and cannot be empty",
    "reference": ""
  }
}

Basic response with an invalid type or empty type

If your response fails due to the invalid type or empty type, please re-execute the command providing a valid type.

{
  "error": {
    "code": "E754",
    "type": "VALIDATION_ERROR",
    "parameter": "type",
    "message": "Invalid type. Allowed routes are TXT,RMC,CTA",
    "reference": ""
  }
}

Basic response with an invalid route or empty route

If your response fails due to the invalid route or empty route, please re-execute the command providing a valid route. Valid route are TXN, OTP, or MKT.

{
  "error": {
    "code": "E752",
    "type": "VALIDATION_ERROR",
    "parameter": "route",
    "message": "Invalid route. Allowed routes are TXN,OTP,MKT",
    "reference": ""
  }
}

Basic response with an invalid title or empty title

If your response fails due to the invalid title or empty title, please re-execute the command providing a valid title.

{
  "error": {
    "code": "E761",
    "type": "VALIDATION_ERROR",
    "parameter": "title",
    "message": "title is mandatory and can have minimum of 1 and a maximum of 4 values",
    "reference": ""
  }
}

Basic response with an invalid action or empty action

If your response fails due to the invalid action or empty action, please re-execute the command providing a valid action.

{
  "error": {
    "code": "E757",
    "type": "VALIDATION_ERROR",
    "parameter": "actions",
    "message": "For type CTA, actions field is required and cannot be empty",
    "reference": ""
  }
}

Sample Request

TXT Sample Request
To send a normal text message, use the messages/soip endpoints in the following request format:

curl -X POST "https://api.kaleyra.io/v1/<SID>/messages/soip" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
    -d "data-raw" '{
            "source": "API",
            "type": "TXT",
            "route": "MKT",
            "to": "13236xxxxx7, +13336xxxxx7",
            "from": "TEST-NUM",
            "body": "Message Body",
            "callback_profile_id": "SG_0xxxxxx8-2xxd-4xx3-bxxe-b6xxxxxxxxe4"
    }'
RMC Sample Request To Send Rich Media with Actionable Content you can use the RMC type with messages/soip endpoints in the following request format:

Video Sample Request

curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
    -d "data-raw" '  {
            "to": "13236xxxxx7, +13336xxxxx7",
            "from": "TEST-NUM",
            "body": "This is Test Message",
            "source": "API",
            "type": "RMC",
            "route": "TXN",
            "title": ["title0"],
            "category": "Category",
            "sub_category": "Sub Category",
            "rich_media": [
                {
                    "media_type": 2,
                    "url": "http://techslides.com/demos/sample-videos/small.mp4",
                        "display_ratio": "tall",
                    "cover":"https://net-sms.s3.ap-south-1.amazonaws.com/2/d7XXXXXXXX28.jpg"
                    }
    ],
                "actions": [
                {
                    "action_type": 1,
                    "action_content": "Open Link",
                    "action_rank": "1",
                    "action_to": "https://www.kaleyra.com"
                    },
                {
                    "action_type": 5,
                    "action_content": "Contact",
                    "action_rank": "2",
                    "action_to": "77XXXX"
                    }
        ],
        "callback_profile_id": "SG_axxxxxxd-2xx5-4xxe-bxxb-98xxxxxxxx44"
}'

 

Image Sample Request

curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
    -d "data-raw" '  {
            "to": "13236xxxxx7",
            "from": "TEST-NUM",
            "body": "Test message",
            "source": "API",
            "type": "RMC",
            "route": "TXN",
            "title": ["title0"],
            "category": "Category",
            "sub_category": "Sub Category",
            "rich_media": [
                    {
                        "media_type": 1,
                        "url": "https://net-sms.s3.ap-south-1.amazonaws.com/2/d73xxxxxxxxxx28.jpg",
                        "display_ratio": "normal"
                    }
            ],
            "callback_profile_id": "SG_axxxxxxd-2xx5-4xxe-bxxb-99xxxxxxxx44"
}'
CTA Sample Request To Send Actionable buttons you can use the CTA type with messages/soip endpoints in the following request format:
curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
    -d "data-raw" ' {
            "to": "13236xxxxx7",
            "from": "TEST-NUM",
            "body": "Test is test message",
            "source": "API",
            "type": "CTA",
            "route": "TXN",
            "title": ["title0", "title1", "title2", "title3"],
            "category": "Category",
            "sub_category": "Sub Category",
            "core_entity": "Copy Text",
            "actions": [
                {
                "action_type": 4,
                "action_content": "Copy Text",
                "action_rank": "0",
                "action_to": "Hello World"
                },
                {
                "action_type": 1,
                "action_content": "Open Link",
                "action_rank": "1",
                "action_to": "https://www.kaleyra.com"
                },
                {
                "action_type":2,
                "action_content": "Add Event",
                "action_rank": "2",
                "action_to":{
                "date": "2021-10-19",
                "time": "22:30",
                "title": "Title of the event",
                "event": "Description of the event"
            }
            },
            {
                "action_type": 3,
                "action_content": "Open App",
                "action_rank": "3",
                "deep_links": [
                {
                    "action": "android.intent.action.MAIN",
                    "packageName": "com.flipkart.android",
                    "className": "com.flipkart.android.SplashActivity"
                }
            ]
            }
        ],
        "callback_profile_id": "SG_a2xxxx6d-2xx5-4xxe-bxxb-98xxxxxxxx44"
}'

Rejections Error and Message

The following table provides information about the rejection error and its message:

Error

Message

INV-NUMBER

The recipient's mobile number is invalid.

MOB-NOTALLOWED

With the default SenderID (KLRHXA), you can only send messages to your team.

INV-MOB-PATTRN

The recipient's mobile number is invalid.

INV-SENDER

The sender is Mandatory.

INV-TYPE

The type is Mandatory.

INV-ROUTE

Invalid Message Route (MKT, TXN, or OTP).

INV-SOURCE

Invalid Source.

INV-MESSAGE-BODY

The invalid message body, Maximum length is 4000 characters.

INV-TITLE

The title is Mandatory for type RMC and CTA.

INV-CATEGORY

The category is Mandatory for type RMC and CTA.

INV-ACTION-CONTENT

Action content is Mandatory in Actions.

INV-ACTION-TYPE

Invalid Action Type in Actions, the supported type is 1, 2, 3, 4, or 5.

INV-ACTION-RANK

Invalid Action Rank in Actions, the supported type is 0, 1, 2, or 3.

INV-ACTION-TO

Action To is mandatory in Actions for types 1, 2, 4, or 5.

INV-DEEP-LINKS

Deep link is mandatory in Actions for type 3.

INV-MEDIA-TYPE

Invalid Media Type in Rich Media, the supported type is 1 or 2.

INV-MEDIA-URL

Invalid Media URL in Rich Media.

INV-MEDIA-DISPLAY-RATIO

Invalid Display Ratio in Rich Media, Supported values is normal or tall.

CAPABILITY-CHECK-ERROR

Mobile Number failed to pass the SOIP Yulore capability check.

NO-CREDITS

Insufficient credits.

Callback Statuses

The following table provides information about the callback statuses response codes and description:

Code

Status

Description

0

DELIVRD

Message Delivered Successfully.

1

UNDELIV_UNSUPPORT_MSG_TYPE

Invalid Message Type, Only Supported type MKT, TXN, or OTP.

2

UNDELIV_MSG_PARSE_FAILED

Message failed to parse.

3

UNDELIV_UNSUPPORTED_SOURCE

Invalid Source.

4

BLOCKED

SMS Rejected as the number is blocked by the operator.

5

DELIVRD_TIMEOUT

Request timeout, but the message got Delivered.

6

OFFLINE

The number is not reachable.

7

UNDELIV

Failed due to network errors.

8

DELIVRD_REPETED

Message delivered Multiple times.

15

REJECTED

SMS Rejected as the number is blacklisted by the operator.

16

TIMEOUT

Problem with Handset/ Handset failed to acknowledge.

20

DELIVRD_NO_CALLBACK

Message Delivered without any callback.

21

UNDELIV_NO_CALLBACK

Message not delivered without any callback.


Did this page help you?