Saltar al contenido
watsi

Casos de uso

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.

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ónPrepara (MCP y REST)Confirma por RESTAlcance
Enviar una plantilla a revisión de Metaprepare_message_template_submission · POST /v1/actions/templates/submit/preparePOST /v1/actions/templates/submit/confirmtemplates:write
Mandar una plantilla aprobada a un grupo de contactosprepare_template_broadcast · POST /v1/actions/broadcasts/preparePOST /v1/actions/broadcasts/confirmbroadcast:write
Invitar a un compañeroprepare_member_invite · POST /v1/actions/team/invites/preparePOST /v1/actions/team/invites/confirmmembers:write
Pedir un número de teléfonoprepare_phone_number_request · POST /v1/actions/voice/phone-number-requests/preparePOST /v1/actions/voice/phone-number-requests/confirmagents: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ónPrepara (MCP y REST)Confirma por REST
Responder con texto libreconversation_reply · POST /v1/actions/conversations/replyPOST /v1/actions/conversations/reply/confirm
Enviar una plantilla aprobadaconversation_send_template · POST /v1/actions/conversations/templatePOST /v1/actions/conversations/template/confirm
Reaccionar a un mensaje (o quitar la reacción)conversation_react · POST /v1/actions/conversations/reactPOST /v1/actions/conversations/react/confirm
Reenviar un mensaje a otras conversacionesconversation_forward · POST /v1/actions/conversations/forwardPOST /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.