# Plantillas, difusiones, invitaciones y números en dos pasos

> Envía plantillas a Meta, mándalas a tus contactos, invita a un compañero o pide un número desde la API REST o el MCP, siempre con vista previa y confirmación.

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

Cuatro acciones llegan a alguien fuera de tu integración: **Meta** (enviar una plantilla a revisión), **tus clientes** (mandar una plantilla a un grupo de contactos), **una persona nueva** (invitarla a tu espacio de trabajo) o **el equipo de watsi** (pedir un número de teléfono). Por eso ninguna se hace en una sola llamada:

1. La llamada `prepare_*` **no hace nada**: revisa lo que pediste y responde una vista previa (`preview`) y un `confirmToken`.
2. Muéstrale la vista previa a la persona. Cuando confirme, canjea el token: en MCP con `confirm_action`, en REST en la ruta `…/confirm` de esa acción.

Así una sola llamada, aunque la haga un modelo engañado por un texto, nunca le escribe a nadie.

## Las cuatro acciones

| Acción                                                | Prepara (MCP y REST)                                                                    | Confirma por REST                                      | Alcance           |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------- |
| Enviar una plantilla a revisión de Meta               | `prepare_message_template_submission` · `POST /v1/actions/templates/submit/prepare`     | `POST /v1/actions/templates/submit/confirm`            | `templates:write` |
| Mandar una plantilla aprobada a un grupo de contactos | `prepare_template_broadcast` · `POST /v1/actions/broadcasts/prepare`                    | `POST /v1/actions/broadcasts/confirm`                  | `broadcast:write` |
| Invitar a un compañero                                | `prepare_member_invite` · `POST /v1/actions/team/invites/prepare`                       | `POST /v1/actions/team/invites/confirm`                | `members:write`   |
| Pedir un número de teléfono                           | `prepare_phone_number_request` · `POST /v1/actions/voice/phone-number-requests/prepare` | `POST /v1/actions/voice/phone-number-requests/confirm` | `agents:write`    |

Detener una difusión es directo: `cancel_template_broadcast` (`POST /v1/actions/broadcasts/cancel`, `broadcast:write`) evita los mensajes que aún no salieron; los ya entregados no se pueden recuperar.

Los alcances de escritura son opcionales: los marcas al crear la clave en **Configuración › Desarrollador** o en la pantalla de consentimiento de OAuth. Además del alcance, la persona necesita el permiso de su rol: invitar (`team:invite`), enviar campañas (`campaign:send`) o configurar el agente (`agent:config:write`) para pedir un número. Pedir un número también requiere que el espacio de trabajo tenga las llamadas telefónicas habilitadas; si no, la vista previa responde `PHONE_CALLING_NOT_ENABLED` (403).

## El token

El `confirmToken` dura **10 minutos**, sólo lo puede canjear **la misma persona** en **el mismo espacio de trabajo**, y lleva dentro lo que se va a ejecutar: la confirmación no puede cambiarlo. Se rechaza cuando:

- venció (`ACTION_CONFIRMATION_EXPIRED`);
- es de otra persona, de otro espacio de trabajo o está alterado (`ACTION_CONFIRMATION_INVALID`);
- cambió lo que mostraba la vista previa (`ACTION_CONFIRMATION_STALE`): ya hay una plantilla con ese nombre, el filtro de la difusión ya no selecciona exactamente los mismos contactos, la persona ya es miembro o tiene una invitación, o ya hay una solicitud de número abierta.

El último caso es también lo que hace que un token sirva **una sola vez**: la acción misma cambia lo que la vista previa mostraba. En una difusión, canjear dos veces el mismo token resuelve la misma campaña (`started: false`) y no envía nada dos veces.

## Detalles por acción

