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. This API feature is only for customers from India.

📘

Note:

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

Base URL

<https://api.kaleyra.io/v1/><SID>

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. 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.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 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 --location -g --request POST '<URL>/v1/<SID>/messages/soip' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-raw '{
    "source": "SOURCE",
    "type": "TYPE",
    "route": "ROUTE",
    "campaign_name": "CAMPAIGN NAME",
    "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 --location -g --request POST '<URL>/v1/<SID>/messages/soip' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-raw '{
            "to": "TO_NUMBER",
            "from": "FROM",
            "body": "BODY",
            "source": "SOURCE",
            "type": "TYPE",
            "route": "ROUTE",
            "campaign_name": "CAMPAIGN NAME",
            "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 --location -g --request POST '<URL>/v1/<SID>/messages/soip' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-raw '{
            "to": "TO_NUMBER",
            "from": "FROM",
            "body": "BODY",
            "source": "SOURCE",
            "type": "TYPE",
            "route": "ROUTE",
            "campaign_name": "CAMPAIGN_NAME",
            "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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier).HXXXXXXX071USTrue
CONTENT_TYPEStringThe format in which the data is sent.application/x-www-form-urlencodedTrue
API_KEYAlphanumericAPI key generated from Kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3True
SOURCEStringSelect the source type. If no value is passed or kept empty, the default value is API.APIFalse
TYPEStringType of message. Supported values:TXT, RMC, or CTA.TXTTrue
ROUTEStringRoute type. If no value is passed or for empty field, the default is MKT.
For example - MKT, TXN, or OTP.
MKTFalse
CAMPAIGN_NAMEStringName of the campaign.New CampaignFalse
TO_NUMBERStringMobile number to which SMS is Sent. You can add multiple mobile numbers separated by “,“ (comma).
Mobile numbers should contain country code with or without +.
+13236xxxxx7True
FROMStringSender ID assigned to the account from which the SMS will be sent over IP.TEST-NUMTrue
MESSAGE_BODYStringMessage contents that need to be sent.Message BodyTrue
TITLEArrayMandatory for RMC and CTA. It can have either one title or maximum up to four titles.["title"]True for RMC and CTA
CATEGORYStringEnter the category. Mandatory for RMC and CTA.CategoryTrue for RMC and CTA
SUB_CATEGORYStringDefine sub category which will be displayed in the message.Sub CategoryFalse
RICH_MEDIAJSON Array The rich Media holds single JSON object for adding images and videos in the message."rich_media": [
{
"media_type": "MEDIA_TYPE",
"url": "URL",
"display_ratio": "DISPLAY_RATIO",
"cover":"COVER"
}
]
True only for RMC
CORE_ENTITYStringThe Core Entity is mandatory in case of CTA.Core EntityTrue for CTA
ACTIONSJSON ArrayThe Action contains JSON object for adding actionable buttons."actions": [
{
"action_type": "ACTION_TYPE",
"action_content": "ACTION_CONTENT",
"action_rank": "ACTION_RANK",
"action_to": "ACTION_TO"
}
]
True for CTA
CALLBACK_PROFILE_IDStringUnique callback profile ID is set for each account for a callback. For more information related to callback profiles, see callback profiles page.SG_0xxxxxx8-2xxd-4xx3-bxxe-b6xxxxxxxxe4False
RMC Parameters and Variables

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

