Crear cuenta
← Blog

·

Typebot con la API oficial de WhatsApp: cómo configurarlo

Actualizado el 25/10/2026

Typebot tiene integración nativa con la API oficial de WhatsApp: conectas tu propia app de Meta y tu número en la pestaña Share del bot, y el flujo empieza a responder los mensajes recibidos. Typebot no ofrece números ni cobra los mensajes de Meta; funciona con el modelo «trae tu propia app de Meta». En WhatsApp, el bot tiene límites que no existen en la versión web, como un máximo de 3 botones por mensaje, y solo puede enviar mensajes libres dentro de la ventana de 24 horas abierta por el cliente.

Esta guía muestra los requisitos, la configuración, los límites que cambian el diseño del flujo y una alternativa por la API de chat de Typebot para quien usa un proveedor de la API de WhatsApp.

Cómo funciona la integración de Typebot con WhatsApp

Según la documentación de Typebot, la integración conecta el bot a tu propia WhatsApp Business Platform, el servicio oficial de Meta. El flujo es así:

  1. El cliente escribe a tu número.
  2. Meta envía el evento al webhook de Typebot.
  3. Typebot ejecuta el flujo y responde por la Cloud API, con las credenciales de tu app.

Puedes conectar todos los números que quieras e incluso varios bots en el mismo número, usando una condición de inicio (Start bot condition) en cada bot para decidir cuál atiende la conversación.

Requisitos en Meta

Typebot describe los pasos para crear la app de Meta:

  1. Crea (o usa) un portafolio empresarial en business.facebook.com. Meta puede restringir portafolios recién creados hasta que verifiques tu identidad.
  2. En developers.facebook.com/apps, crea una app, elige Other y el tipo Business, vincúlala al portafolio y activa el producto WhatsApp.
  3. Sigue las instrucciones de la pestaña Share del bot para conectar la app a Typebot.

Para producción, usa un token que no venza. La configuración de self-hosting de Typebot, por ejemplo, pide un token de usuario del sistema con vencimiento Never y los permisos whatsapp_business_messaging y whatsapp_business_management. El paso a paso está en la guía de token permanente con usuario del sistema.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Configurar el bot en WhatsApp

Probar antes de publicar

En el editor, haz clic en Test y cambia el entorno a WhatsApp. Typebot envía el mensaje inicial de vista previa al número que escribas.

Una trampa común: Typebot advierte que el número que escribas debe ser exactamente el que aparece en la configuración de tu perfil de WhatsApp. En Brasil, por ejemplo, algunos números aparecen con 8 dígitos y otros con 9 después del código de área; si escribes la otra versión, recibes el primer mensaje, pero el bot no responde a los siguientes.

Opciones de la integración

En Configure integration:

OpciónQué hace
Session expiration timeoutHoras sin interacción (de 0 a 48, por defecto 4) hasta que vence la sesión. Después, un nuevo mensaje del cliente inicia otra conversación
Start bot conditionCondición evaluada en el primer mensaje. Si no se cumple, el bot no se activa

Para capturar datos del contacto, usa un bloque Set variable con los valores de sistema de WhatsApp para nombre y teléfono. Para pedir la ubicación, un bloque de texto simple recibe la posición que comparte el cliente con el formato <LAT>, <LONG>.

Límites de Typebot en WhatsApp

La documentación de Typebot enumera lo que cambia frente al bot web:

LímiteEfecto en el flujo
GIF y SVG no se muestranUsa JPEG o PNG
Solo videos .mp4Convierte otros formatos antes
Máximo 3 botones por mensajeTypebot divide las opciones extra en mensajes «…» adicionales
Cards con máximo 3 botones por cardSimplifica las cards
Texto del botón de hasta 20 caracteresEl excedente se corta; escribe etiquetas cortas
Los bloques incompatibles se omitenPago, Chatwoot, Google Analytics, Meta Pixel, Cal.com y Script o Set Variable con Execute on client

Estos números vienen de la propia Cloud API: los mensajes con botones de respuesta aceptan hasta 3 botones con títulos de hasta 20 caracteres. Para más opciones, la API ofrece el mensaje de lista, con hasta 10 filas de hasta 24 caracteres.

