Deprecated - 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:
- 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.
- 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:
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. Supported values: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 |
CAMPAIGN_NAME | String | Name of the campaign. | New Campaign | False |
TO_NUMBER | String | Mobile number to which SMS is Sent. You can add multiple mobile numbers separated by “,“ (comma). Mobile numbers 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. | ["title"] | 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 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_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. | "actions": [ { "action_type": "ACTION_TYPE", "action_content": "ACTION_CONTENT", "action_rank": "ACTION_RANK", "action_to": "ACTION_TO" } ] | True for CTA |
CALLBACK_PROFILE_ID | String | Unique 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-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 | String | Display Ratio of the media. Valid values are normal and tall. For media_type 2 display_ratio supports only tall type. | 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. Maximum size is 28 characters. | Track Order | True |
ACTION_RANK | String | Priority for actionable data. Range is between 0 to 3. | 0 | 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. | "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):Parameter | Variable | Description | Example | Mandatory |
---|---|---|---|---|
DATE | String | The 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 “Hours:Minutes“ (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 variables 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 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:
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. |
Callback Parameters
The following table provides information about the callback parameter fields and descriptions:
Field Name | Descriptions |
---|---|
campaign_name | Name of the campaign. |
description | Details information about the status. |
from | Sender ID used to send messages. |
id | Unique ID for each request. |
kid | Unique Kid for each request same as ID. |
message_id | Unique message_id for each number mentioned in the request. |
recipient | Mobile number of the recipient. |
route | Type of route used in the request (MKT, TXN, or OTP). |
source | Source of the Request. |
status | Status of the message. |
status_trace | Status trace of the message. |
type | Type of request made. (TXT, CTA, or RMC) |
Updated 22 days ago