WOML integrates with the WhatsApp Cloud API for message triggers, approved-template notifications, and messaging services.

Required configuration

Inbound messages require the Meta Phone Number ID, a verify token, and app secret. WOML exposes /callbacks/whatsapp, completes verification, and validates X-Hub-Signature-256 over the raw callback body.

Outbound proactive messages use an access token and approved template. Recipients are international digits without + or spaces. Approval templates must preserve the expected Approve and Reject button order.

Terminal

woml whatsapp doctor --phone-number-id <id> --callback-url <https-url>

WOML ignores delivery-status callbacks as triggers. Production callbacks require public HTTPS and deliberate reverse-proxy configuration.

Understand the two credential paths

Inbound callbacks use phone-number-id, a project-chosen verification token, and the Meta app secret used to validate callback signatures. Outbound messages use an access token and the Phone Number ID.

The Phone Number ID is Meta's numeric resource identity, not the human-readable telephone number.

Declare an inbound trigger

WOML

<whatsapp
  id="customerMessage"
  events="message"
  phone-number-id="123456789012345"
  verify-token="{{secrets.WHATSAPP_VERIFY_TOKEN}}"
  app-secret="{{secrets.WHATSAPP_APP_SECRET}}"
/>

Expose WOML's callback route through public HTTPS, configure that URL in Meta, and use the same verification value stored in WOML secrets. WOML validates the raw-body signature before creating a run.

Send an approved template

JavaScript

return services.whatsapp.send({
  accessToken: secrets.WHATSAPP_ACCESS_TOKEN,
  phoneNumberId: "123456789012345",
  conversationId: context.payload.conversationId,
  template: {
    name: "woml_reply_v1",
    language: "en_US",
    parameters: ["Your request was received"]
  }
}, { name: "whatsapp-reply" });

WOML v1 does not promise arbitrary proactive free-form messages. Use approved templates and preserve the expected button ordering for approval templates.

Run the doctor before production deployment, then test verification, a signed inbound message, and an outbound template separately.