Actualizado el 29/10/2026
Para transferir del bot a un humano en WhatsApp, tu sistema cambia el estado de la conversación de «bot» a «esperando humano», deja de generar respuestas automáticas, avisa al cliente y le entrega al agente un resumen con los datos ya recopilados. La transferencia debe ocurrir cuando el cliente la pide, cuando el tema es sensible, cuando el bot falla dos veces o cuando el cliente es prioritario. La política de WhatsApp Business permite automatización dentro de la ventana de 24 horas, pero exige vías de escalamiento rápidas, claras y directas.
La API de WhatsApp oficial no tiene un botón de «transferir»: quien hace el handoff es tu software. Esta guía muestra disparadores, qué pasarle al agente, cómo pausar y reactivar el bot, SLA y un pseudocódigo.
Por qué el handoff es obligatorio, no opcional
La Política de Mensajes de WhatsApp Business dice que la empresa puede usar automatización al responder dentro de la ventana de 24 horas, siempre que mantenga vías de escalamiento rápidas, claras y directas. La lista de opciones aceptadas incluye:
- transferencia a un agente humano en la misma conversación;
- número de teléfono;
- correo electrónico;
- soporte en el sitio web de la empresa;
- visita a una tienda o sucursal;
- formulario de soporte.
La transferencia dentro de la conversación da la mejor experiencia; las otras opciones sirven de plan B fuera del horario.
Los bots de IA tienen un motivo más: los términos de Meta restringen el uso de asistentes de IA de propósito general en la plataforma, y un bot de atención con alcance acotado y salida a un humano queda claramente del lado del uso permitido. Los detalles están en política de IA de Meta para chatbots.
Los cuatro disparadores de transferencia
| Disparador | Cómo detectarlo | Ejemplo |
|---|---|---|
| Pedido explícito | Palabras clave, botón «Hablar con un agente», o el LLM clasifica la intención | «quiero hablar con una persona» |
| Intención sensible | Lista de temas que la empresa decide tratar solo con personas | cancelación, reclamo, cobro impugnado, datos de salud |
| Falla repetida | Contador de respuestas fallidas en la misma conversación | el bot no entendió dos veces seguidas |
| Cliente prioritario | Consulta al CRM por el número de WhatsApp | cliente con contrato corporativo, pedido por encima de cierto monto |
Pedido explícito
Tres capas ayudan:
- Botón siempre a mano. Incluye «Hablar con un agente» como opción en los mensajes interactivos del bot. Consulta mensajes interactivos.
- Palabras clave. «agente», «humano», «persona», «gerente». Simple, rápido y sin costo de LLM.
- Clasificación de intención. Si el bot usa un LLM, pídele que marque la intención
hablar_con_humanocuando el cliente lo pida con otras palabras.
Intención sensible
Define la lista con el equipo de atención y el área legal, no con el equipo de tecnología. Cancelación, impugnación de cobros, reclamo formal y cualquier conversación con datos sensibles (salud, por ejemplo) suelen entrar. La LGPD, la ley brasileña de protección de datos, trata los datos de salud como datos sensibles (art. 5, II, de la Ley 13.709/2018); este artículo no sustituye la orientación de un abogado sobre tu caso.
Falla repetida
Cuenta las fallas por conversación («no entendí», búsqueda vacía, cliente repitiendo la pregunta). Dos seguidas es un buen punto de partida para transferir; reinicia el contador cuando el bot acierte.
Cliente prioritario
El webhook trae el número del cliente en messages[].from. Con él, tu sistema consulta el CRM antes de que el bot responda. Si el cliente tiene un ejecutivo de cuenta o un pedido de alto valor en curso, la conversación puede ir directo a la fila humana, o el bot hace solo la clasificación inicial y transfiere.
¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →
La máquina de estados de la conversación
El punto central del handoff es un campo de estado por conversación, guardado en la base de datos por el wa_id del cliente. Todo evento que llega por el webhook pasa por él antes de cualquier respuesta.
disparador de handoff
┌──────┐ ───────────────────────────▶ ┌────────────────────┐
│ bot │ │ esperando_humano │
└──────┘ ◀──── timeout sin agente ───── └────────────────────┘
▲ (el bot avisa y ofrece │
│ otro canal) │ el agente toma
│ ▼
│ ┌──────────────┐
└──────── el agente devuelve ─────── │ humano │
o conversación inactiva └──────────────┘| Estado | Quién responde | Qué hace el bot | Sale cuando |
|---|---|---|---|
bot | Bot | Responde normalmente | Se activa un disparador |
esperando_humano | Nadie automáticamente | Avisa una vez y se queda en silencio | Un agente toma la conversación, o se agota el tiempo máximo de espera |
humano | Agente | Nada; solo registra los mensajes | El agente la devuelve, la cierra, o la conversación queda inactiva |
Dos errores comunes:
- El bot respondiendo encima del agente. Pasa cuando el estado queda solo en la memoria del proceso o cuando dos workers procesan la misma conversación. Guarda el estado en la base de datos y procesa los mensajes de cada conversación en orden.
- Conversación atrapada en
humanopara siempre. El cliente vuelve una semana después y nadie responde, porque el bot cree que hay alguien atendiendo. Usa un tiempo de inactividad para devolverla al bot.
Qué pasarle al agente
El agente no debería leer 40 mensajes para entender el caso. Junto con la transferencia, entrega una ficha con:
| Elemento | De dónde viene |
|---|---|
| Nombre y número | contacts[].profile.name y messages[].from en el webhook |
| Motivo de la transferencia | El disparador que se activó (pedido, sensible, falla, prioritario) |
| Resumen en 2 o 3 líneas | Generado por el LLM a partir del historial, o armado con las respuestas del flujo |
| Datos ya recopilados | Número de pedido, CPF parcial (el número de identificación fiscal de Brasil), correo, producto |
| Origen | Anuncio, sitio web, código QR; el webhook trae el objeto referral cuando la conversación empieza por un anuncio Click-to-WhatsApp |
| Hora del último mensaje del cliente | messages[].timestamp, para saber cuánto queda de la ventana de 24 horas |
| Enlace al historial completo | Tu base de datos o CRM |
Un ejemplo de payload que tu sistema puede publicar en la fila de atención o en el CRM:
{
"conversacion_id": "5511988887777",
"motivo": "intencion_sensible:cancelacion",
"resumen": "El cliente quiere cancelar la suscripción anual. Ya informó el correo y el número de pedido. Preguntó por un reembolso proporcional.",
"datos": { "pedido": "48213", "email": "cliente@ejemplo.com" },
"origen": { "tipo": "ad", "source_id": "120226305854810726" },
"ultimo_mensaje_cliente": "2026-10-29T14:02:11-03:00",
"ventana_expira_en": "2026-10-30T14:02:11-03:00",
"prioridad": "normal"
}El resumen del LLM puede equivocarse: muestra el historial completo justo debajo.
Cómo avisarle al cliente
El mensaje de transición tiene que decir tres cosas: que una persona va a tomar la conversación, cuánto debería tardar y qué hacer si es fuera del horario.
- Dentro del horario: «Voy a llamar a una persona de nuestro equipo. El tiempo promedio de espera ahora es de unos minutos, y no necesitas repetir nada.»
- Fuera del horario: «Nuestro equipo atiende de lunes a viernes, de 8 a 18 h. Dejé tu caso registrado y alguien te responde aquí a primera hora. Si es urgente, llama al (11) 0000-0000.»
Envía el aviso una sola vez. Si el cliente vuelve a escribir mientras espera, el bot no responde cada mensaje; como mucho, repite el aviso después de un intervalo. Los mensajes de bienvenida y de ausencia por horario se tratan en mensaje de bienvenida y ausencia en la API.
Atención a la ventana de 24 horas
El texto libre solo se puede enviar hasta 24 horas después del último mensaje del cliente. Si la fila humana tarda y la ventana se cierra, el agente ya no puede responder con texto libre: necesita una plantilla aprobada para retomar el contacto. Por eso la ficha del agente muestra cuándo expira la ventana, y la fila debe ordenarse teniendo en cuenta ese plazo. Las reglas están en ventana de 24 horas de WhatsApp.
Cómo devolver la conversación al bot
El regreso al bot puede ocurrir de tres formas:
- El agente la devuelve. Un botón «Devolver al bot» en la herramienta de atención cambia el estado a
bot. El bot no debe enviar un mensaje en ese momento; solo vuelve a responder con el próximo mensaje del cliente. - El agente cierra el caso. Al cerrarlo, el estado vuelve a
boty el historial de la atención queda registrado para la próxima conversación. - Inactividad. Si la conversación está en
humanoy nadie escribe durante un período definido (por ejemplo, algunas horas), el sistema la devuelve al bot.
Al volver, incluye en el contexto del LLM una nota como «caso atendido por un agente en tal fecha», para que el bot no reabra el tema.
SLA: qué medir
Mide el handoff con datos que tu propio sistema ya registra:
| Métrica | Cómo calcularla |
|---|---|
| Tasa de transferencia | Conversaciones transferidas ÷ conversaciones atendidas por el bot |
| Transferencias por disparador | Conteo por motivo (pedido, sensible, falla, prioritario) |
| Tiempo hasta que el agente toma la conversación | Hora en que entró en humano − hora en que entró en esperando_humano |
| Ventanas perdidas en la fila | Conversaciones en las que la ventana de 24 horas se cerró antes de que el agente respondiera |
| Devoluciones al bot | Conversaciones que volvieron a bot y se resolvieron sin un nuevo handoff |
Muchas transferencias por «falla» indican que al bot le falta contenido; muchas por «pedido explícito» desde el primer mensaje sugieren que el bot no se presenta bien. Las métricas de atención en general (tiempo de primera respuesta, tiempo medio de atención, CSAT) están en métricas de atención en WhatsApp.
Pseudocódigo del enrutador
El enrutador corre para cada mensaje recibido, después de la deduplicación por el ID wamid.
def enrutar(msg, conversacion):
conversacion.ultimo_msg_cliente = msg.timestamp
registrar_en_historial(conversacion, msg)
if conversacion.estado == "humano":
notificar_agente(conversacion, msg) # el bot se queda en silencio
return
if conversacion.estado == "esperando_humano":
if supero_tiempo_maximo(conversacion):
enviar_texto(msg.from_, AVISO_OTRO_CANAL)
conversacion.estado = "bot"
return # no responde cada mensaje
# estado == "bot"
motivo = detectar_disparador(msg, conversacion) # pedido, sensible, falla, prioritario
if motivo:
return transferir(conversacion, motivo)
respuesta = bot_responder(conversacion)
if respuesta.fallo:
conversacion.fallas += 1
if conversacion.fallas >= 2:
return transferir(conversacion, "falla_repetida")
else:
conversacion.fallas = 0
enviar_texto(msg.from_, respuesta.texto)
def transferir(conversacion, motivo):
conversacion.estado = "esperando_humano"
conversacion.entro_en_fila = ahora()
enviar_texto(conversacion.wa_id, aviso_de_transferencia(dentro_del_horario()))
publicar_en_fila_humana({
"conversacion_id": conversacion.wa_id,
"motivo": motivo,
"resumen": resumir(conversacion.historial),
"ventana_expira_en": conversacion.ultimo_msg_cliente + horas(24),
})
def agente_tomo(conversacion, agente_id):
conversacion.estado = "humano"
conversacion.agente = agente_id
registrar_metrica("tiempo_hasta_tomar", ahora() - conversacion.entro_en_fila)
def devolver_al_bot(conversacion):
conversacion.estado = "bot"
conversacion.fallas = 0
agregar_nota_de_contexto(conversacion, "atención humana concluida")enviar_texto llama a la API con el payload estándar de Meta (type: "text"); la fila y las notificaciones quedan en tu herramienta (tickets, CRM, pantalla propia).
¿Y si el agente responde desde el celular?
Con coexistencia, el mismo número queda en la app WhatsApp Business y en la API. Los mensajes que el agente envía desde la app llegan a tu sistema como eventos de eco. El enrutador puede usar ese eco para cambiar la conversación a humano automáticamente: si una persona respondió desde el celular, el bot sale de escena. Qué se sincroniza y qué no está en coexistencia: qué se sincroniza.
Cómo hacer el handoff con Vectalk
Vectalk entrega la API oficial: recibes los webhooks en el formato de Meta y envías por el endpoint POST https://apis.vectalk.com.br/api/messages, con el mismo payload. El panel de Vectalk no tiene bandeja de entrada de atención ni bot nativo. El enrutador, el estado de la conversación y la pantalla del agente quedan en tu sistema o en la herramienta que conectes a la API (un CRM, una plataforma de atención, un flujo en n8n).
En la práctica, el diseño queda así:
- Registra la URL de tu enrutador como webhook de la instancia (documentación de webhooks). Puedes registrar más de una URL; todas reciben el mismo evento.
- El enrutador decide entre bot y humano y envía las respuestas por la API.
- La herramienta de atención lee y responde con las mismas llamadas, o el equipo usa la app en el celular con coexistencia.
Si varios agentes van a usar el mismo número, consulta varios agentes en el mismo número. Para empezar, crea tu cuenta en apps.vectalk.com.br/register y lee la guía de la API oficial de WhatsApp.
Preguntas frecuentes
¿La API de WhatsApp tiene una función nativa de transferencia a humano?
No. La Cloud API envía y recibe mensajes; quien decide si la respuesta viene del bot o de una persona es tu sistema. El handoff es un cambio de estado en tu base de datos, no una llamada a la API.
¿Qué pasa si nadie toma la conversación?
Define un tiempo máximo en la fila. Cuando se agota, el bot avisa al cliente, ofrece otro canal (teléfono, correo, formulario) y registra el caso para darle seguimiento. Si la ventana de 24 horas se cierra, el seguimiento solo puede hacerse con una plantilla.
¿Los mensajes del agente se cobran igual que los del bot?
Sí. Para Meta, una respuesta de texto libre dentro de la ventana es un mensaje de servicio, ya sea escrita por una persona o por una IA de terceros. Desde el 1/10/2026, cada número tiene 1.000 mensajes de servicio gratuitos al mes y paga a partir del 1.001; para destinatarios en Brasil, la tarifa es de R$ 0,0350 (reales brasileños) por mensaje entregado.
¿Puedo hacer que el bot le sugiera respuestas al agente?
Sí. En este modelo, el LLM genera un borrador en la pantalla del agente, que lo revisa y lo envía. Es una forma de mantener al humano en control en temas sensibles sin perder velocidad.
Fuentes oficiales consultadas el 29/10/2026: Política de Mensajes de WhatsApp Business (actualizada el 23/09/2026), Términos de Meta para la Plataforma de WhatsApp Business, Ventana de atención al cliente, Precios de la plataforma, Webhook de mensajes de texto y objeto referral, Webhooks (Vectalk), Ley 13.709/2018 (LGPD, ley brasileña de protección de datos).
Pon a funcionar el WhatsApp oficial de tu empresa
Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.