API oficial de WhatsApp: guía completa (2026)

Actualizado el 29/10/2026

La API oficial de WhatsApp es la WhatsApp Business Platform de Meta, que hoy se ofrece como Cloud API: una API HTTP alojada por la propia Meta que permite enviar y recibir mensajes desde tu sistema. Para usarla necesitas un portafolio comercial en Meta, un número registrado en la plataforma, plantillas aprobadas para iniciar conversaciones y una forma de pago, ya que Meta cobra por mensaje entregado. Es el único camino que Meta autoriza para automatizar el WhatsApp de una empresa.

Esta guía explica qué separa la API oficial de WhatsApp de las bibliotecas no oficiales, cuáles son los requisitos, cómo elegir entre integrarte directo con Meta o usar un intermediario, cuánto cuesta a grandes rasgos y en qué casos el cambio compensa.

Qué es la API oficial de WhatsApp

La WhatsApp Business Platform es el conjunto de APIs que Meta pone a disposición de las empresas. En la práctica, cuando alguien habla hoy de «API oficial de WhatsApp», se refiere a la Cloud API: endpoints de la Graph API (graph.facebook.com) que reciben JSON y devuelven JSON, y webhooks que avisan a tu servidor cuando llega un mensaje o cambia el estado de un mensaje enviado.

Algunos términos aparecen todo el tiempo en la documentación de Meta. Conviene conocerlos antes de empezar:

Término	Qué es	Dónde aparece
Portafolio comercial	La cuenta de la empresa en Meta (antes llamada Business Manager). Puede verificarse.	business_id
Cuenta de WhatsApp Business (WABA)	Desde el 23/09/2026, Meta la separa en cuenta de WhatsApp (el número) y cuenta de mensajes (plantillas, facturación, webhooks). Los IDs y endpoints anteriores siguen funcionando durante la transición.	waba_id
Número de teléfono comercial	El número registrado en la Cloud API, usado para enviar y recibir.	phone_number_id
Plantilla (template)	Mensaje aprobado previamente, obligatorio para iniciar contacto fuera de la ventana de atención.	type: "template"
Ventana de atención al cliente	Periodo de 24 horas que se abre con cada mensaje del cliente, en el que puedes responder con mensajes libres.	reglas de envío y precio
Webhook	URL de tu sistema que recibe eventos (mensajes recibidos, estados de entrega).	object: "whatsapp_business_account"

La nueva división de la cuenta se explica en Cuenta de WhatsApp y cuenta de mensajes: la nueva estructura de la WABA.

API oficial vs. API no oficial

Bibliotecas como Baileys y WPPConnect, y las herramientas construidas sobre ellas (como el modo Baileys de Evolution API), funcionan emulando WhatsApp Web: escaneas un código QR con el celular y el software pasa a controlar esa sesión. No hay contrato con Meta, no hay plantillas ni cobro por mensaje. Tampoco hay garantía de que la próxima actualización de WhatsApp no rompa la integración.

Las Condiciones del servicio de WhatsApp prohíben acceder o usar el servicio por medios automatizados no autorizados y crear cuentas por medios no autorizados o automatizados. El texto también menciona el envío masivo y los mensajes automáticos entre las comunicaciones no permitidas. Por eso los números usados con APIs no oficiales pueden ser bloqueados sin aviso.

Criterio	API oficial (Cloud API)	API no oficial (Baileys, WPPConnect, etc.)
Autorización de Meta	Sí, es el producto de Meta para empresas	No; contradice las Condiciones del servicio
Conexión	Token de acceso y llamadas HTTP	Sesión de WhatsApp Web por código QR
Riesgo de bloqueo por usar la herramienta	No; el riesgo viene de la calidad y la política	Alto e impredecible
Iniciar conversación	Solo con plantilla aprobada	Mensaje libre (y ahí está el riesgo)
Costo de mensajes	Por mensaje entregado, tarifa de Meta	Sin cobro de Meta
Estabilidad	Versionada, con changelog y fechas de descontinuación	Depende de ingeniería inversa
Webhooks	Formato documentado por Meta	Formato propio de cada biblioteca