ParameterVariableDescriptionExampleMandatory
COVERStringCover Image URL which is exposed publicly for media type 2.1False
MEDIA_TYPENumericType of media needs to be sent in the message. For example:
1 - Image
2 - video
1True
URLStringMedia URL exposed for all the users.https://net-sms.s3.ap-south-1.amazonaws.com/2/dxxxxxb.pngTrue
DISPLAY_RATIOStringDisplay Ratio of the media. Valid values are normal and tall. For media_type 2 display_ratio supports only tall type.normalTrue
CTA Parameters and Variables Apart from the Parameters and Variables listed for basic Text Messages, use the following parameters and variables additionally for CTA:
ParameterVariableDescriptionExampleMandatory
ACTION_TYPENumericType 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.
1True
ACTION_CONTENTStringActionable content. Maximum size is 28 characters.Track OrderTrue
ACTION_RANKStringPriority for actionable data. Range is between 0 to 3.0 True
ACTION_TOStringMandatory 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.comTrue
DEEP_LINKSJSON ArrayMandatory for type 3 (Open App) contains array of JSON."deep_links": [
{
"action": "ACTION",
"packageName": "PACKAGE_NAME",
"className": "CLASS_NAME"
}
]
True
Action To Fields Parameters and Variables The following table displays the mandatory parameters and variables for type 2 (Add to Calendar):
ParameterVariableDescriptionExampleMandatory
DATEStringThe date on which the event needs to be created. Date format “YYYY-MM-DD”.2021-10-19True
TIMEStringTime on which the event needs to be created. Time format “Hours:Minutes“ (24 hour format).22:30True
TITLEStringTitle of the event.Title of the eventTrue
EVENTStringDescription of the eventDescription of the eventTrue
Deep links Fields Parameters and Variables The following table displays the mandatory parameters and variables for type 3 (Open App):
ParameterVariableDescriptionExampleMandatory
ACTIONStringAndroid Application intentandroid.intent.action.MAINTrue
PACKAGE_NAMEStringAndroid Application Package Namecom.flipkart.androidTrue
CLASS_NAME/URI_BASEStringAndroid Screen Class name or play store URLcom.flipkart.android.SplashActivityTrue

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 Text Message (TXT)
Basic successful response with raw data in JSON format to specific numbers on the Xiaomi mobile for TXT:

{
    "body": "This is Text Message",
    "callback_profile_id": "SG_axxxxxxd-2xx5-4xxe-bxxb-9exxxxxxxx844",
    "campaign_name": "New Campaign",
    "data": [
        {
            "message_id": "fxxxxxxf-1xx1-4xxd-8xx4-19xxxxxxxx4f:0",
            "recepient": "91xxxxxxxx39"
        }
    ],
    "from": "SNSOIP",
    "kid": "f8xxxx1f-1xx1-4xxd-8xx4-19xxxxxxxx4f",
    "route": "OTP",
    "type": "TXT"
}
Rich Media Message (RMC) Basic successful response with raw data in JSON format to specific numbers on the Xiaomi mobile for RMC:
{
    "actions": null,
    "body": "This is RMC Image Message",
    "callback_profile_id": "SG_a2xxxx6d-bxx5-4xxe-bxxb-98xxxxxxxx44",
    "campaign_name": "New Campaign",
    "data": [
        {
            "message_id": "85xxx8a-axx1-4xx4-9xx5-b2xxxxxxxxc1:0",
            "recepient": "91xxxxxxxx39"
        }
    ],
    "from": "SNSOIP",
    "kid": "8cxxxx8a-axx1-4xx4-9xx5-b2xxxxxxxxc1",
    "rich_media": [
        {
            "display_ratio": "normal",
            "media_type": 1,
            "url": "https://net-sms.s3.ap-south-1.axxxxws.com/d7xxxxxxxxxxxxxx28.jpg"
        }
    ],
    "route": "TXN",
    "type": "RMC"
}
Call To Action (CTA) Basic successful response with raw data in JSON format to specific numbers on the Xiaomi mobile.
{
    "actions": [
        {
            "action_content": "Copy Text",
            "action_rank": "0",
            "action_to": "Kaleyra-KLR",
            "action_type": 4
        },
        {
            "action_content": "Open Link",
            "action_rank": "1",
            "action_to": "https://www.kaleyra.com",
            "action_type": 1
        },
        {
            "action_content": "Add Event",
            "action_rank": "2",
            "action_to": {
                "date": "2022-02-20",
                "event": "Description of the event",
                "time": "14:30",
                "title": "Title of the event"
            },
            "action_type": 2
        },
        {
            "action_content": "Open App",
            "action_rank": "3",
            "action_type": 3,
            "deep_links": [
                {
                    "action": "android.intent.action.MAIN",
                    "className": "com.fxxxxxxt.android.SplashActivity",
                    "packageName": "com.fxxxxxxt.android"
                }
            ]
        }
    ],
    "body": "This is Call To Action Message",
    "callback_profile_id": "SG_a2xxxx6d-2xx5-4xxe-bxxb-99xxxxxxxx44",
    "campaign_name": "New Campaign",
    "data": [
        {
            "message_id": "d0xxxx21-7xxb-4xxc-axx7-01xxxxxxxx2d:0",
            "recepient": "91xxxxxxxx39"
        }
    ],
    "from": "SNSOIP",
    "kid": "d0xxxx21-7xxb-4xxc-axx7-01xxxxxxxx2d",
    "rich_media": null,
    "route": "MKT",
    "type": "CTA"
}

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 type 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 --location -g --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "source": "API",
    "type": "TXT",
    "route": "MKT",
    "campaign_name": "New Campaign",
    "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 --location -g --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw ' {
            "to": "13236xxxxx7, +13336xxxxx7",
            "from": "TEST-NUM",
            "body": "This is Test Message",
            "source": "API",
            "type": "RMC",
            "route": "TXN",
            "campaign_name": "New Campaign",
            "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 --location -g --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": "13236xxxxx7",
    "from": "TEST-NUM",
    "body": "Test message",
    "source": "API",
    "type": "RMC",
    "route": "TXN",
    "campaign_name": "New Campaign",
    "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 --location -g --request POST 'https://api.kaleyra.io/v1/HXXXXXXX071US/messages/soip' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": "13236xxxxx7",
    "from": "TEST-NUM",
    "body": "Test is test message",
    "source": "API",
    "type": "CTA",
    "route": "TXN",
    "campaign_name": "New Campaign",
    "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:

