Send a WhatsApp Template

Sends a pre-approved template to a WhatsApp recipient. Templates can be sent at any time, including outside Meta's 24-hour customer-service window — this is the right endpoint for proactive sends like order confirmations, appointment reminders, and re-engagement messages.

Which endpoint do I call?

POST to /v1/whatsapp/templates over HTTPS. The endpoint requires the whatsapp:send scope on your API key — same scope as free-form text sends.

POST /v1/whatsapp/templates

What does the request look like?

A minimal call needs an agent, a from-phone, a recipient, and the template name + language. Most real sends also include parameters to fill in placeholders.

curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "arabic_signup_message",
      "language": "ar"
    }
  }'

With body parameters:

curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-shipped" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "order_shipped",
      "language": "en",
      "parameters": {
        "customer_name": "Sara",
        "tracking_url":  "https://example.com/track/A123"
      }
    }
  }'

What goes in the request body?

Six fields total. The first four (agent_id, from, to, template.name/language) are required for any send. template.parameters is optional and only matters when your template has placeholders to fill in.

Field	Type	Required	Description
agent_id	UUID	Yes	The agent to send from.
from	E.164 string	Yes	The WhatsApp business number to send from.
to	E.164 string	Yes	Recipient's phone.
template.name	string	Yes	Meta-approved template name (e.g. order_shipped).
template.language	string	Yes	BCP-47 language tag (e.g. en, ar, en_US).
template.parameters	object	No	Flat name → value map for body placeholders.

How do template parameters work?

Templates can have placeholders in their body — e.g. a template body of Hello {{customer_name}}, your order is on the way: {{tracking_url}}. Pass values as a flat map:

"parameters": {
  "customer_name": "Sara",
  "tracking_url":  "https://example.com/track/A123"
}

In v1 only body-level parameters are supported. Header parameters (image, document, video) and footer parameters can land later as additive changes without breaking the existing contract.

What does a success response look like?

HTTP 202 Accepted:

{
  "id":                  "01c45011-d803-4eb0-a762-3228a4c392f3",
  "status":              "queued",
  "agent_id":            "12345678-1234-1234-1234-123456789012",
  "to":                  "+15551234567",
  "type":                "template",
  "platform_message_id": null,
  "created_at":          "2026-04-30T09:18:31Z",
  "sent_at":             null,
  "failed_at":           null
}

Use the returned id with Get Message Status to track delivery.

What can go wrong?

The standard error envelope. Template-specific cases:

code	HTTP	When
invalid_template_name	422	template.name is missing or blank
invalid_request_body	422	Required field missing — param names which
from_phone_not_found_for_agent	422	from doesn't match any active WhatsApp connection — available_phones lists what would work
agent_not_authorized	403	API key isn't allowed to use this agent

If the template name doesn't exist on the agent's WhatsApp Business Account, or isn't approved in the recipient's region, Mojeeb still returns 202 (we don't pre-validate against Meta). The send transitions to status: "failed" once Meta rejects delivery — check Get Message Status.

Common questions

How do I create a template?

Templates are created and approved through Meta's WhatsApp Business Manager, then become available to send. This is a one-time setup per template, separate from your Mojeeb integration. The Mojeeb dashboard surfaces your existing templates under the agent's WhatsApp connection.

What's the difference between language en and en_US?

BCP-47 language tags. Meta uses these to pick the right template translation. en is generic English; en_US is US English specifically. Use whatever language tag your template was approved with.

Can I omit parameters if my template has no placeholders?

Yes. Omit the parameters field entirely (or pass an empty object). Templates with no placeholders ignore parameters anyway.

Does the API validate parameters against the template's expected placeholders?

No, not at the API layer. If your template needs customer_name and you don't pass it, Meta rejects the send and you'll see status: "failed" on the status lookup. Always test new templates with at least one real send before depending on them in production.

Can I send the same template twice safely?

Yes — use Idempotency-Key. See Idempotency.