Send template messages

Queues an approved WhatsApp template message using the Meta-style payload format. Supports both a single recipient and bulk sending — up to 30,000 contacts in one request, processed asynchronously via a Redis-backed queue.

Endpoint

POST https://wa20.nuke.co.in/v6/api/whatsappTemplate/24/{{username}}/messages

Replace {{username}} in the URL with your account username.

Authentication

Required. Send a JWT in one of these ways:

Method	Example
Header	`Authorization: Bearer <jwt_token>`
Cookie	`auth_token=<jwt_token>`

The {{username}} in the URL must match the username inside your JWT. If they don't match, the request is rejected with 401 Route username does not match authenticated user.

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <jwt_token>`

Body Parameters

Parameter	Type	Required	Description
`messaging_product`	string	Yes	Must always be `"whatsapp"`.
`to`	string or array of strings	Yes	Recipient phone number(s) with country code. Pass a single string for a one-off send, or an array of up to 30,000 numbers to send the same template as a bulk campaign.
`type`	string	Yes	Must always be `"template"`.
`template`	object	Yes	Template definition.
`template.name`	string	Yes	Exact approved template name from your account.
`template.language.code`	string	Yes	Meta language code like `en_US`, or supported language input that can be normalized.
`template.components`	array	No	Required only when template needs variables, media header, or button parameters. Applied identically to every recipient in a bulk send.

Bulk sending: When to is an array, all recipients receive the same template.components (i.e. the same variables/media/buttons) — this endpoint does not support per-recipient personalized variables in a single call. For personalized bulk sends, call the endpoint once per recipient/variable-set.

Payload Examples

1. Simple template (single recipient)

{
  "messaging_product": "whatsapp",
  "to": "919912345678",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": {
      "code": "en_US"
    }
  }
}

2. Body variables (single recipient)

{
  "messaging_product": "whatsapp",
  "to": "919912345678",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Rahul" },
          { "type": "text", "text": "10234" }
        ]
      }
    ]
  }
}

3. Image header + body variable (single recipient)

{
  "messaging_product": "whatsapp",
  "to": "919912345678",
  "type": "template",
  "template": {
    "name": "promo_banner",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/banner.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Rahul" }
        ]
      }
    ]
  }
}

4. Dynamic URL button (single recipient)

{
  "messaging_product": "whatsapp",
  "to": "919912345678",
  "type": "template",
  "template": {
    "name": "order_tracking",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Rahul" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          { "type": "text", "text": "10234" }
        ]
      }
    ]
  }
}

5. Bulk send (up to 30,000 contacts)

{
  "messaging_product": "whatsapp",
  "to": [
    "919912345678",
    "919912345679",
    "919912345680"
  ],
  "type": "template",
  "template": {
    "name": "modiinternational",
    "language": {
      "code": "en_US"
    }
  }
}

All numbers in the to array receive the same template + components. For up to 30,000 recipients, the request is accepted immediately and the recipients are pushed onto a Redis-backed queue for processing in the background — you don't need to wait for each individual message to send.

Example Response — 201 Created

Single recipient

On success, the template message is queued internally.

{
  "success": true,
  "message": "Template message queued successfully",
  "request_id": "a1b2c3d4e5f6",
  "username": "demo_user",
  "template_name": "welcome_message",
  "category": "utility"
}

Bulk send

{
  "success": true,
  "message": "Template campaign queued successfully",
  "request_id": "a1b2c3d4e5f6",
  "username": "demo_user",
  "template_name": "modiinternational",
  "category": "utility",
  "contacts": 30000
}

Field	Description
`success`	Whether the request was accepted.
`message`	Human-readable confirmation.
`request_id`	Unique campaign/request ID — use this to fetch per-contact status via Get Contacts by Request ID.
`username`	Your account username.
`template_name`	Name of the template that was queued.
`category`	Template category (e.g. `utility`, `marketing`).
`contacts`	Total number of recipients queued — returned only for a bulk send.

Confirm exact response field names/shape for bulk sends against production output before publishing — the above reflects the same pattern used elsewhere (e.g. contacts count in the Voice Campaign response) but hasn't been pasted from an actual bulk response yet.

Error Responses

Status	Message	Reason
`400`	`Invalid Authorization token`	JWT missing/invalid.
`401`	`Route username does not match authenticated user`	Route username and JWT username mismatch.
`400`	`messaging_product must be whatsapp`	Invalid or missing `messaging_product`.
`400`	`to is required`	Recipient(s) missing.
`400`	`to array cannot exceed 30,000 contacts`	Bulk `to` array has more than 30,000 numbers.
`400`	`type must be template`	Type is not `template`.
`400`	`template must be an object`	Template payload missing/invalid.
`400`	`template.name is required`	Template name missing.
`400`	`template.language.code is required`	Template language missing/unrecognized.
`400`	`template.components must be an array`	Invalid components type.
`400`	`Recipient phone number is invalid`	Invalid number after cleanup.
`400`	`Recipient phone number must be between 8 and 20 digits`	Invalid number length.
`404`	`Template not found`	No matching template for this username.
`409`	`Template is pending Meta approval`	Template exists but not approved yet.
`409`	`Template was rejected by Meta`	Template was rejected.
`409`	`Template is not approved for sending`	Template status is not sendable.
`422`	`Template language does not match the approved template`	Language mismatch with stored approved template.
`422`	`Template body parameter count does not match the approved template`	Body placeholder count mismatch.
`422`	`Template header parameter count does not match the approved template`	Header placeholder count mismatch.
`500`	`Failed to queue template message`	Internal queue/database failure.

Add the exact error message for exceeding the 30,000-contact limit once confirmed — placeholder used above.

Notes

This endpoint validates the template against locally stored approved template records before queueing.
Language inputs such as en_US, numeric language IDs, or language names may be normalized internally.
The message is queued internally; this endpoint does not directly return provider wamid on success.
Body and header variable counts are strictly checked against the approved template structure.
Bulk sending: pass an array in to to send the same template to up to 30,000 contacts in a single request. Recipients are queued via Redis and processed in the background — use the returned request_id with Get Contacts by Request ID to track per-contact status afterward.