iris-whatsapp-adapter

Send and receive WhatsApp messages from InterSystems IRIS Interoperability productions,
through Meta’s official WhatsApp Cloud API.

It provides an outbound adapter and Business Operation to send messages, and an
inbound adapter and Business Service to receive them through Meta’s webhook, plus a
small demo production that echoes back whatever you send it.

Implements the InterSystems idea
DPI-I-882 — Introduce a WhatsApp adapter for IRIS Interoperability.

How it works

Your production ──▶ Operation.SendMessage ──▶ Adapter.Outbound ──▶ Meta Cloud API ──▶ phone
                                                                                        │
phone ──▶ Meta webhook ──▶ HTTPS ──▶ /whatsapp (API.Webhook) ──▶ Service.Webhook ──▶ your targets
                                     checks X-Hub-Signature-256

• Outbound: send a SendTextRequest or SendTemplateRequest to the operation; you get
  back a SendResponse with Meta’s message ID.
• Inbound: Meta posts each message to the /whatsapp/webhook endpoint. Requests without
  a valid signature from your Meta App Secret are rejected with 403. Valid messages become
  Message.Inbound requests sent to the targets you choose.

Requirements

• InterSystems IRIS or IRIS for Health with Interoperability, 2024.1 or later
  (tested on IRIS Community 2026.1)
• IPM (ZPM) package manager
• A Meta developer app with the WhatsApp use case and a phone number (Meta’s free test
  number works). See https://github.com/xJuan21/iris-whatsapp-adapter/blob/master/META-SETUP.md for the Meta side, step by step.
• Inbound only: a public HTTPS URL that reaches your IRIS web server (a reverse proxy or a
  tunnel such as Tailscale Funnel)

Install

In an Interoperability-enabled namespace:

zpm "install iris-whatsapp-adapter"

Or from a clone of this repository:

zpm "load /path/to/iris-whatsapp-adapter"

Installing creates only the outbound SSL configuration (WhatsApp) and prints the next
steps. It never creates the public webhook endpoint by itself (see step 4 below).

Configure

Run these in the namespace where you installed the package. Each command prints nothing
on success; secrets are stored as Interoperability Credentials, never in code.

1. Access token (from Meta, see https://github.com/xJuan21/iris-whatsapp-adapter/blob/master/META-SETUP.md)

Write $System.Status.GetErrorText(##class(WhatsAppMeta.Util.Setup).SetToken(""))

2. Phone Number ID: add a System Default Setting (Interoperability → Configure →
System Default Settings → New) so it survives recompiling the production:

3. Try sending. Start WhatsAppMeta.Production.Demo, then:

Do ##class(WhatsAppMeta.Util.Setup).SendHello("")

You should receive Meta’s hello_world template. Sending works now; steps 4–6 are only
needed to receive messages.

4. Webhook secrets: a verify token you invent, and your Meta App Secret:

Write $System.Status.GetErrorText(##class(WhatsAppMeta.Util.Setup).SetSecrets("",""))

5. Create the webhook endpoint. This creates an unauthenticated web application,
so it shows you exactly what it will change and asks before doing anything:

Write $System.Status.GetErrorText(##class(WhatsAppMeta.Util.Setup).CreateWebApp())

It creates the web application /whatsapp and a role, WhatsAppWebhook, whose resources
are looked up from your namespace’s own databases. Answer y to apply. To undo it, run
RemoveWebApp().

6. Connect Meta to the endpoint: register the webhook URL in Meta, then subscribe your
app to your WhatsApp Business Account:

Write $System.Status.GetErrorText(##class(WhatsAppMeta.Util.Setup).SubscribeApp(""))

Without this last step, Meta’s dashboard Test button works but real messages never
arrive. https://github.com/xJuan21/iris-whatsapp-adapter/blob/master/META-SETUP.md explains why.

Done. Message the number from your phone: the demo production replies Echo: <your text>.

Use it in your own production

Send: add WhatsAppMeta.Operation.SendMessage to your production and send it either
request:

Set Request = ##class(WhatsAppMeta.Message.SendTextRequest).%New()
Set Request.ToRecipient = "15551234567", Request.Body = "Your order has shipped"

Receive: add WhatsAppMeta.Service.Webhook with Pool Size 0 (web requests drive it),
set its adapter’s VerifyTokenCredentials / AppSecretCredentials, and point
TargetConfigNames at your process. It sends one Message.Inbound per message
(FromSender, ContactName, MessageType, Body, MessageId, SentAt).

Classes

Security

• Only the webhook should be public. Expose /whatsapp alone, never the whole web
  server; the Management Portal must not be reachable from the internet.
• Every POST must be signed by Meta with your App Secret; anything else gets 403
  before reaching your production. The handshake (GET) needs your verify token.
• The endpoint is unauthenticated because Meta can’t log in. It runs with the
  WhatsAppWebhook role only. That role needs read access to the database holding
  credential passwords and to %Ens_Credentials, so code running under /whatsapp could
  read every credential in the namespace. Only this package’s dispatch class runs there.
• If a granted resource also protects other databases, CreateWebApp() warns you before
  you agree.
• Secrets live in Interoperability Credentials. Never put them in code, files, or settings.

Tests

Offline unit tests cover the signature and verify-token checks and the outbound payloads:

zpm "test iris-whatsapp-adapter"

To run them from VS Code’s Testing panel instead, set the test root once per namespace:

Set Dir = "/durable/irissys/unittestroot/" Write ##class(%File).CreateDirectoryChain(Dir) Set ^UnitTestRoot = Dir

Troubleshooting

License and policies

MIT · Privacy policy · Terms

Not affiliated with Meta, WhatsApp, or InterSystems.