Send SMS with Unicode

POST Method

kaleyra.io enables you to send an SMS with Unicode characters using this API. To know more about Unicode characters, see Understanding SMS length.

Prerequisites

Before sending the SMS, you must configure the SMS channel 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.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
You must have an approved SenderID or a specific number to be used as SenderID.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to send SMS with Unicode

To send SMS with unicode use the <api_domain>/v1/<sid>/sms endpoint with the following request method:

Request Format

The following is the request format to send SMS with unicode:

curl -X POST "https:<api_domain>/v1/<sid>/sms" \
     -H "api-key:<api-key>" \
     -H "Content-Type:<content-type>" \
     -d "to=<to>" \
     -d "sender=<sender>" \
     -d "type=<type>" \
     -d "body=<body>" \
     -d "unicode=<unicode>"

Sample Request Format

The following is the sample request format to send SMS with unicode:

curl -X POST "https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/sms" \
     -H "api-key:Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3" \
     -H "Content-Type:application/json" \
     -d "to=+91XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "type=MKT" \
     -d "body=你好，世界" \
     -d "unicode=1"

URL Parameters and Headers

Following is the list of parameters and headers to send the outgoing message request:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	`HXAP16XXXXXX97IN`	Yes
`api-key`	String	API key generated from kaleyra.io account.	`Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3`	Yes
`content-type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`to`	String	Phone number of the end customer you want to send a message to.	`+91XXXXXXXXXX`	Yes (valid phone numbers only)
`sender`	String	Alphanumeric Sender ID displayed on recipient devices.	KLRHXA	Yes

Following is the list of attributes to be used in the payload to send the SMS with unicode:

Parameter	Data Type	Description	Example	Mandatory?
`type`	String	Route type. Note: This is not a mandatory field. For customers in the Indian region, the available SMS Types are OTP, Transactional (TNX), Transactional DND (TXND), and Marketing (MKT). For Europe, America, and Singapore regions, only OTP and Default (to be used for Marketing and Transactional) route types are available.	MKT	Yes
`body`	String	Body of the SMS. It is required.	"你好，世界"	Yes
`unicode`	Integer	Determines message encoding. Acceptable values are "AUTO", "0", or "1".	1	No

📘
Notes:

If you are sending 0 then the message should not have any unicode characters. If Unicode characters are there they will not be converted.

If you are sending 1 then the entire message will be considered as unicode and all characters will be converted. That is if there are 60 characters it will be doubled, and this can impact charges too.

If you are sending “AUTO“ then if the message contains any unicode characters, then the entire message will be converted to unicode and the message length will be doubled. Else message will be considered a normal message.

Success Response

The following success response is received when the JSON script has the correct syntax:

{
  "id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391",
  "sender": "KLRHXA",
  "type": "MKT",
  "body": "你好，世",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "unicode": 1,
  "data": [
    {
      "message_id": "648xxx2c-xxxx-xxxx-80c5-3c2xxxb391:1",
      "recipient": "+91XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Response

The following failure response is received when the JSON script has an incorrect syntax:

Exceeds Maximum Mobile Number Limit
You cannot pass more than 100 numbers in a single API call.

{
  "code": "E405",
  "message": "If Type is TXN then mobile numbers should not be more than 100.",
  "error": {
    "time": "If Type is TXN then mobile numbers should not be more than 100."
  }
}

SMS Error Codes, SMS Status and Status Trace Codes

Refer to the following links for Error Codes, Status and Status Trace Codes:

For information related to SMS error codes, see SMS Error Codes.
For information related to SMS status and status trace codes, see SMS Status and Status Trace Codes.

Updated 5 months ago