What this does

An order gets marked shipped. A booking is confirmed. An invoice is ready. Your system knows the instant it happens — and the customer usually finds out much later, if at all. This connects the two: your system tells us, we send the customer a WhatsApp message.

Nobody has to be at a screen for it. It runs at 2am, on a Saturday, on the fiftieth order of the day, and the customer gets the same message every time.

It has to be an approved template. When your business speaks first — the customer didn’t just message you — WhatsApp only allows a message Meta has already approved, word for word, with blanks for the details. So you set up one template per event (shipped, ready for pickup, paid), and each send fills in the blanks. That’s the one rule that shapes everything below.

What you need first

Four things, and only the last two take any effort.

WhatsApp connected to your agent — see Connect WhatsApp
A template per event, approved by Meta. Your approved templates are listed under Build → Channels → WhatsApp, in WhatsApp templates. Copy the name exactly as it appears there
Developer access for your organization — it is off until you ask for it (next section)
An API key with permission to send on a channel

One template, many orders A template like order_shipped is written once with a blank for the order number. You don’t need a template per order — you need one per kind of update.

Get a key

The key is what proves the request came from you. Two steps, and the first one is us saying yes.

1. Ask for developer access. Open Account → Developers. If the API isn’t open for your organization yet you’ll see Developer access with a short box asking what you’d like to build — write a line (“order status updates from our shop”) and send it. We review and reply by email, usually within a business day. Only an organization admin sees this form.

2. Create the key. Once approved, the same page becomes the developer center. Go to API keys → New key, name it after the system that will use it, and pick the agent it may send from.

This key sends messages and does nothing else — tick channel:send and leave the rest off.

The full key appears once. Afterwards only a hash of it is stored, so nobody — including us — can read it back.

Treat it like a password. Paste it into your store’s webhook settings or your automation tool, not into an email or a chat. If it leaks, open the key’s menu and hit Roll — you get a new secret and the old one stops working that second.

The three things to fill in

Whatever you’re using — your shop’s own webhook settings, a Make or Zapier step, or code your developer writes — it will ask for the same three things. Here they are.

1. The address. The method is POST. Swap YOUR_AGENT_ID for your agent’s id, which sits in the address bar when the agent is open, and is also listed on the developer center’s overview.

Address

https://server-150134556021.us-central1.run.app/api/v1/assistants/YOUR_AGENT_ID/whatsapp/send-template

2. Two header lines. The first carries your key — the word Bearer, a space, then the key itself.

Headers

Authorization: Bearer al_live_your_key_here
Content-Type: application/json

3. The message itself, as JSON. Who it goes to, which template, in which language, and the blanks to fill in.

Body

{
  "to": "+972501234567",
  "templateName": "order_shipped",
  "language": "he",
  "body": {
    "order_id": "4021"
  }
}

That’s the whole integration. There is no second call, nothing to poll, and nothing to install.

Filling in the details

Four fields, and three of them are where mistakes happen.

to — the customer’s number in international form: a +, the country code, then the number without its leading zero. 050-123-4567 becomes +972501234567
templateName — exactly as approved, character for character. Templates are usually named in lowercase with underscores, and a near-miss is simply not found
language — the language code the template was approved in, e.g. he or en. A template approved in Hebrew won’t answer to en
body — the blanks, by name. If your template says “your order {{order_id}} is on its way”, send { "order_id": "4021" }. Older templates that use numbered blanks take { "1": "4021" } instead

Templates with a button or an image Add buttons for a dynamic link on a button, and header for a picture or a PDF — the file has to sit at a public address, and it has to match what the template was approved with. The developer center’s API reference has the exact shape.

What comes back

The answer arrives in the same request, so your system knows immediately whether the customer got the message.

Sent

{ "status": "sent", "messageId": "wamid.HBgLM…", "threadId": "thread_9f2c" }

Handed to WhatsApp for delivery, and recorded on the customer’s conversation — so when they reply, your agent already has the context.

Skipped

{ "status": "skipped", "reason": "contact_opted_out", "threadId": null }

This customer asked to stop receiving messages. Nothing was sent, and nothing is wrong — don’t retry. Mark it handled and move on.

Failed

{ "status": "failed", "error": "…", "threadId": "thread_9f2c" }

WhatsApp refused it. The error text says why — almost always a template name that doesn’t exist, a language that doesn’t match, or blanks that don’t line up with the approved text.

A 403 means quota, not permission. Every template you send is a paid WhatsApp message and counts against your plan. If you get a 403 with a quota message, the sends stopped because the month’s allowance ran out — what WhatsApp actually costs is worth reading before you automate a high-volume event.

Wiring it to your system

You now have the three fields. The only question left is who fills them in when an order changes — and there are three honest answers.

Your system does it directly. If your shop or ERP lets you define a webhook per event with your own address, your own headers and a body you write yourself, you’re done — put the three fields in, map the order number and the customer’s phone into the body, and nothing else sits in the middle. This is the best version: one hop, nothing to pay for, nothing extra to keep alive.

An automation tool reshapes it first. Many systems send only their own fixed payload, with their own internal status codes, and won’t let you rewrite it. Then you need one step in between — Make, Zapier, n8n, whatever you already use: it catches the event, translates “status 7” into order_shipped, formats the phone number, and calls the address above. Use the tool’s plain “HTTP request” step and paste the same three fields into it.

Ask us for a dedicated address. If your system can’t be reshaped and you’d rather not run an automation tool, send us a real example of what it does send — one event is enough — and we can give you an address per event that accepts it as-is and picks the right template on our side.

How fast can you send? There is no rate limit on our side. The real ceiling is the messaging tier WhatsApp gives your number, which rises as you send more without people blocking you. Ask us where your number sits before you plan a big batch.

When it doesn’t work

The failures are few and they repeat. In order of likelihood:

401 or 403 straight away — the key is wrong, revoked, or missing the send permission; or the agent id isn’t one this key was allowed to use. Check the key’s row under API keys
“Template not found” — a typo in the name, or the language doesn’t match the one it was approved in. Copy both from the template list under Build → Channels
Sent, but the customer saw nothing — almost always the phone number: a leading zero left in, a local format, or a country code missing
Everything skipped — you’re messaging people who opted out. That’s the system working

The full reference — every field, every response, and a downloadable spec — lives in the app under Account → Developers → API reference. If you’re stuck on a specific send, send us the response text and the template name and we’ll tell you which of the four it is.

Was this helpful?