WhatsApp Channel

Norq compiles WhatsApp templates to WhatsApp Cloud API payloads. It supports text messages, interactive messages (with reply buttons), image messages, and WhatsApp Business template messages.

Pipeline: Markdown -> AST (parse tree) -> WhatsApp Cloud API payload JSON

Template files

  • whatsapp.md -- Markdown mode
  • whatsapp.json -- Native JSON mode (for flows, complex interactive messages)

Frontmatter

Standard mode (text/interactive messages)

---
enabled: true
---

Template mode (WhatsApp Business approved templates)

---
mode: "template"
template_name: "order_shipped_v2"
template_language: "en"
---
Field Required Description
enabled No true (default) or false.
mode No Set to "template" for WA Business template mode.
template_name Template mode The approved WA Business template name.
template_language Template mode Language code (e.g., "en", "es").

Directive compilation

Directive WhatsApp output
:::header Bold text (*header text*)
:::footer Footer text in interactive messages; ignored in text-only
:::action Reply buttons (max 3) in interactive mode; URL buttons in template mode
:::callout Body text with warning symbol prefix
:::hero Image URL extracted; triggers image message type
:::fields Bold key formatting (*Key:* Value)
:::media Ignored (hero/images handled separately)
:::columns Stacked as text lines
:::list Text lines
:::raw Ignored

Message type auto-detection

Norq automatically selects the WhatsApp message type based on content:

Content pattern Message type
Has :::action buttons Interactive message (buttons)
Has :::hero with image Image message
Template mode frontmatter Template message
Plain text only Text message

Example: Interactive message

Hey {{user.first_name}}, your order *#{{order.id}}* has shipped!
 
::: fields
Tracking: {{order.tracking_id}}
Delivery: {{order.delivery_date}}
:::
 
::: action
[Track Order]({{tracking_url}}){primary}
[Contact Support]({{support_url}}){secondary}
:::
 
::: footer
Order notification
:::

Example: Template mode

---
mode: "template"
template_name: "order_shipped_v2"
template_language: "en"
---
::: action
[Track Order]({{tracking_url}}){primary}
:::

In template mode, the body content comes from the approved WhatsApp template. Norq fills in the template parameters and button URLs.

WhatsApp Flows

WhatsApp Flows (built in Meta's Flow Builder -- see developers.facebook.com/docs/whatsapp/flows) are multi-screen interactive forms referenced from a template via a CTA button:

::: action
[Book Appointment](flow://{{flow_id}}){flow}
:::

The Flow definition itself is managed in Meta's Flow Builder, not in Norq. Norq only triggers the flow from a notification.

For complex flow triggers, use native JSON mode (whatsapp.json).

Best practices

  • WhatsApp reply buttons are limited to 3 per message
  • Button labels have a 20-character limit
  • Keep messages concise -- WhatsApp is a conversational channel
  • Use template mode for marketing/promotional messages (Meta requires pre-approval)
  • Use interactive mode for transactional messages with action buttons
  • Test with norq preview <name> --channel whatsapp to see the payload structure