> ## Documentation Index
> Fetch the complete documentation index at: https://flow.engineer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp agent

> Connect your product to WhatsApp, with buttons, templates and channel-aware replies.

Let people use your product from a WhatsApp conversation. Flow handles the conversation while
Flow Messaging—or your own provider—delivers the messages.

## Try it from the starter

```sh Terminal
npx @flow-engineer/flow link --channel whatsapp
npm start
```

Open the phone link, write first and ask “What's on the menu?” If the trial channel is not
available, `link` reports the available alternatives. Shared trial numbers are for testing,
not real customer data.

**Check it worked:** the agent replies on WhatsApp and the playground's **Debug** view shows
the tool call.

## Connect your own sender

Set `FLOW_MESSAGING_KEY` and `FLOW_MESSAGING_WHATSAPP_SENDER` for your own Flow Messaging sender.
The starter connects WhatsApp when that sender is set.

In a custom entry point, the channel is `fm.whatsapp()`:

```ts Channel configuration fragment
import { flowMessaging } from "@flow-engineer/flow/flow-messaging";

const fm = flowMessaging();
const channels = [fm.whatsapp()];
// Pass channels to buildAgent({ channels }), then await agent.resume().
// Start delivery with fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" }).
```

See [Flow Messaging setup](https://flow.engineer/docs/unified-messaging-api/guides/going-live.md) for sender provisioning, or use
`whatsapp(provider)` with [your own sending callbacks](https://flow.engineer/docs/conversations.md#choose-a-provider).

## What changes on WhatsApp

* Messages can use reply buttons, lists, photos, links and reactions. Carousels require provider support.
  More than three buttons go as a list with the agent's own label.
* Free-form replies depend on the channel's reply window. Outside it, business-initiated messages
  need an approved template; declare the templates your agent may use.
* The adapter maps button taps to `choice: { id, title }` so your tools can distinguish choices.

Flow Messaging sends exactly what it is given or refuses it; the adapter picks what WhatsApp
takes, and a refusal reaches the agent with what the channel does not take.

Framework 0.8.0 also preserves a refusal received over the event stream before the send's HTTP
response. The send rejects with the channel's reason; it does not wait until the delivery timeout.
[Reminders and nudges](https://flow.engineer/docs/nudges.md) explains templates, quiet hours and opt-outs.