Vale aclarar que Evolution API también ofrece integración con la Cloud API oficial, además de su modo basado en Baileys. Lo que define el riesgo es el canal, no el nombre de la herramienta. Si estás en esa situación, Cómo migrar de una API no oficial a la API oficial de WhatsApp trae el paso a paso, y API oficial vs. API no oficial de WhatsApp profundiza en el riesgo de bloqueo.

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

Requisitos para usar la API oficial

Portafolio comercial en Meta

Todo uso de la plataforma parte de un portafolio comercial. Ahí quedan la cuenta de WhatsApp y la cuenta de mensajes, los números, los usuarios del sistema y la forma de pago.

Verificación de la empresa

La verificación no es obligatoria para dar los primeros pasos, pero cambia lo que puedes hacer. Según la documentación de límites de mensajes de Meta, los portafolios nuevos empiezan con un límite de 250 destinatarios únicos en 24 horas móviles fuera de la ventana de atención. Verificar la empresa es uno de los caminos para subir a 2.000 (los otros son que tu proveedor esté verificado, o entregar 2.000 mensajes fuera de la ventana a números únicos en 30 días con plantillas de alta calidad). El límite de números registrados también depende de eso: los portafolios nuevos pueden registrar dos números, y el tope sube a 20 cuando la empresa se verifica o llega al límite de 2.000.

En el flujo de Vectalk, la guía rápida pide una cuenta de Meta Business verificada para conectar el número. Por eso, trata la verificación como parte del proyecto, no como un paso opcional. Nuestra guía de verificación de la empresa en Meta Business detalla el proceso.

Número de teléfono

Según la documentación de números de teléfono comerciales de Meta, el número debe:

• pertenecer a tu empresa;
• tener código de país y de área (no se aceptan códigos cortos);
• poder recibir SMS o llamada de voz con el código de verificación.

Un punto que confunde a muchos: los números que ya están en uso en WhatsApp no se pueden registrar en la Cloud API sin antes eliminar la cuenta de la app. La excepción es el número de la app WhatsApp Business, que se puede conectar a la API sin dejar de usar la app, en la función conocida como coexistencia. Explicamos requisitos y limitaciones en Coexistencia en la API de WhatsApp.

También necesitarás un nombre visible. Según el nombre, Meta puede revisarlo antes de que se pueda usar.

Forma de pago

Desde el 1 de octubre de 2026, Meta cobra los mensajes de servicio que superan una franquicia mensual gratuita por número. La página de precios indica que las cuentas sin forma de pago solo reciben entregas de mensajes de servicio dentro de esa franquicia. En la práctica, toda operación en producción necesita una facturación activa: tu propia forma de pago en Meta o la línea de crédito de un proveedor (con Vectalk es lo segundo; lo vemos más abajo).

Consentimiento (opt-in) de los contactos

La Política de mensajería comercial de WhatsApp solo permite contactar a quien te dio su número y su permiso (opt-in) para recibir mensajes. Las solicitudes para dejar de recibir mensajes deben respetarse, incluso si se hacen fuera de WhatsApp. Esto vale para cualquier integración oficial y es uno de los factores que más pesan en la calidad del número.

Límites que debes conocer

Límite	Valor por defecto	Observación
Límite de mensajes (fuera de la ventana)	250 destinatarios únicos / 24 h móviles en portafolios nuevos	Sube a 2.000, 10.000, 100.000 e ilimitado según verificación, volumen y calidad. Vale para todo el portafolio.
Números registrados por portafolio	2 al inicio	Pasa a 20 con verificación o al llegar al límite de 2.000
Velocidad de envío (throughput)	80 mensajes por segundo por número por defecto	Los números elegibles suben automáticamente hasta 1.000 mps; los números en coexistencia quedan en 20 mps
Ventana de atención	24 horas desde el último mensaje del cliente	Fuera de ella, solo plantillas

Fuentes: límites de mensajes, números de teléfono y velocidad de envío.

Un detalle importante: el límite de mensajes es del portafolio, no del número. Si tienes tres números en el mismo portafolio, uno de ellos puede consumir toda la capacidad del día. Por encima de 2.000, el límite sube solo cuando la calidad es alta y usaste al menos la mitad en los últimos 7 días.

Cómo funciona la conversación: ventana de 24 horas y plantillas