- **Plantillas.** La revisión es la misma que hace el editor de plantillas: el nombre, las variables, los largos, los botones y los ejemplos. La vista previa dice en qué número de WhatsApp se crea; una plantilla sólo existe en ese número. Meta asigna la categoría final, y una plantilla aprobada sólo se puede editar una vez cada 24 h, así que un cambio de redacción es una plantilla nueva. Por aquí no hay encabezado de imagen, video o PDF.
- **Difusiones.** El público se describe con un filtro (etapa, etiqueta, contenido de los mensajes, actividad), nunca con una lista de ids, y se rechaza por encima de **1,000 contactos**. La plantilla tiene que estar aprobada y llevar exactamente sus variables (`{{nombre}}` se vuelve el nombre de cada contacto). La primera difusión de un espacio de trabajo pide `optInAcknowledged: true`, después de que la persona confirme que sus contactos aceptaron recibir mensajes de marketing. La vista previa trae cuántos contactos están dentro de la ventana de 24 h, cuántos tienen número de EE. UU. (Meta no les entrega plantillas de marketing) y un costo estimado.
- **Invitaciones.** Sólo como `admin` o `member`. La invitación llega por correo y ocupa un asiento hasta que se acepta o vence; `emailSent: false` significa que la invitación existe pero el correo no salió.
- **Número de teléfono.** Registrar la solicitud no conecta nada: el equipo de watsi aprovisiona el número a mano, y un número +52 de México necesita trámite fiscal. Hay una solicitud abierta a la vez.

## Responder a un cliente en una conversación

Escribirle al cliente de una conversación también va en dos pasos, con el alcance `messages:write` y el permiso `chat:reply` del rol:

| Acción                                         | Prepara (MCP y REST)                                                     | Confirma por REST                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------- |
| Responder con texto libre                      | `conversation_reply` · `POST /v1/actions/conversations/reply`            | `POST /v1/actions/conversations/reply/confirm`    |
| Enviar una plantilla aprobada                  | `conversation_send_template` · `POST /v1/actions/conversations/template` | `POST /v1/actions/conversations/template/confirm` |
| Reaccionar a un mensaje (o quitar la reacción) | `conversation_react` · `POST /v1/actions/conversations/react`            | `POST /v1/actions/conversations/react/confirm`    |
| Reenviar un mensaje a otras conversaciones     | `conversation_forward` · `POST /v1/actions/conversations/forward`        | `POST /v1/actions/conversations/forward/confirm`  |

- **Texto libre** sólo dentro de la ventana del canal: 24 h desde el último mensaje del cliente en WhatsApp, 7 días en Instagram y Messenger. Fuera de ella la respuesta es `TEMPLATE_REQUIRED`, al preparar y también al confirmar si la ventana se cerró mientras la persona leía la vista previa.
- **Plantilla** sólo en WhatsApp: tiene que estar aprobada **en el número de WhatsApp de esa conversación** (cada número tiene sus propias plantillas; una aprobada sólo en otro número responde `TEMPLATE_NOT_FOUND` y lo dice) y `bodyParameters` tiene que llenar cada `{{N}}`. La vista previa trae el texto tal como lo leerá el cliente.
- El token lleva la conversación, el texto o la plantilla con sus valores. Si alguien escribe en la conversación antes de confirmar (el envío mismo incluido), el token queda `ACTION_CONFIRMATION_STALE`.
- Una conversación fuera de lo que la persona ve en la bandeja responde `CONVERSATION_NOT_FOUND`, igual que una de otro espacio de trabajo.
- **Reacción:** uno de los emojis rápidos de la bandeja (👍 ❤️ 😂 😮 😢 🙏), o `""` para quitar la nuestra. WhatsApp pone sus propias reglas (la ventana de 24 h y un mensaje reciente).
- **Reenvío:** hasta 10 conversaciones. Si una sola queda fuera de lo que la persona ve, se rechaza todo el reenvío. Cada destino tiene su propia ventana: uno cerrado vuelve como `skipped` y los demás se envían.

## Abrir una conversación con un número nuevo

`start_conversation` (`POST /v1/actions/conversations/start`, confirma en `POST /v1/actions/conversations/start/confirm`) le escribe a **una persona que quizá nunca te escribió**, con una plantilla aprobada de WhatsApp. Pide `broadcast:write`, el mismo alcance de las difusiones, y el permiso `chat:reply`.

- El destinatario es un número de teléfono o el nombre de un contacto. Un nombre que coincide con varios contactos, o con ninguno, se rechaza: pide el número.
- La vista previa dice desde qué número de WhatsApp del espacio de trabajo se envía y si el contacto se crea. La plantilla tiene que estar aprobada en ese número. El token lleva la persona, ese número, la plantilla y sus valores; si el número que envía cambia, o la persona escribe o recibe algo antes de confirmar, queda `ACTION_CONFIRMATION_STALE`.
- Si la persona ya tiene una conversación, usa `conversation_send_template` en ella.

En el Asistente de la app, estas mismas acciones son una tarjeta que la persona aplica con un clic.
