---
updatedAt: 2026-02-25T09:43:37.000Z
agentTools:
  projectIndex: https://developers.kaleyra.io/llms.txt
---

# Send Interactive Order Status Message

POST Method

The **Send Interactive Order Status Message** API allows you to send an interactive order status message to WhatsApp users. You can create an interactive message using the `order_status` type to notify a customer about updates to their order.

## Prerequisites

1. Before you get started, [Create an API Key](https://developers.kaleyra.io/docs/generating-an-api-key). To view the API Key and the SID, see[ View API Key and SID](https://developers.kaleyra.io/docs/view-api-key-and-sid).<br />A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on Kaleyra platform.
2. To set up a WhatsApp account on Kaleyra platform, [Embedded Signup](https://developers.kaleyra.io/docs/embedded-signup).
3. An active WhatsApp for Business API plan that includes:
   * A WhatsApp business number.
   * An associated profile with the business number.
   * A WhatsApp verified and approved profile.
   * A WABA ID onboarded on Kaleyra WhatsApp API V2.

## Base URL

`https://<api_domain>/v2/<SID>`

## API Domain and Value

| api\_domain | Value             |
| :---------- | :---------------- |
| IN pod      | api.in.kaleyra.io |
| SG Pod      | api.ap.kaleyra.io |
| EU Pod      | api.eu.kaleyra.io |

## API request to send Interactive Order Status Message:

To send Interactive Order Status Message, use the `https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages` endpoint with the following request method:

## Request Format

The following is the request format to send Interactive Order Status Message:

```curl
curl -X POST \
  https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages \
  -H 'Content-Type: <content_type>' \
  -H 'api-key: <api-key>' \
  -H 'cache-control: no-cache' \
  -d  '{
    "messaging_object": {
        "messaging_product": "<messaging_product>",
        "recipient_type": "<recipient_type>",
        "to": "<to_number>",
        "type": "<type>",
        "interactive": {
            "type": "<type>",
            "body": {
                "text": "<text>"
            },
            "action": {
                "name": "<name>",
                "parameters": {
                    "reference_id": "<reference_id>",
                    "order": {
                        "status": "<status>",
                        "description": "<description>"
                    }
                }
            }
        }
    },
    "extra_info": {
        "ref": "<ref>",
        "ref1": "<ref1>",
        "ref2": "<ref2>",
        "wa_source": "<wa_source>"
    }
}'
```

## Sample Request Format

The following is the sample request format to send Interactive Order Status Message:

```curl
curl -X POST \
  https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/+91XXXXXXXXXX/messages \
  -H 'Content-Type: application/json'  \
  -H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
  -H 'cache-control: no-cache' \
  -d  '{
    "messaging_object": {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": "+91XXXXXXXXX",
        "type": "interactive",
        "interactive": {
            "type": "order_status",
            "body": {
                "text": "This is an update about your order"
            },
            "action": {
                "name": "review_order",
                "parameters": {
                    "reference_id": "123XXXXX",
                    "order": {
                        "status": "processing | partially_shipped | shipped | completed | cancelled",
                        "description": "The shipment has been cancelled due to insufficient data"
                    }
                }
            }
        }
    },
    "extra_info": {
        "ref": "customer1",
        "ref1": "marketing",
        "ref2": "dictionary",
        "wa_source": "api"
    }
}'
```

## URL Parameters and Headers

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

<Table align={["left","left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Parameter / Headers
      </th>

      <th style={{ textAlign: "left" }}>
        Data Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Example
      </th>

      <th style={{ textAlign: "left" }}>
        Mandatory?
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `sid`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Account SID (Security Identifier).
      </td>

      <td style={{ textAlign: "left" }}>
        HXAP16XXXXXX97IN
      </td>

      <td style={{ textAlign: "left" }}>
        Yes
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `phone_number`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        WhatsApp Business Phone number through which WA Messages are sent.
      </td>

      <td style={{ textAlign: "left" }}>
        +91XXXXXXXXXX
      </td>

      <td style={{ textAlign: "left" }}>
        Yes  
        (valid phone numbers only)
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `Content-Type`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Indicates the format of the content the API will be processing.
      </td>

      <td style={{ textAlign: "left" }}>
        The only allowed value is application/json.
      </td>

      <td style={{ textAlign: "left" }}>
        Yes
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `api-key`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        API key generated from kaleyra platform account.
      </td>

      <td style={{ textAlign: "left" }}>
        AXXXXXXXXXXXXXXXXXXXX3
      </td>

      <td style={{ textAlign: "left" }}>
        Yes
      </td>
    </tr>
  </tbody>
</Table>

Following is the list of attributes to be used in the payload to send the outgoing message:

| Parameter          | Data Type   | Description                                                                                                                                                                     | Example                             | Mandatory? |
| :----------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- | :--------- |
| `messaging_object` | JSON object | Payload is supported only in JSON format. The messaging\_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message. | See the specific table for details. | Yes        |
| `extra_info`       | JSON object | This object will contain additional details that a user can send for certain functionality.                                                                                     | See the specific table for details. | No         |

The following table describes the different attributes used for the `messaging_object` object:

| Parameter           | Data Type   | Description                                                                                   | Example                                                        | Mandatory? |
| :------------------ | :---------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--------- |
| `messaging_product` | String      | Messaging service used for the request.                                                       | The only allowed value is whatsapp                             | Yes        |
| `recipient_type`    | String      | Currently, you can only send messages to individuals. Default is individual.                  | The only allowed value is individual                           | Yes        |
| `to_number`         | String      | WhatsApp end-user phone number. It should include country code prefix following E.164 format. | +91XXXXXXXXX                                                   | Yes        |
| `type`              | String      | The type of message you want to send. If omitted, it defaults to text.                        | The only allowed value for this type of message is interactive | No         |
| `interactive`       | JSON object | Interactive object contains interactive message details.                                      | See the specific table for details                             | Yes        |

The following table describes the different attributes used for the `interactive` object:

| Parameter | Data Type   | Description                                                              | Example                                                                           | Mandatory? |
| :-------- | :---------- | :----------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :--------- |
| `type`    | String      | The type of interactive element                                          | The only allowed value to send interactive order status message is `order_status` | Yes        |
| `body`    | JSON object | Body content.                                                            | See the specific table for details                                                | Yes        |
| `action`  | JSON object | An action object you want the user to perform after reading the message. | See the specific table for details                                                | Yes        |

The following table describes the different attributes used for the `body` object:

| Parameter | Data Type | Description                                                                                      | Example                             | Mandatory? |
| :-------- | :-------- | :----------------------------------------------------------------------------------------------- | :---------------------------------- | :--------- |
| `text`    | String    | The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters | This is an update about your order. | Yes        |

The following table describes the different attributes used for the `action` object:

| Parameter    | Data Type   | Description                          | Example                                  | Mandatory? |
| :----------- | :---------- | :----------------------------------- | :--------------------------------------- | :--------- |
| `name`       | String      | Defines the name of the order.       | The only allowed value is `review_order` | Yes        |
| `parameters` | JSON object | Defines the type of parameters used. | See the specific table for details       | Yes        |

The following table describes the different attributes used for the `parameters` object:

| Parameter      | Data Type   | Description                                                | Example                            | Mandatory? |
| :------------- | :---------- | :--------------------------------------------------------- | :--------------------------------- | :--------- |
| `reference_id` | String      | The ID sent by the business in the order\_details message. | 123XXXXX                           | Yes        |
| `order`        | JSON object | Defines the order status related information.              | See the specific table for details | Yes        |

The following table describes the different attributes used for the `order` object:

| Parameter     | Data Type | Description                                                                                                             | Example                                                  | Mandatory? |
| :------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- | :--------- |
| `status`      | String    | Defines the new order status. Supported statuses are processing, partially\_shipped, shipped, completed, and cancelled. | cancelled                                                | Yes        |
| `description` | string    | Defines the text for sharing status related information. The Maximum character limit is set to 120 characters.          | The shipment has been cancelled due to insufficient data | No         |

The following table describes the different attributes used for the `extra_info` JSON object:

<Table align={["left","left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Parameter
      </th>

      <th style={{ textAlign: "left" }}>
        Data Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Example
      </th>

      <th style={{ textAlign: "left" }}>
        Mandatory?
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        `ref`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
        Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.
      </td>

      <td style={{ textAlign: "left" }}>
        customer1
      </td>

      <td style={{ textAlign: "left" }}>
        No
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `ref1`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
        Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.
      </td>

      <td style={{ textAlign: "left" }}>
        marketing
      </td>

      <td style={{ textAlign: "left" }}>
        No
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `ref2`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more.
        Limit: The variable can be 255 characters long only. This parameter will be available in report and callback.
      </td>

      <td style={{ textAlign: "left" }}>
        dictionary
      </td>

      <td style={{ textAlign: "left" }}>
        No
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        `wa_source`
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Indicates the source from where the API has been triggered. Supported values for wa\_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage".
        Note: If the customer enters any value other than the above-specified values, the system will override it as the "API".
      </td>

      <td style={{ textAlign: "left" }}>
        api
      </td>

      <td style={{ textAlign: "left" }}>
        No
      </td>
    </tr>
  </tbody>
</Table>

> 📘 Note:
>
> In the case of ref, ref1, and ref2, if the length of the string exceeds 255 characters, it will be truncated.

## Sample Success Response

The following success message appears with the status 202 Accepted:

```json
202 Accepted 
{
"code":"WA202"
"message":"Request Accepted",
"data":{
  "message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}
```

## Sample Failure Response

The following are the failure responses:

```json
401 Unauthorized
{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "error": "Incorrect SID or API key."
    }
}
```

```json
401 Unauthorized phone number
{
    "code": "WA401",
    "message": "Phone number is not present or does not belong to the account.",
    "data": {},
    "error": {
        "phone_number": "Phone number is not present or does not belong to the account."
    }
}
```

```json
400 Incorrect payload
{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }
}
```

```json
500 Internal Server Error
{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}
```

```json
400 Low balance (applicable only to prepaid account)
{
    "code": "E110",
    "message": "Please check your balance, You have a low balance!",
    "data": {},
    "error": {
        "balance": "Please check your balance, You have a low balance!"
    }
}
```

```json
401 Unauthorised Account type
{
    "code": "WA-401",
    "message": "API is not available for given customer.Please contact support for more info",
    "data": {},
    "error": {
        "account": "API is not available for given customer.Please contact support for more info"
    }
}
```

```json
401 Unauthorized phone number version
{
    "code": "WA-401",
    "message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
    "data": {},
    "error": {
        "phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
    }
}
```