Ventana de 24 horas: el límite que el flujo no ve

El editor de Typebot permite esperas largas y sesiones de hasta 48 horas, pero la regla de Meta está por encima: los mensajes libres (texto, imágenes, botones) solo se pueden enviar hasta 24 horas después del último mensaje del cliente.

En la práctica:

  • Las respuestas inmediatas siempre funcionan, porque el cliente acaba de escribir.
  • Los bloques Wait largos (por ejemplo, «esperar 2 días y preguntar si le gustó») fallan si el cliente no escribió en ese tiempo.
  • Retomar el contacto después de la ventana exige una plantilla aprobada. Planifica la reactivación con plantillas enviadas por tu propio sistema y deja que Typebot conduzca la conversación cuando el cliente responda.

Un número que ya está en la app WhatsApp Business

Typebot recomienda un número dedicado. Su documentación explica que registrar el número en la plataforma bloquea su uso en la app común, y que para migrar un número de la app WhatsApp Business hay que eliminar la cuenta en la app; el número se libera después de unas 24 horas. Paso a paso en cómo liberar un número para la API.

Meta también ofrece la coexistencia, en la que el mismo número queda en la app y en la API al mismo tiempo. Depende de que el número se conecte con un flujo de registro que soporte ese modo; mira qué se sincroniza en la coexistencia.

Costos

El plan de Typebot va aparte; Meta cobra los mensajes en tu cuenta. Atención: el FAQ de Typebot habla de «1.000 conversaciones de servicio gratis al mes», un término del modelo anterior. Desde el 1 de julio de 2025, Meta cobra por mensaje entregado, no por conversación. Las respuestas libres de un chatbot dentro de la ventana de atención son mensajes de servicio: cada número tiene 1.000 mensajes de servicio entregados gratis al mes, y desde el 1 de octubre de 2026 Meta cobra a partir del 1.001, según la tarifa publicada. Un bot que manda varias burbujas por respuesta consume esa cuota más rápido, así que conviene unir textos cortos en un solo mensaje. Las plantillas para iniciar conversaciones se cobran según su categoría; mira cuánto cuesta una campaña de WhatsApp.

Alternativa: Typebot por la API de chat + un proveedor de la API

La integración nativa habla directo con la Graph API de Meta. Si usas un proveedor de la API de WhatsApp, quieres centralizar el webhook en un sistema propio o necesitas combinar el bot con atención humana, Typebot documenta cómo integrar con apps de mensajería por la API HTTP:

  1. Tu servidor recibe el webhook de WhatsApp.
  2. En el primer mensaje del contacto, llama a startChat y guarda el sessionId junto al wa_id.
  3. En los siguientes, llama a continueChat con el texto del cliente.
  4. Convierte el arreglo messages (y el input, cuando exista) en mensajes de WhatsApp.

Ejemplo en Node.js usando Vectalk para enviar:

const TYPEBOT = 'https://typebot.co/api/v1'; // o la URL de tu viewer self-hosted
const PUBLIC_ID = process.env.TYPEBOT_PUBLIC_ID;
const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const sesiones = new Map(); // en producción, usa Redis o una base de datos

async function hablarConTypebot(waId, texto) {
  const cuerpo = { message: { type: 'text', text: texto }, textBubbleContentFormat: 'markdown' };
  const sessionId = sesiones.get(waId);
  if (sessionId) {
    const r = await fetch(`${TYPEBOT}/sessions/${sessionId}/continueChat`, {
      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(cuerpo),
    });
    if (r.status !== 404) return r.json();
    sesiones.delete(waId); // la sesión venció: inicia otra
  }
  const r = await fetch(`${TYPEBOT}/typebots/${PUBLIC_ID}/startChat`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ textBubbleContentFormat: 'markdown' }),
  });
  const datos = await r.json();
  sesiones.set(waId, datos.sessionId);
  return datos;
}

async function enviar(payload) {
  await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.VECTALK_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ messaging_product: 'whatsapp', ...payload }),
  });
}