La regla central de la API oficial es simple. Cuando el cliente envía un mensaje, se abre una ventana de atención de 24 horas. Dentro de ella respondes con cualquier tipo de mensaje: texto, imagen, botones, listas. Cada nuevo mensaje del cliente reinicia el contador.

Fuera de la ventana solo puedes enviar plantillas. Se crean con una categoría (marketing, utilidad o autenticación), pasan por la aprobación de Meta y aceptan variables. Una plantilla de confirmación de pedido, por ejemplo:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "es" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "María" },
          { "type": "text", "text": "#12345" }
        ]
      }
    ]
  }
}

Es el mismo payload que aceptan Meta y Vectalk. La categoría de la plantilla también define el precio del mensaje, tema que detallamos en Precio de la API de WhatsApp en Brasil.

Un cambio para planificar: Meta está llevando las plantillas de marketing a la Marketing Messages API. La Cloud API (/messages) deja de enviar marketing el 13/10/2027, y las cuentas de mensajes creadas a partir del 13/04/2027 ya no pueden enviarlo por ahí. Consulta Marketing Messages API: cómo migrar.

Solution Partner, Tech Provider o Cloud API directa

Hay tres formas de llegar a la Cloud API. La diferencia está en quién se encarga de la app en Meta, los tokens, los webhooks y la facturación.

Integración directa. Creas una app en el panel de Meta, generas un token de usuario del sistema, configuras el webhook con verificación y firma, suscribes los campos de la cuenta y te encargas de rotar las credenciales. No hay intermediario, pero toda la operación queda en manos de tu equipo.

Socios de Meta. La documentación para proveedores de soluciones divide a los intermediarios en tres tipos:

• Solution Partners (lo que el mercado llama BSP): son Meta Business Partners, pueden extender una línea de crédito a sus clientes y cobrarles directamente por el uso de la plataforma.
• Tech Providers: ofrecen servicios sobre la plataforma, pero sin línea de crédito. El cliente registra su propia forma de pago y Meta le cobra el uso de la API directamente.
• Tech Partners: Tech Providers que son, o pueden llegar a ser, Meta Business Partners.

Proxy gestionado. Es el modelo de Vectalk. Tu aplicación habla con Vectalk, que reenvía las llamadas a la Cloud API. Los payloads son los mismos de Meta; solo cambian la URL base y el token:

	Cloud API directa	Vectalk
URL base	https://graph.facebook.com/vXX.X	https://apis.vectalk.com.br/api
Token	Token de acceso de Meta (usuario del sistema)	Token generado en Vectalk
Payloads	Formato de Meta	Igual al de Meta
Varias cuentas	Un token y un phone_number_id por contexto	Un token de organización para todas las instancias, enviando el phone_number_id
Webhooks	Un endpoint por app, configurado en el panel de Meta	Varias URLs por instancia, registradas vía API

En Vectalk, el envío de un mensaje de texto queda así:

curl -X POST https://apis.vectalk.com.br/api/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5584999999999",
    "type": "text",
    "text": { "body": "Tu pedido salió para entrega." }
  }'

Si ya tienes código escrito para la Cloud API, migrar al proxy es cambiar dos variables de entorno. Los detalles del token de organización y de instancia están en la página de autenticación. Para comparar las opciones, lee ¿API de WhatsApp directo con Meta o con un proveedor?.

Costos a grandes rasgos

Desde el 1 de julio de 2025, Meta cobra por mensaje entregado, con precio definido por la categoría del mensaje y el código de país del destinatario. Las categorías de plantilla son marketing, utilidad y autenticación; los mensajes sin plantilla son de servicio, y desde el 1 de julio de 2026 existe también Meta Business Agent, para respuestas generadas por la IA de la propia Meta, cobrado a una tarifa global de US$ 2,00 por 1 millón de tokens. Algunos mensajes no se cobran: los enviados dentro de la ventana de punto de entrada gratuito que abren los anuncios Click-to-WhatsApp (puede quedar abierta hasta 7 días; los mensajes de Meta Business Agent se cobran igual dentro de ella) y los primeros 1.000 mensajes de servicio del mes, por número. Desde el 1 de octubre de 2026, las plantillas de utilidad enviadas dentro de la ventana de atención se cobran.

