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:
- La llamada
prepare_*no hace nada: revisa lo que pediste y responde una vista previa (preview) y unconfirmToken. - Muéstrale la vista previa a la persona. Cuando confirme, canjea el token: en MCP con
confirm_action, en REST en la ruta…/confirmde 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 pideoptInAcknowledged: 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
adminomember. La invitación llega por correo y ocupa un asiento hasta que se acepta o vence;emailSent: falsesignifica 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_FOUNDy lo dice) ybodyParameterstiene 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
skippedy 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_templateen ella.
En el Asistente de la app, estas mismas acciones son una tarjeta que la persona aplica con un clic.