export async function tratarMensaje(msg) {
  const texto = msg.text?.body ?? msg.interactive?.button_reply?.title ?? msg.interactive?.list_reply?.title ?? '';
  const respuesta = await hablarConTypebot(msg.from, texto);

  for (const m of respuesta.messages ?? []) {
    if (m.type === 'text') await enviar({ to: msg.from, type: 'text', text: { body: m.content.markdown } });
    if (m.type === 'image') await enviar({ to: msg.from, type: 'image', image: { link: m.content.url } });
  }

  const opciones = respuesta.input?.type === 'choice input' ? respuesta.input.items.map((i) => i.content) : [];
  if (opciones.length && opciones.length <= 3) {
    await enviar({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'button', body: { text: 'Elige una opción:' },
        action: { buttons: opciones.map((t, n) => ({ type: 'reply', reply: { id: `op${n}`, title: t.slice(0, 20) } })) },
      },
    });
  } else if (opciones.length) {
    await enviar({
      to: msg.from, type: 'interactive',
      interactive: {
        type: 'list', body: { text: 'Elige una opción:' },
        action: { button: 'Ver opciones', sections: [{ title: 'Opciones', rows: opciones.slice(0, 10).map((t, n) => ({ id: `op${n}`, title: t.slice(0, 24) })) }] },
      },
    });
  }
}

tratarMensaje la llama el worker que consume la cola del webhook. Este camino da más trabajo, pero permite pausar el bot cuando un agente toma la conversación, registrar todo en tu base de datos y usar el mismo número con otros sistemas. Si prefieres armar el flujo en una herramienta de automatización, mira n8n con la API oficial.

Cómo hacerlo con Vectalk

La integración nativa de Typebot pide una app de Meta propia y llama directamente a la Graph API. Con Vectalk, usa el camino de la API de chat:

  1. Registra la URL de tu servidor con POST https://apis.vectalk.com.br/api/webhooks (instance_id, url, name).
  2. En el worker, llama a Typebot como en el ejemplo.
  3. Envía las respuestas con POST https://apis.vectalk.com.br/api/messages, que acepta texto, imagen, botones y listas con el mismo formato de la Cloud API.

Los eventos llegan con el payload de Meta, y puedes registrar varias URL por instancia. El costo de los mensajes llega en la factura de Vectalk, sin tarjeta en Meta, y la coexistencia permite mantener el número en la app WhatsApp Business. Crea tu cuenta en apps.vectalk.com.br/register o consulta la documentación (en portugués).

Preguntas frecuentes

¿Typebot ofrece el número de WhatsApp?

No. Typebot funciona con tu propia app de Meta y tu propio número. Solo ejecuta el flujo.

¿Por qué mi Typebot no responde después de publicarlo?

Las causas que señala la documentación de Typebot: el bot no funciona en modo de prueba, el número todavía se usa en la app WhatsApp Business, una condición de inicio que el primer mensaje no cumple o, con un número de prueba de Meta, que tu celular no esté en la lista de números permitidos. Volver a configurar el número en Typebot, leyendo bien las instrucciones, también está entre las soluciones sugeridas.

¿Puedo tener más de un Typebot en el mismo número?

Sí. Usa una condición de inicio en cada bot para definir cuál atiende cada conversación.

¿Typebot puede escribir a alguien que no me contactó?

Fuera de la ventana de 24 horas, Meta solo acepta plantillas aprobadas. Planifica el primer contacto con una plantilla enviada por tu sistema y deja que Typebot conduzca la conversación cuando el cliente responda.

¿Puedo usar Typebot con WhatsApp por código QR?

Las integraciones por QR dependen de APIs no oficiales, que van contra los Términos de Servicio de WhatsApp. La integración de Typebot usa la plataforma oficial de Meta. Mira API oficial vs. no oficial.

Fuentes oficiales consultadas el 25/10/2026: Typebot: WhatsApp, Typebot: Create a WhatsApp Meta app, Typebot: Self-hosting configuration, Typebot: Integrate with external messaging apps, Typebot: Start chat, Meta: Interactive reply buttons, Meta: Interactive list messages, Meta: Pricing, Documentación de Vectalk.

Prueba hoy la API oficial de WhatsApp

Crea tu cuenta, genera el token y envía el primer mensaje con la guía de la documentación. Los mismos payloads y webhooks de la Cloud API de Meta.

Crear cuenta gratis
Leer la documentación