Send Your First SMS

POST Method

Description

SMS is a simple and cost-effective way to communicate with customers. By now, you would have configured the SMS channel in the Kaleyra Cloud. Now, let us use this API to send your first outbound SMS.

Base URL

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

To send your first SMS, follow the below steps:

1. Signup or Login to Kaleyra Cloud 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 Cloud.

2. API command to Send Your First SMS

Request Format

To send your first SMS, use the /messages endpoints.

curl -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -d "to=<TO_NUMBER>" \
     -d "sender=<SENDER_ID>" \
     -d "body=Hello! This is my first SMS." \
     -d "source=API" \
     -d "ref=<OPTIONAL_PARAMETER>" \
     -d "ref1=<OPTIONAL_PARAMETER1>" \
     -d "ref2=<OPTIONAL_PARAMETER2>"
Request Format-Indian Customers
curl -X POST "https://api.kaleyra.io/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -d "to=<TO_NUMBER>" \
     -d "sender=<SENDER_ID>" \
     -d "source=API" \
     -d "body=Hello! This is my first SMS." \
     -d "template_id=<TEMPLATE_ID>"
     -d "ref=<OPTIONAL_PARAMETER>" \
     -d "ref1=<OPTIONAL_PARAMETER1>" \
     -d "ref2=<OPTIONAL_PARAMETER2>"

šŸ“˜

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:

Parameter

Variable

Description

Example

Mandatory

<SID>

String

Account SID (Security Identifier)

HXXXXXXX071US

Yes

<TO_NUMBER>

Integer

Recipient's MSISDN

+1XXXXXXXXXX

Yes

<SENDER_ID>

String

Originator/Alphanumeric ID (default KLRHXA)

KLRHXA

Yes

<API_KEY>

String

API Key generated by Kaleyra Cloud

Ac4XXXXX21f

Yes

<TEMPLATE_ID>

Integer

Unique ID of the template (Only for Indian Customers)

2xxxxxxxxxxxx

Yes

<OPTIONAL_PARAMETER>

String/Integer

Include the contextual information in this parameter.
For Example: Name, Customer ID, and so on

Customer Name

No

<OPTIONAL_PARAMETER1>

String/Integer

Include the contextual information in this parameter.
For Example: Name, Customer ID, and so on

Company Name

No

<OPTIONAL_PARAMETER2>

String/Integer

Include the contextual information in this parameter.
For Example: Name, Customer ID, and so on

Designation

No

Optional Parameters

Add the required contextual information to your SMS using the Optional Parameters. You can include up to three parameters in the above SMS API call, and each can have a maximum of 50 characters.

šŸ“˜

For Example:

When you deliver a message to multiple customers, you can pass the Reference ID as optional parameters in the API call for further reference.

You can also include information such as:

  • Campaign Name
  • Client Name
  • Client ID
  • Product ID and so on

3. Response Format

This section provides you the success and failure JSON response format for different scenarios.

Success Response

{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "body": "Hello! This is my first SMS.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}
Success Response - Indian Customers
{
  "id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d",
  "sender": "KLRHXA",
  "type": "DEFAULT",
  "template_id": "2xxxxxxxxxxxx",
  "body": "Hello! This is my first SMS.",
  "createdDateTime": "2019-11-04 10:42:23+00:00",
  "totalCount": 1,
  "data": [
    {
      "message_id": "ee8aXXXX-XXXX-XXXX-XXXX-9b717XXXX30d:1",
      "recipient": "1XXXXXXXXXX"
    }
  ],
  "dlrurl": null,
  "error": {}
}

Failure Response

Exceeds Maximum Characters
The SMS length is exceeding 4000 characters. Keep the characters below the maximum limit and re-execute the command.

{
  "code": "E401",
  "message": "SMS length is exceeding 4000 characters.",
  "error": {
    "body": "SMS length is exceeding 4000 characters."
  }
}

šŸ“˜

Note:

In case of an error, ensure that the parameter values are correct in the above code. Refer to the Understand Error Codes page for detailed information.

Sample Request

curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "api-key: Ac4XXXXX21f" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "to=+1XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "body=Hello! This is my first SMS."
     -d "source=API" \
     -d "ref=Campaign name" \
     -d "ref1=Client Name" \
     -d "ref2=Product ID"
Sample Request - Indian Customers
curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "api-key: Ac4XXXXX21f" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "to=+1XXXXXXXXXX" \
     -d "sender=KLRHXA" \
     -d "body=Hello! This is my first SMS." \
     -d "source=API" \
     -d "ref=Campaign name" \
     -d "ref1=Client Name" \
     -d "ref2=Product ID" \
     -d "template_id=2xxxxxxxxxxxx"

Two-way SMS for Customer Engagement

Kaleyra's Two-Way SMS API is designed to offer you an easy and efficient way to communicate with your customers. It allows you to instantly send and receive messages through your choice of long or short-codes.

If you have purchased a two-way SMS number, you must pass the same number as a Sender ID in the above API call to initiate a two-way conversation with your customers.

Sample Request
curl -X POST "https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "api-key: Ac4XXXXX21f" \
     -d "to=+1XXXXXXXXXX" \
     -d "sender=+1XXXXXXXXXX" \
     -d "body=Hello! This is my first SMS."
     -d "template_id=2xxxxxxxxxxxx"




Ā© 2020-2021 Kaleyra Inc. All rights reserved

Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.

Updated 2 days ago



Send Your First SMS


POST Method

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.