En Brasil, Meta publica la tarifa oficial en reales (BRL), y las cuentas en BRL las factura Facebook Brasil. Valores, tramos de volumen y los cambios de octubre de 2026 están en Precio de la API de WhatsApp en Brasil. Si tus clientes están en otros países, consulta el precio de la API de WhatsApp por país.

Cuándo conviene la API oficial

Compensa cuando WhatsApp es parte del producto o de la operación, y no un canal secundario:

• Sistemas que necesitan notificar a clientes: confirmación de pedido, recordatorio de cita, segunda vía de boleto (el comprobante de pago bancario de Brasil), código de verificación.
• Atención con varias personas o con IA: un número, varios agentes o un agente automático respondiendo, con historial en tu sistema.
• SaaS que ofrece WhatsApp a sus propios clientes: CRMs, ERPs, plataformas de agendamiento y de e-commerce que necesitan conectar números de terceros con seguridad.
• Operaciones que no pueden parar: cualquier flujo en el que el bloqueo de un número sale caro.

Y conviene menos en algunos casos:

• cuando el uso es solo conversación manual, con pocos mensajes al día, y la app WhatsApp Business alcanza;
• cuando el plan depende de enviar mensajes a listas sin consentimiento, algo que la política no permite en ninguna API oficial;
• cuando el flujo depende de funciones que la Cloud API no cubre o cubre con límites. La API de Grupos, por ejemplo, exige una cuenta comercial oficial y admite como máximo 8 participantes por grupo, según la documentación de grupos.

Primeros pasos con Vectalk

1. Crea tu cuenta en apps.vectalk.com.br/register. Se crea una organización automáticamente.
2. En Instancias (Instâncias en la interfaz en portugués), haz clic en Conectar cuenta (Conectar conta en la interfaz en portugués) y completa el Registro insertado (Embedded Signup) de Meta. Vectalk importa el phone_number_id, el waba_id y el token de acceso.
3. En Configuración → API Tokens (Configurações → API Tokens en la interfaz en portugués), genera un token de organización o de instancia. Se muestra una sola vez.
4. Envía el primer mensaje con POST /api/messages y registra un webhook con POST /api/webhooks.

La facturación funciona con mensualidad más saldo prepago: Vectalk coloca su propia línea de crédito en tu número, cada mensaje entregado se descuenta del saldo y no registras tarjeta en Meta. El paso a paso completo está en la guía rápida de la documentación. Para dudas de cuenta y facturación, contáctanos.

Preguntas frecuentes

¿La API oficial de WhatsApp es gratuita?

No. Meta cobra por mensaje entregado, según la categoría y el país del destinatario. Hay casos sin cobro, como la franquicia de 1.000 mensajes de servicio por mes por número y los mensajes dentro de la ventana de punto de entrada gratuito. El intermediario que elijas puede cobrar aparte por su servicio.

¿Necesito un CNPJ para usar la API oficial?

El CNPJ es el registro de empresas de Brasil. Meta exige un portafolio comercial, y la verificación de la empresa pide documentos de la organización. Revisa el servicio de ayuda para empresas de Meta para ver qué documentos se aceptan en tu país antes de empezar.

¿Puedo usar el mismo número que ya uso en el celular?

Si el número está en la app WhatsApp Business, puedes conectarlo a la API sin salir de la app, mediante la coexistencia. Si está en WhatsApp común (Messenger), debes eliminar la cuenta de la app antes de registrar el número en la Cloud API.

¿Cuál es la diferencia entre la API oficial y la app WhatsApp Business?

La app está hecha para uso manual en el celular y la computadora. La API es para sistemas: envío programático, webhooks, varios agentes, integraciones y automatización. La API tiene reglas de plantillas y de ventana de 24 horas que la app no tiene.

¿Cuánto tiempo lleva ponerla en marcha?

La integración técnica suele ser rápida cuando el equipo ya conoce APIs REST. Lo que suele demorar es la parte de Meta: verificación de la empresa y aprobación del nombre visible y de las plantillas. Planifica esas etapas con anticipación.

---

Fuentes oficiales consultadas el 29/10/2026: Precios de WhatsApp Business Platform, Límites de mensajes, Números de teléfono comerciales, Velocidad de envío (throughput), Proveedores de soluciones, Evolución del modelo de cuentas, Marketing Messages API, Grupos, Condiciones del servicio de WhatsApp, Política de mensajería comercial de WhatsApp.