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

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

POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/wa_template

Authentication

Include your project API password in every request header:

X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD

Path Parameters

string

required

Your Convo project ID.

Request Body

string

required

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

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.

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

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

string

required

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

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!"

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!"

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.

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}}"`)

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"]

string

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

string

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

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
CTA Buttons
Quick Replies

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"
  }'

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
  }'

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.

{
  "_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 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.

{
  "error": "Bad Request",
  "message": "Template name 'shipping_update_v1' already exists in this project."
}

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

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

Endpoint

Authentication

Path Parameters

Request Body

Request Examples

Response

Error Responses

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Examples

​Response

​Error Responses

Endpoint

Authentication

Path Parameters

Request Body

Request Examples

Response

Error Responses