> ## Documentation Index
> Fetch the complete documentation index at: https://convo.co.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /project/{project_id}/wa_template — Submit Template

> POST /project/{project_id}/wa_template — Submit a new WhatsApp Message Template for approval. Supports text, image, video, file, and carousel types.

Submit a new Message Template to WhatsApp for approval. Templates must be approved before you can use them in campaigns or messages. Approval typically takes a few minutes to a few hours depending on WhatsApp's review queue.

## Endpoint

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/wa_template
```

## Authentication

Include your project API password in every request header:

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

**project\_id** `string` *required*

Your Convo project ID.

## Request Body

**label** `string` *required*

A human-readable label for the template. Used for display in the Convo dashboard. Does not affect submission to WhatsApp.

**name** `string` *required*

A unique identifier for this template. Must be lowercase, use underscores instead of spaces, and contain no special characters (e.g., `order_confirmation_v1`). This name is used when referencing the template in campaigns.

**category** `string` *required*

The template category. Accepted values:

* `TRANSACTIONAL` — Order updates, shipping notifications, account alerts
* `MARKETING` — Promotional messages, offers, announcements
* `OTP` — One-time passwords and verification codes

**type** `string` *required*

The media type of the template. Accepted values:

* `TEXT` — Text-only body
* `IMAGE` — Includes an image header
* `VIDEO` — Includes a video header
* `FILE` — Includes a document/file header
* `LOCATION` — Includes a location share
* `CAROUSEL` — Carousel of cards (each with image, body, and buttons)
* `ORDER_DETAILS` — Structured order summary

**language** `string` *required*

Full language name for the template locale. Examples: `"English"`, `"Hindi"`, `"Spanish"`, `"French"`, `"Arabic"`.

**text** `string` *required*

The message body text. Use double-brace placeholders — `{{1}}`, `{{2}}`, etc. — for dynamic values. Placeholders must be numbered sequentially starting from `{{1}}`.

**Example:** `"Hi {{1}}, your order {{2}} has been shipped!"`

**sample\_text** `string` *required*

The same body text with placeholder values filled in with realistic sample data. WhatsApp reviewers use this to evaluate your template. Providing clear, realistic samples speeds up approval.

**Example:** `"Hi Priya, your order #ORD-4521 has been shipped!"`

**message\_action\_type** `string`

The type of interactive buttons to attach. Omit this field if you do not need buttons. Accepted values:

* `CTA` — Call-to-action buttons (phone number or URL). Maximum 2 buttons.
* `QuickReplies` — Quick reply buttons. Maximum 3 buttons.
* `All` — A mix of both CTA and quick reply buttons.

**call\_to\_action** `array`

Required when `message_action_type` is `CTA`. An array of up to 2 CTA button objects. Each object has the following fields:

| Field | Type | Description |
| - | - | - |
| `type` | string | `"Phone Number"` or `"URL"` |
| `button_title` | string | Label displayed on the button |
| `button_value` | string | Phone number (e.g., `"+919876543210"`) or URL (e.g., `"https://example.com/track/{{1}}"`) |

**quick\_replies** `array`

Required when `message_action_type` is `QuickReplies`. An array of up to 3 strings, each being the label for a quick reply button.

**Example:** `["Yes, confirm", "No, cancel", "Talk to support"]`

**header\_text** `string`

Optional text to display above the message body as a header. Only applicable for `TEXT` type templates with a text header variant.

**footer\_text** `string`

Optional text to display below the message body as a footer. Footers appear in a smaller, muted style.

**isClickTrackingEnabled** `boolean` (default: false)

When `true`, Convo tracks clicks on URL buttons in this template. Requires at least one `URL` type CTA button.

## Request Examples

**Plain Text**

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/wa_template" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Shipping Update",
    "name": "shipping_update_v1",
    "category": "TRANSACTIONAL",
    "type": "TEXT",
    "language": "English",
    "text": "Hi {{1}}, your order {{2}} has been shipped and will arrive by {{3}}.",
    "sample_text": "Hi Priya, your order #ORD-4521 has been shipped and will arrive by Dec 10.",
    "footer_text": "Reply STOP to unsubscribe"
  }'
```

**CTA Buttons**

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/wa_template" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Track My Order",
    "name": "track_order_cta_v1",
    "category": "TRANSACTIONAL",
    "type": "TEXT",
    "language": "English",
    "text": "Hi {{1}}, your order {{2}} is on its way! Track it in real time using the link below.",
    "sample_text": "Hi Priya, your order #ORD-4521 is on its way! Track it in real time using the link below.",
    "footer_text": "Convo Logistics",
    "message_action_type": "CTA",
    "call_to_action": [
      {
        "type": "URL",
        "button_title": "Track Order",
        "button_value": "https://example.com/track/{{1}}"
      },
      {
        "type": "Phone Number",
        "button_title": "Call Support",
        "button_value": "+919876543210"
      }
    ],
    "isClickTrackingEnabled": true
  }'
```

**Quick Replies**

```bash theme={null}
curl -X POST "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/wa_template" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Appointment Reminder",
    "name": "appointment_reminder_v1",
    "category": "TRANSACTIONAL",
    "type": "TEXT",
    "language": "English",
    "text": "Hi {{1}}, you have an appointment scheduled for {{2}} at {{3}}. Can you confirm your attendance?",
    "sample_text": "Hi Rahul, you have an appointment scheduled for Dec 12 at 3:00 PM. Can you confirm your attendance?",
    "message_action_type": "QuickReplies",
    "quick_replies": [
      "Yes, I will attend",
      "No, please cancel",
      "Reschedule"
    ]
  }'
```

## Response

A successful request returns `200 OK` with the created template object.

```json theme={null}
{
  "_id": "64a1f3bc9e4a2b001c3d7f12",
  "name": "shipping_update_v1",
  "label": "Shipping Update",
  "status": "PENDING",
  "category": "TRANSACTIONAL",
  "type": "TEXT",
  "language": "English",
  "text": "Hi {{1}}, your order {{2}} has been shipped and will arrive by {{3}}.",
  "sample_text": "Hi Priya, your order #ORD-4521 has been shipped and will arrive by Dec 10.",
  "total_parameters": 3,
  "footer_text": "Reply STOP to unsubscribe",
  "message_action_type": null,
  "call_to_action": [],
  "quick_replies": [],
  "isClickTrackingEnabled": false,
  "project_id": "YOUR_PROJECT_ID",
  "created_at": "2024-07-02T10:45:00.000Z",
  "updated_at": "2024-07-02T10:45:00.000Z"
}
```

The `status` field is always `PENDING` immediately after submission. Poll the [Get Template](https://convo.co.in/docs/api-reference/templates/get-template.md) endpoint or check your Convo dashboard to monitor approval.

## Error Responses

| Status | Description |
| - | - |
| `400 Bad Request` | A required field is missing, the template `name` already exists in your project, or a field value is invalid. The response body contains a `message` field with details. |
| `500 Internal Server Error` | An unexpected server-side error occurred. Retry with exponential backoff. |

```json theme={null}
{
  "error": "Bad Request",
  "message": "Template name 'shipping_update_v1' already exists in this project."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.