Starting a WhatsApp flow from your own system

An External Event trigger starts a WhatsApp flow when your own software posts an event to us — a delivery slot needing booking, a subscription about to renew, a repair finished. It is the escape hatch for everything Shopify's seven store events do not cover.

This is the one place in the builder where a developer is genuinely needed, and it is worth being precise about how little they have to do: they post one message to one web address. Everything after that — the questions, the branches, the messages — you build yourself.

What your developer needs

1. Your account API key, from Settings.
2. The address to post to: /api/external/event.
3. An event name they choose and you both agree on — for example delivery_slot_request.
4. The customer's phone number, plus any fields you want available in the flow.

That is the whole developer task. Any field they include arrives in the flow as {{event.field_name}}, so a payload carrying an order number and a customer name makes both usable in your messages.

The thing that surprises people: you need a template

A flow started by your own system lands on a chat the customer may never have written to, so the 24-hour window is shut. Meta only allows approved templates outside it.

Practically this means the first message of an external-event flow must be a template, and if that first message asks a question, the question step has to be sent as a template too — with quick-reply buttons whose titles match your flow's options exactly.

It also means the first message is charged. But there is a compensation worth designing around: the customer's tap opens the 24-hour window, so everything after it is free text at no cost.

A complete example: delivery slot booking

Button labels must match exactly

When a question is sent as a template, the template's quick-reply buttons are what the customer taps — so each option in your flow must match a button title character for character. "Morning" and "Morning slot" are different strings, and a mismatch means the tap resolves to nothing and the flow stalls.

Check this before publishing. It is the single most common reason an external-event flow appears to work and then goes quiet.

Sending data back

The Call External API step posts the customer's answer to your system. Two things worth knowing:

• Use GET to look something up and POST to send something. To do both — check availability, then book — chain a GET into a POST.
• Wire the failure branch. An endpoint that is down should produce a human handover, not silence.

What this unlocks that Shopify events do not

Use case	Why a store event won't do it
Delivery slot booking	Scheduling lives in your warehouse system
Subscription renewal reminder	No renewal event exists
Repair or service ready for collection	Not an ecommerce event at all
Appointment confirmation	Your booking system owns the date
Back-office approval decisions	Happens inside your own tools

The general rule: if the moment that should start the conversation happens inside software you control, this is the trigger for it.

What it still cannot do

An external event starts a flow now. It does not schedule one for later — there is no per-contact scheduled send, so "message this customer on the 14th" has to be your system posting the event on the 14th. That is usually a one-line change on their side and it keeps the timing where the data lives.

And no amount of API access moves Meta's rules. The first message still needs an approved template, the recipient still has to be reachable on WhatsApp, and marketing content still cannot be delivered to a US number. The API changes what starts a flow, not what a flow is allowed to send.

Testing it

Have your developer post one test event with your own phone number before you publish. It is the only way to exercise the path, and it proves three things at once: the key works, the event name matches, and the template renders with real values. See testing an automation safely.

What to hand your developer

The whole developer task fits on one page, and it helps to give it to them in this shape rather than asking them to work it out:

1. The endpoint: POST to /api/external/event.
2. The API key from your Settings, sent as the request's key header.
3. The event name you have agreed — a specific string, never blank.
4. The customer's phone number, in full international format.
5. Any fields the flow needs, which arrive as {{event.field_name}}.
6. When to fire it — the exact moment in their system.

That last point is the one that needs a conversation rather than a spec. "When the order is ready" means something precise inside their software and something vaguer to you, and the gap between the two is where these projects go wrong.

Designing for a cold chat

Because these flows land on a conversation the customer may never have started, three things follow that do not apply to customer-triggered flows:

Constraint	Consequence for your flow
The window is shut	First message must be an approved template
A question must reach them anyway	Send the question as a template, with quick-reply buttons
Button titles are fixed at approval	Flow options must match them character for character
The first message is charged	Make it earn a tap, so the rest is free

The fourth row is the design lever. Once the customer taps, the 24-hour window opens and everything after it is free text — so an external-event flow that asks rather than announces gets a day of unrestricted conversation for the price of one template.

Two patterns worth copying

1. Ask, save, send back. External event → template question with buttons → save the answer to a contact field → POST it to your system. This is delivery slots, appointment confirmations and preference collection, all the same shape.
2. Look up, then act. A GET call to read something — availability, a balance, a status — wired into a POST that submits the result. Chain the GET's success port into the POST.

In both, wire the failure branch to a human. An endpoint that is down should produce a handover and an honest message, not silence.

What this does not solve

It starts a flow now. It cannot schedule one for later, because there is no per-contact scheduled send — so "message this customer on the 14th" has to be your system posting the event on the 14th. That is usually a one-line change on their side, and it keeps the timing where the data actually lives, which is the better place for it anyway.

And API access does not change Meta's rules. The first message still needs an approved template, the recipient still has to be reachable on WhatsApp, and marketing content still cannot be delivered to a US number.

Keeping it maintainable

Agree the event name and the field names in writing, and treat them as a contract. A developer renaming a payload field is indistinguishable from a broken flow at your end — the variable simply resolves empty and the message sends with a gap in it, or fails outright.

Start with one event

Resist wiring three integrations at once. Pick the single event with the clearest value — usually the one your team currently handles by copying details into WhatsApp by hand — and get that working end to end before adding another. The second is far easier once the first has proved the plumbing.

Once the first event is live, the rest is repetition: a new event name, a new template, the same plumbing. The hard part is only ever the first one.

Start there, and add the second one only once the first is trusted.

The rules your API access does not change

It is worth being explicit that posting an event gives you a new way to start a flow, not permission to send anything you like.

• The first message still needs an approved template, because it lands on a chat outside the 24-hour customer service window. That window opens when a customer messages or calls you and resets each time, per Meta's sending messages documentation.
• It is charged. Meta bills per delivered template message; messages inside an open window are free, per its pricing documentation, which is why the first message earning a tap matters so much.
• Your messaging tier still applies. Each external event that reaches a cold chat counts against it — starting at 250 unique recipients per rolling 24 hours.
• Marketing content still cannot reach a US number.

None of that is a limitation of the trigger. It is the same set of rules every other flow lives under, and designing for them from the start is easier than discovering them after your system is already posting events.