# Templates, broadcasts, invitations and numbers in two steps

> Submit a WhatsApp template to Meta, send it to a group of contacts, invite a teammate or ask for a phone number from the REST API or the MCP server, always with a preview and a confirmation.

Source: https://docs.watsi.ai/en/guides/two-step-actions

Four actions reach someone outside your integration: **Meta** (submitting a template for review), **your customers** (sending a template to a group of contacts), **a new person** (inviting them to your workspace) or **the watsi team** (asking for a phone number). That is why none of them happens in a single call:

1. The `prepare_*` call **does nothing**: it checks what you asked for and answers a `preview` and a `confirmToken`.
2. Show the preview to the person. Once they confirm, redeem the token: on MCP with `confirm_action`, on REST at that action's `…/confirm` route.

So a single call, even one made by a model misled by some text, never messages anyone.

## The four actions

| Action                                           | Prepare (MCP and REST)                                                                  | Confirm on REST                                        | Scope             |
| ------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------- |
| Submit a template for Meta review                | `prepare_message_template_submission` · `POST /v1/actions/templates/submit/prepare`     | `POST /v1/actions/templates/submit/confirm`            | `templates:write` |
| Send an approved template to a group of contacts | `prepare_template_broadcast` · `POST /v1/actions/broadcasts/prepare`                    | `POST /v1/actions/broadcasts/confirm`                  | `broadcast:write` |
| Invite a teammate                                | `prepare_member_invite` · `POST /v1/actions/team/invites/prepare`                       | `POST /v1/actions/team/invites/confirm`                | `members:write`   |
| Ask for a phone number                           | `prepare_phone_number_request` · `POST /v1/actions/voice/phone-number-requests/prepare` | `POST /v1/actions/voice/phone-number-requests/confirm` | `agents:write`    |

Stopping a broadcast is direct: `cancel_template_broadcast` (`POST /v1/actions/broadcasts/cancel`, `broadcast:write`) prevents the messages that have not gone out yet; delivered ones cannot be recalled.

Write scopes are opt-in: you tick them when you create the key in **Settings › Developer** or on the OAuth consent screen. On top of the scope, the person needs their role's permission: inviting (`team:invite`), sending campaigns (`campaign:send`) or configuring the agent (`agent:config:write`) to ask for a number. Asking for a number also requires phone calling to be enabled for the workspace; otherwise the preview answers `PHONE_CALLING_NOT_ENABLED` (403).

## The token

The `confirmToken` lasts **10 minutes**, can only be redeemed by **the same person** in **the same workspace**, and carries what will run: the confirmation cannot change it. It is refused when:

- it expired (`ACTION_CONFIRMATION_EXPIRED`);
- it belongs to another person or workspace, or was altered (`ACTION_CONFIRMATION_INVALID`);
- what the preview showed changed (`ACTION_CONFIRMATION_STALE`): a template with that name now exists, the broadcast filter no longer selects exactly the same contacts, the person is already a member or invited, or a number request is already open.

The last case is also what makes a token **single-use**: the action itself changes what the preview showed. For a broadcast, redeeming the same token twice resolves the same campaign (`started: false`) and sends nothing twice.

## Per-action details

- **Templates.** The check is the template editor's own: name, variables, lengths, buttons and samples. The preview says which WhatsApp number the template is created on; a template exists only on that number. Meta assigns the final category, and an approved template can be edited only once per 24 h, so a wording change is a new template. Image, video or PDF headers are not available here.
- **Broadcasts.** The audience is a filter (stage, tag, message content, activity), never a list of ids, and more than **1,000 contacts** is refused. The template must be approved and carry exactly its variables (`{{nombre}}` becomes each contact's name). A workspace's first broadcast needs `optInAcknowledged: true`, after the person confirms their contacts agreed to receive marketing messages. The preview says how many contacts are inside the 24 h window, how many have US numbers (Meta does not deliver marketing templates to them) and an estimated cost.
- **Invitations.** Only as `admin` or `member`. The invitation arrives by email and holds a seat until it is accepted or expires; `emailSent: false` means the invitation exists but the email did not go out.
- **Phone number.** Filing the request connects nothing: the watsi team provisions the number by hand, and a +52 Mexico number needs fiscal paperwork. One request is open at a time.

## Replying to a customer in a conversation

Writing to the customer of a conversation also takes two steps, with the `messages:write` scope and the role's `chat:reply` permission:

| Action                                      | Prepare (MCP and REST)                                                   | Confirm over REST                                 |
| ------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------- |
| Reply with free text                        | `conversation_reply` · `POST /v1/actions/conversations/reply`            | `POST /v1/actions/conversations/reply/confirm`    |
| Send an approved template                   | `conversation_send_template` · `POST /v1/actions/conversations/template` | `POST /v1/actions/conversations/template/confirm` |
| React to a message (or remove the reaction) | `conversation_react` · `POST /v1/actions/conversations/react`            | `POST /v1/actions/conversations/react/confirm`    |
| Forward a message to other conversations    | `conversation_forward` · `POST /v1/actions/conversations/forward`        | `POST /v1/actions/conversations/forward/confirm`  |

- **Free text** only inside the channel's window: 24 h since the customer's last message on WhatsApp, 7 days on Instagram and Messenger. Outside it the answer is `TEMPLATE_REQUIRED`, at prepare and also at confirm if the window closed while the person read the preview.
- **Template** on WhatsApp only: it must be approved **on the conversation's WhatsApp number** (each number has its own templates; one approved only on another number answers `TEMPLATE_NOT_FOUND` and says so) and `bodyParameters` must fill every `{{N}}`. The preview carries the text exactly as the customer will read it.
- The token carries the conversation and the text or the template with its values. If anything is said in the conversation before the confirm (the send itself included), the token is `ACTION_CONFIRMATION_STALE`.
- A conversation outside what the person sees in the inbox answers `CONVERSATION_NOT_FOUND`, the same as one in another workspace.
- **Reaction:** one of the inbox's quick emojis (👍 ❤️ 😂 😮 😢 🙏), or `""` to remove ours. WhatsApp sets its own rules (the 24 h window and a recent message).
- **Forward:** up to 10 conversations. If a single one is outside what the person sees, the whole forward is refused. Each target has its own window: a closed one comes back `skipped` and the rest are sent.

## Opening a conversation with a new number

`start_conversation` (`POST /v1/actions/conversations/start`, confirmed at `POST /v1/actions/conversations/start/confirm`) writes to **a person who may never have written to you**, with an approved WhatsApp template. It needs `broadcast:write`, the same scope as broadcasts, and the `chat:reply` permission.

- The recipient is a phone number or a contact's name. A name that matches several contacts, or none, is refused: ask for the number.
- The preview says which of the workspace's WhatsApp numbers sends and whether the contact is created. The template must be approved on that number. The token carries the person, that number, the template and its values; if the sending number changes, or the person writes or receives anything before the confirm, it is `ACTION_CONFIRMATION_STALE`.
- If the person already has a conversation, use `conversation_send_template` in it.

In the app's Asistente, these same actions are a card the person applies with one click.
