Messaging

Templates

A template is a message WhatsApp has approved in advance. It is the only way to start a conversation, or to write to a customer more than 24 hours after their last message.

From draft to approved

1. Create a draft with its name, language, category and components.
2. Submit it for review. Submission starts an operation; WhatsApp usually decides within minutes, sometimes hours. In the sandbox it takes seconds.
3. Send it once its status is approved. You are told of every change by the template.status_changed event.

1. Create

curl -X POST "https://api.shipmsg.com/v1/accounts/$SHIPMESSAGES_ACCOUNT_SID/templates" \
  -H "Authorization: Bearer $SHIPMESSAGES_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_ready",
    "language": "en_US",
    "category": "UTILITY",
    "parameterFormat": "POSITIONAL",
    "components": [
      {
        "type": "BODY",
        "text": "Hello {{1}}, your order {{2}} is ready for pickup.",
        "example": { "body_text": [["Ada", "A-1042"]] }
      }
    ]
  }'

The answer is the template (TM…) in status draft. If your account has more than one WhatsApp Business Account, add wabaSid to say which one owns it.

2. Submit

curl -X POST "https://api.shipmsg.com/v1/accounts/$SHIPMESSAGES_ACCOUNT_SID/templates/TM.../submit" \
  -H "Authorization: Bearer $SHIPMESSAGES_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

This returns an operation (OP…). Its status moves to submitted, then approved or rejected with a statusReason.

3. Send

{
  "from": "WA…",
  "to": "+15550000001",
  "type": "template",
  "template": {
    "name": "order_ready",
    "language": "en_US",
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Ada" },
        { "type": "text", "text": "A-1042" }
      ] }
    ]
  }
}

Sending a template that is not approved in that language answers TEMPLATE_NOT_APPROVED.

Categories

WhatsApp may re-categorise a template (for example utility to marketing); you receive template.category_changed.

Parameters

With parameterFormat: "POSITIONAL" the body uses {{1}}, {{2}} … and you pass parameters in that order. With NAMED it uses {{first_name}} and each parameter carries parameterName. Parameters can also be currencies and dates, and header, button and carousel components take their own parameter lists.

Quality, pauses and limits

• If customers block or report a template, WhatsApp lowers its quality and may pause it ( template.paused); sending a paused template answers TEMPLATE_PAUSED.
• A deleted template’s name cannot be reused for 30 days.
• In the sandbox, names starting with sandbox_reject_, sandbox_reject_once_ or sandbox_pause_ are rejected or paused on purpose; see the sandbox.