> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/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

<ParamField path="project_id" type="string" required>
  Your Convo project ID.
</ParamField>

## Request Body

<ParamField body="label" type="string" required>
  A human-readable label for the template. Used for display in the Convo dashboard. Does not affect submission to WhatsApp.
</ParamField>

<ParamField body="name" type="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.
</ParamField>

<ParamField body="category" type="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
</ParamField>

<ParamField body="type" 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
</ParamField>

<ParamField body="language" type="string" required>
  Full language name for the template locale. Examples: `"English"`, `"Hindi"`, `"Spanish"`, `"French"`, `"Arabic"`.
</ParamField>

<ParamField body="text" type="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!"`
</ParamField>

<ParamField body="sample_text" type="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!"`
</ParamField>

<ParamField body="message_action_type" 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.
</ParamField>

<ParamField body="call_to_action" type="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}}"`) |
</ParamField>

<ParamField body="quick_replies" type="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"]`
</ParamField>

<ParamField body="header_text" type="string">
  Optional text to display above the message body as a header. Only applicable for `TEXT` type templates with a text header variant.
</ParamField>

<ParamField body="footer_text" type="string">
  Optional text to display below the message body as a footer. Footers appear in a smaller, muted style.
</ParamField>

<ParamField body="isClickTrackingEnabled" default="false" type="boolean">
  When `true`, Convo tracks clicks on URL buttons in this template. Requires at least one `URL` type CTA button.
</ParamField>

## Request Examples

<Tabs>
  <Tab title="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"
      }'
    ```
  </Tab>

  <Tab title="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
      }'
    ```
  </Tab>

  <Tab title="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"
        ]
      }'
    ```
  </Tab>
</Tabs>

## 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](/api-reference/templates/get-template) 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."
}
```