ErrorMessage
INV-NUMBERThe recipient's mobile number is invalid.
MOB-NOTALLOWEDWith the default SenderID (KLRHXA), you can only send messages to your team.
INV-MOB-PATTRNThe recipient's mobile number is invalid.
INV-SENDERThe sender is Mandatory.
INV-TYPEThe type is Mandatory.
INV-ROUTEInvalid Message Route (MKT, TXN, or OTP).
INV-SOURCEInvalid Source.
INV-MESSAGE-BODYThe invalid message body, Maximum length is 4000 characters.
INV-TITLEThe title is Mandatory for type RMC and CTA.
INV-CATEGORYThe category is Mandatory for type RMC and CTA.
INV-ACTION-CONTENTAction content is Mandatory in Actions.
INV-ACTION-TYPEInvalid Action Type in Actions, the supported type is 1, 2, 3, 4, or 5.
INV-ACTION-RANKInvalid Action Rank in Actions, the supported type is 0, 1, 2, or 3.
INV-ACTION-TOAction To is mandatory in Actions for types 1, 2, 4, or 5.
INV-DEEP-LINKSDeep link is mandatory in Actions for type 3.
INV-MEDIA-TYPEInvalid Media Type in Rich Media, the supported type is 1 or 2.
INV-MEDIA-URLInvalid Media URL in Rich Media.
INV-MEDIA-DISPLAY-RATIOInvalid Display Ratio in Rich Media, Supported values is normal or tall.
CAPABILITY-CHECK-ERRORMobile Number failed to pass the SOIP Yulore capability check.
NO-CREDITSInsufficient credits.

Callback Statuses

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

CodeStatusDescription
0DELIVRDMessage Delivered Successfully.
1UNDELIV_UNSUPPORT_MSG_TYPEInvalid Message Type, Only Supported type MKT, TXN, or OTP.
2UNDELIV_MSG_PARSE_FAILEDMessage failed to parse.
3UNDELIV_UNSUPPORTED_SOURCEInvalid Source.
4BLOCKEDSMS Rejected as the number is blocked by the operator.
5DELIVRD_TIMEOUTRequest timeout, but the message got Delivered.
6OFFLINEThe number is not reachable.
7UNDELIVFailed due to network errors.
8DELIVRD_REPETEDMessage delivered Multiple times.
15REJECTEDSMS Rejected as the number is blacklisted by the operator.
16TIMEOUTProblem with Handset/ Handset failed to acknowledge.
20DELIVRD_NO_CALLBACKMessage Delivered without any callback.
21UNDELIV_NO_CALLBACKMessage not delivered without any callback.

Callback Parameters

The following table provides information about the callback parameter fields and descriptions:

Field NameDescriptions
campaign_nameName of the campaign.
descriptionDetails information about the status.
fromSender ID used to send messages.
idUnique ID for each request.
kidUnique Kid for each request same as ID.
message_idUnique message_id for each number mentioned in the request.
recipientMobile number of the recipient.
routeType of route used in the request (MKT, TXN, or OTP).
sourceSource of the Request.
statusStatus of the message.
status_traceStatus trace of the message.
typeType of request made. (TXT, CTA, or RMC)