> ## 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. # Create and Send WhatsApp Template Messages in Convo > Learn how to create, submit for approval, and send WhatsApp Business Message Templates with dynamic parameters, media headers, and interactive buttons. WhatsApp requires you to use **pre-approved Message Templates** whenever you initiate a conversation with a user or message someone outside the 24-hour session window. Templates go through a three-step lifecycle: you **create** the template in Convo, **submit** it to Meta for review, and — once it reaches `APPROVED` status — **send** it to your contacts with dynamic parameter values substituted at runtime. Template names must be unique per project and **cannot be edited after approval**. If you need to change the content, delete the existing template and create a new one with a different name. *** ## Submitting a Template Send a `POST` request to create and queue a template for Meta's review. ```text theme={null} POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/wa_template ``` | Header | Value | | -------------------------- | ------------------- | | `X-API-WA-Project-API-Pwd` | `YOUR_API_PASSWORD` | | `Content-Type` | `application/json` | Use double-brace placeholders like `{{1}}`, `{{2}}` for dynamic values. The `sample_text` field shows Meta reviewers what realistic content looks like in those slots. ```json theme={null} { "label": "Shipping Update", "category": "TRANSACTIONAL", "type": "TEXT", "language": "English", "name": "shipping_update_v1", "text": "Your order {{1}} has shipped and will arrive in {{2}} days.", "sample_text": "Your order [#12345] has shipped and will arrive in [3] days." } ``` ### Key template fields | Field | Description | | ------------- | --------------------------------------------------- | | `label` | Human-readable display name inside Convo | | `category` | `TRANSACTIONAL`, `MARKETING`, or `OTP` | | `type` | `TEXT`, `IMAGE`, `VIDEO`, or `DOCUMENT` | | `language` | Full language name, e.g. `English`, `Hindi` | | `name` | Unique snake\_case identifier used when sending | | `text` | Template body with `{{n}}` placeholders | | `sample_text` | Sample body with placeholder values in `[brackets]` | *** ## Template with CTA Buttons Call-to-action buttons let recipients open a URL or dial a phone number directly from the message. Set `message_action_type` to `"CTA"` and supply a `call_to_action` array. ```json theme={null} { "label": "Order Update with CTA", "category": "TRANSACTIONAL", "type": "TEXT", "language": "English", "name": "order_cta_v1", "text": "Your order {{1}} is ready. Track it here:", "sample_text": "Your order [#12345] is ready. Track it here:", "message_action_type": "CTA", "call_to_action": [ { "type": "URL", "button_value": "https://track.example.com/{{1}}", "button_title": "Track Order" }, { "type": "Phone Number", "button_value": "918116856153", "button_title": "Call Support" } ] } ``` You can include up to **two CTA buttons** — one URL and one phone number. *** ## Quick Reply Templates Quick Reply buttons let recipients tap a pre-defined response, making it easy to collect structured feedback or route conversations. Set `message_action_type` to `"QuickReplies"` and list up to three reply strings. ```json theme={null} { "label": "Feedback Survey", "category": "MARKETING", "type": "TEXT", "language": "English", "name": "feedback_survey_v1", "text": "How was your experience with us today?", "sample_text": "How was your experience with us today?", "message_action_type": "QuickReplies", "quick_replies": ["Great!", "Average", "Needs Improvement"] } ``` *** ## Sending an Approved Template Once a template reaches `APPROVED` status, send it using the messages endpoint with `type: "template"`. Pass dynamic values as `parameters` inside the appropriate `components` array entry. ```text theme={null} POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/messages ``` ```json theme={null} { "to": "917089379345", "type": "template", "template": { "language": { "policy": "deterministic", "code": "en" }, "name": "shipping_update_v1", "components": [ { "type": "body", "parameters": [ {"type": "text", "text": "#12345"}, {"type": "text", "text": "3"} ] } ] } } ``` Parameters are positional — the first object maps to `{{1}}`, the second to `{{2}}`, and so on. *** ## Template with Image Header For templates with a `type` of `IMAGE`, include a `header` component that supplies the image URL at send time. ```json theme={null} { "to": "917089379345", "type": "template", "template": { "language": { "policy": "deterministic", "code": "en" }, "name": "promo_with_image", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/promo.jpg" } } ] }, { "type": "body", "parameters": [ {"type": "text", "text": "Ankit"} ] } ] } } ``` The same pattern applies to `VIDEO` and `DOCUMENT` headers — replace `"type": "image"` with `"type": "video"` or `"type": "document"` and update the nested object key accordingly. *** ## Carousel Templates Carousel templates display a horizontal scroll of up to **10 product cards**, each with its own image, body text, and buttons. This is ideal for showcasing a range of products or promotions in a single message. Each card is represented as a separate component with `type: "carousel_card"` and its own `card_index`. Supply header media and body parameters for each card independently. ```json theme={null} { "to": "917089379345", "type": "template", "template": { "language": { "policy": "deterministic", "code": "en" }, "name": "summer_carousel_v1", "components": [ { "type": "carousel", "cards": [ { "card_index": 0, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": {"link": "https://example.com/card1.jpg"} } ] }, { "type": "body", "parameters": [ {"type": "text", "text": "Red Sneakers"}, {"type": "text", "text": "₹1,299"} ] }, { "type": "button", "sub_type": "url", "index": 0, "parameters": [ {"type": "text", "text": "red-sneakers-42"} ] } ] }, { "card_index": 1, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": {"link": "https://example.com/card2.jpg"} } ] }, { "type": "body", "parameters": [ {"type": "text", "text": "Blue Loafers"}, {"type": "text", "text": "₹999"} ] }, { "type": "button", "sub_type": "url", "index": 0, "parameters": [ {"type": "text", "text": "blue-loafers-41"} ] } ] } ] } ] } } ``` *** ## Checking Template Status Poll the template status endpoint to find out whether Meta has approved or rejected a submitted template. ```text theme={null} GET https://connect.api-wa.co/project-apis/v1/project/{project_id}/wa_template/{wa_template_id} ``` ### Status values | Status | Meaning | | ---------- | -------------------------------------------------------- | | `PENDING` | Submitted and awaiting Meta review (usually 24–48 hours) | | `APPROVED` | Ready to send to contacts | | `REJECTED` | Meta did not approve the template; see `rejected_reason` | When a template is rejected, the response includes a `rejected_reason` field with a short explanation from Meta — for example, `"ABUSIVE_CONTENT"` or `"INVALID_FORMAT"`. Use this to fix and resubmit under a new name. ```json theme={null} { "id": "64f3a1b2c0e4d500123abc", "name": "shipping_update_v1", "status": "REJECTED", "rejected_reason": "PROMOTIONAL_CONTENT_IN_TRANSACTIONAL_TEMPLATE", "created_at": "2024-01-15T10:30:00Z" } ```