> For the complete documentation index, see [llms.txt](https://docs.quickreply.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quickreply.ai/developer/apis/sms-send-template-api.md).

# SMS Send Template API

Send approved SMS template messages through the External API.

***

### Endpoint

<mark style="color:green;">`POST`</mark>  /api/v4/external/template-message/sms/send

> **Base URL:**
>
> ```
> <https://app.quickreply.ai>
> ```

***

### Authentication

This API uses the **External Secret Key** authentication mechanism.

Include the following headers in every request:

| Header         | Description        |                                                                                                                                                                                   |
| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-client-id`  | Company ID         | Click the **profile/account name** in the bottom-left corner of the QuickReply dashboard. In the menu that opens, the **Company ID** is displayed directly below the company name |
| `x-secret-key` | Company Secret Key | You can find client-id of your account in [Settings > Developers > API credentials](https://app.quickreply.ai/v2/settings/dev/api-credentials)                                    |
| `Content-Type` | `application/json` |                                                                                                                                                                                   |

***

### Request Body

| Field                                                         | Type     | Description                                                                                                                                                         |
| ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`<mark style="color:red;">\*</mark>                        | `string` | Recipient phone number in E.164 format (e.g. `+919800000000`)                                                                                                       |
| `templateId`<mark style="color:red;">\*</mark>                | `string` | <p>You can find the template id by clicking on the 3 dots at the right of template block and clicking "Copy Template Id"<br><br>ID of the approved SMS template</p> |
| `templateParams.bodyParams`<mark style="color:red;">\*</mark> | `array`  | Array of template parameter values. The number of parameters **must exactly match** the template's `paramLength`.                                                   |

> **Note**
>
> SMS templates can have:
>
> * No parameters (`paramLength: 0`)
> * One parameter
> * Multiple parameters
>
> Supply parameter values in the same order as the template placeholders (`{{1}}`, `{{2}}`, ...).

***

## Examples

### 1. Static Template (No Parameters)

Example template:

```
Your order has shipped.
```

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": []
    }
  }'
```

***

### 2. Single Parameter Template

Example template:

```
Hello {{1}}!
```

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": [
        {
          "value": "John"
        }
      ]
    }
  }'
```

***

### 3. Multiple Parameter Template

Example template:

```
Hi {{1}}, Your order  is {{2}}, balance to be paid  is {{3}} Rupees.
```

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": [
        {
          "value": "John"
        },
        {
          "value": "Black shirt "
        },
        {
          "value": "100"
        }
      ]
    }
  }'
```

***

## Parameter Examples

The following examples demonstrate supported parameter values.

### Numeric Parameter

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": [
        {
          "value": "482913"
        }
      ]
    }
  }'
```

***

### URL Parameter

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": [
        {
          "value": "<https://a.co/xyz>"
        }
      ]
    }
  }'
```

***

### Alphanumeric Parameter

```bash
curl -X POST "<https://app.quickreply.ai/api/v4/external/template-message/sms/send>" \
  -H "Content-Type: application/json" \
  -H "x-client-id: <your-client-id>" \
  -H "x-secret-key: <your-secret-key>" \
  -d '{
    "to": "+919800000000",
    "templateId": "<sms-template-id>",
    "templateParams": {
      "bodyParams": [
        {
          "value": "AB12CD"
        }
      ]
    }
  }'
```

***

## Success Response

**HTTP 200**

```json
{
  "conversationId": "6a45fffc7b5fb1610c57f923_conv",
  "messageId": "6a476f6c74d42f920ee404d3_msg",
  "messageStatus": "SENT"
}
```

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| `conversationId` | Conversation created for the SMS message |
| `messageId`      | Unique identifier of the message         |
| `messageStatus`  | Current status of the message            |

***

## Error Responses

| HTTP Status | Condition                                    | Message                                                 |
| ----------- | -------------------------------------------- | ------------------------------------------------------- |
| `400`       | Unknown channel                              | `Invalid channel. Supported: rcs, sms`                  |
| `400`       | Missing `to` or `templateId`                 | `to and templateId are required`                        |
| `400`       | Invalid phone number                         | `to must be a valid phone number`                       |
| `400`       | Invalid `templateParams`                     | `Invalid templateParams`                                |
| `400`       | Body parameter count does not match template | `Body parameter count mismatch: expected N, received M` |
| `400`       | Required parameters not provided             | `Body requires N parameter(s), but none were provided`  |
| `400`       | Template is not approved                     | `Template is not approved (status: ...)`                |

***

## Notes

* Only **approved** SMS templates can be used.
* The number of `bodyParams` supplied must exactly match the template's configured `paramLength`.
* Parameters must be provided in the same order as the template placeholders (`{{1}}`, `{{2}}`, `{{3}}`, ...).
* Phone numbers must be provided in **E.164** format (for example, `+919800000000`).