Create and Send WhatsApp Template Messages in Convo

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.

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.

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

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

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

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

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

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

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

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.

{
  "id": "64f3a1b2c0e4d500123abc",
  "name": "shipping_update_v1",
  "status": "REJECTED",
  "rejected_reason": "PROMOTIONAL_CONTENT_IN_TRANSACTIONAL_TEMPLATE",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Started

Core Concepts

Guides

Create and Send WhatsApp Template Messages in Convo

Submitting a Template

Key template fields

Template with CTA Buttons

Quick Reply Templates

Sending an Approved Template

Template with Image Header

Carousel Templates

Checking Template Status

Status values

​Submitting a Template

​Key template fields

​Template with CTA Buttons

​Quick Reply Templates

​Sending an Approved Template

​Template with Image Header

​Carousel Templates

​Checking Template Status

​Status values

Submitting a Template

Key template fields

Template with CTA Buttons

Quick Reply Templates

Sending an Approved Template

Template with Image Header

Carousel Templates

Checking Template Status

Status values