Skip to content
watsi

Use cases

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.

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

ActionPrepare (MCP and REST)Confirm on RESTScope
Submit a template for Meta reviewprepare_message_template_submission · POST /v1/actions/templates/submit/preparePOST /v1/actions/templates/submit/confirmtemplates:write
Send an approved template to a group of contactsprepare_template_broadcast · POST /v1/actions/broadcasts/preparePOST /v1/actions/broadcasts/confirmbroadcast:write
Invite a teammateprepare_member_invite · POST /v1/actions/team/invites/preparePOST /v1/actions/team/invites/confirmmembers:write
Ask for a phone numberprepare_phone_number_request · POST /v1/actions/voice/phone-number-requests/preparePOST /v1/actions/voice/phone-number-requests/confirmagents: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:

ActionPrepare (MCP and REST)Confirm over REST
Reply with free textconversation_reply · POST /v1/actions/conversations/replyPOST /v1/actions/conversations/reply/confirm
Send an approved templateconversation_send_template · POST /v1/actions/conversations/templatePOST /v1/actions/conversations/template/confirm
React to a message (or remove the reaction)conversation_react · POST /v1/actions/conversations/reactPOST /v1/actions/conversations/react/confirm
Forward a message to other conversationsconversation_forward · POST /v1/actions/conversations/forwardPOST /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.