Cómo conectar WhatsApp API a tu ISP

Lo que tienes que reunir

Todo el trámite existe para conseguir estos seis datos. Cuando los tengas, se pegan una sola vez en Ajustes › WhatsApp de W-Chat y el número queda operativo.

Requisitos previos

• Un número de teléfono propio que pueda recibir un SMS o una llamada una sola vez, y que no esté activo en ninguna app de WhatsApp.
• Una cuenta personal de Facebook para entrar a las herramientas de Meta. No se publica nada con ella: solo es la llave de acceso.
• Documentos del ISP para la verificación: RUC o registro mercantil y un comprobante con la dirección (planilla de servicios, estado de cuenta bancario o licencia de funcionamiento), con el nombre legal idéntico en los dos.
• Un sitio web y un correo con el dominio del ISP. Meta los usa para corroborar que el negocio existe; con un correo de Gmail la verificación se complica.
• Una tarjeta de crédito o débito internacional para el método de pago de la cuenta de WhatsApp.

Paso a paso

1. Crear el portafolio comercial

   business.facebook.com

   El portafolio comercial (antes “Business Manager”) es tu empresa dentro de Meta: de él cuelgan la app, la cuenta de WhatsApp y el número.

   1. Entra a business.facebook.com y pulsa Crear cuenta.
   2. Pon el nombre legal del ISP, tal como aparece en el RUC, no el nombre comercial. Es el que Meta va a contrastar con los documentos.
   3. Completa dirección, sitio web y teléfono de la empresa.
   4. Confirma el correo de empresa que te llega.

   Si tu ISP ya tiene un portafolio con páginas de Facebook o Instagram, úsalo; no crees uno nuevo.

2. Verificar el negocio

   business.facebook.com › Configuración del negocio › Centro de seguridad

   Sin verificación, Meta limita el número a 250 conversaciones iniciadas por el negocio cada 24 horas, no aprueba el nombre visible y deja fuera las llamadas. Es el paso que más tarda, así que se arranca cuanto antes: el resto de la configuración avanza en paralelo.

   1. Abre el Centro de seguridad y pulsa Comenzar verificación.
   2. Sube los documentos. Que el nombre legal, la dirección y el teléfono coincidan carácter por carácter con lo que pusiste en el portafolio: la mayoría de los rechazos son por una abreviatura distinta (“Cía. Ltda.” frente a “Compañía Limitada”).
   3. Verifica el teléfono o el dominio cuando lo pida.
   4. Espera la resolución: de unas horas a unos días hábiles.
   Se puede seguir mientras tanto

   Con el negocio sin verificar el número ya envía y recibe: solo está topado. Continúa con los pasos siguientes; el límite sube solo cuando Meta apruebe.

3. Crear la app y añadirle WhatsApp

   developers.facebook.com/apps

   1. Entra a developers.facebook.com/apps y pulsa Crear app.
   2. Cuando pregunte qué quieres lograr, elige la opción de mensajería / WhatsApp. Si no aparece, elige el tipo Negocio.
   3. Ponle un nombre reconocible (por ejemplo CRM NombreDelISP) y asóciala al portafolio comercial del paso 1. Este enlace no es opcional: sin él no se puede generar el token permanente.
   4. Ya dentro de la app, en el panel de productos, pulsa Configurar en WhatsApp.

4. Dar de alta el número

   App de Meta › WhatsApp › Configuración de la API

   Al abrir WhatsApp por primera vez, Meta ofrece crear la cuenta de WhatsApp Business (WABA). Créala dentro del mismo portafolio. Meta regala además un número de prueba: no sirve para producción, solo escribe a destinatarios que registres a mano.

   1. En Del número de teléfono, pulsa Agregar número de teléfono.
   2. Nombre visible: el que verán tus clientes en el chat. Tiene que guardar relación con el negocio — Meta rechaza nombres genéricos como “Soporte” o “Ventas”.
   3. Elige categoría y escribe una descripción corta del negocio.
   4. Escribe el número con código de país y verifícalo por SMS o llamada.
   5. Cuando pida un PIN de seis dígitos (verificación en dos pasos), invéntalo y anótalo. Es del número, no de W-Chat, y hace falta si algún día hay que volver a registrarlo o moverlo de proveedor.
   El nombre visible se revisa aparte

   Su aprobación va ligada a la verificación del negocio y al volumen del número. Hasta que se apruebe, los clientes ven el número en vez del nombre. No bloquea nada: W-Chat funciona igual.

5. Copiar los dos identificadores

   App de Meta › WhatsApp › Configuración de la API

   En esa misma pantalla, debajo del selector de número, están los dos identificadores. Cópialos tal cual — son números largos, sin espacios ni signo +:

   • Identificador del número de teléfono → es el ID del número de teléfono de W-Chat.
   • Identificador de la cuenta de WhatsApp Business → es el WABA ID.

   Ojo con no confundirlos con el número marcable (+593…), que es un dato distinto y también se pide.

6. Generar el token permanente

   business.facebook.com › Configuración del negocio › Usuarios del sistema

   El token que muestra la pantalla de la API caduca en 24 horas y solo sirve para probar. El de producción se emite a nombre de un “usuario del sistema”, que es un usuario técnico sin persona detrás, y no caduca.

   1. En Configuración del negocio, abre Usuarios › Usuarios del sistema y pulsa Agregar.
   2. Nómbralo wchat-api y dale el rol Administrador.
   3. Con el usuario seleccionado, pulsa Agregar activos y asígnale, con control total, la app del paso 3 y la cuenta de WhatsApp del paso 4.
   4. Pulsa Generar nuevo token, elige la app y marca estos permisos:
      • whatsapp_business_messaging — enviar y recibir mensajes, y las llamadas;
      • whatsapp_business_management — plantillas y perfil del negocio;
      • business_management — solo si la pantalla lo ofrece.
   5. En caducidad elige Nunca.
   El token se muestra una sola vez

   Cópialo entero y guárdalo antes de cerrar la ventana: empieza por EAAG y es largo. Si lo pierdes no se recupera, hay que generar otro. Trátalo como la contraseña del banco — quien lo tenga puede escribir a tus clientes en tu nombre.

7. Copiar la clave secreta de la app

   App de Meta › Configuración › Básica

   En Clave secreta de la app, pulsa Mostrar, introduce tu contraseña de Facebook y cópiala.

   W-Chat la usa para comprobar que cada mensaje entrante viene de verdad de Meta y no de un tercero que descubrió la dirección del webhook. Sin ella el número funciona, pero pierdes esa comprobación: pásala siempre.

8. Configurar el webhook

   App de Meta › WhatsApp › Configuración

   Aquí es donde le dices a Meta a dónde entregar los mensajes que reciba tu número.

   1. En el bloque Webhook, pulsa Editar.
   2. URL de devolución de llamada:

      https://api.wchatisp.com/api/whatsapp/webhook

   3. Token de verificación: el que te entregó W-Chat, pegado exacto, sin espacios delante ni detrás.
   4. Pulsa Verificar y guardar. Meta llama a esa dirección en el momento; si el token es el correcto, la ventana se cierra sin error.
   5. Vuelve al bloque de webhook, pulsa Administrar y suscríbete a estos campos:
      • messages — mensajes entrantes y acuses de entrega y lectura;
      • calls — llamadas, si vas a usarlas (paso 11).
   El token de verificación te lo damos nosotros

   No lo inventes: si pones uno propio, la verificación falla con 403 y el webhook no se guarda. Pídenoslo antes de llegar a este paso. La clave secreta del paso 7 sí es tuya y propia, y es la que separa tu tráfico del de cualquier otro ISP.

9. Modo activo y método de pago

   App de Meta (barra superior) · business.facebook.com › Cuentas de WhatsApp

   1. En la barra superior de la app, cambia el interruptor de Desarrollo a Activo. En modo desarrollo Meta no entrega webhooks de tráfico real.
   2. En Configuración del negocio › Cuentas › Cuentas de WhatsApp, abre tu WABA y añade un método de pago con una tarjeta internacional.

   Sin método de pago, las plantillas y los mensajes que inicia el negocio dejan de salir en cuanto se agota el cupo gratuito. Las conversaciones que abre el cliente —las respuestas dentro de la ventana de 24 horas— no se cobran, así que el gasto real de un ISP suele ser bajo; pero la tarjeta tiene que estar cargada.

10. Pegar los datos en W-Chat

    W-Chat › Ajustes › WhatsApp

    Este paso lo hace el propietario de la cuenta: los demás roles no ven estos campos. Rellena los seis valores de la tabla del principio, escribe el PIN de seguridad que te dimos y guarda.

    Al guardar, la tarjeta pasa a mostrar el número como conectado. Manda un WhatsApp desde tu celular personal al número del ISP: debe aparecer en la bandeja de Mensajes en pocos segundos. Responde desde W-Chat y comprueba que te llega. Con eso el circuito está cerrado en los dos sentidos.

11. Habilitar las llamadas opcional

    WhatsApp Manager › Números de teléfono › Configuración

    Las llamadas de voz por WhatsApp vienen apagadas de fábrica y no se encienden el primer día. Meta exige antes:

    • el negocio verificado (paso 2);
    • el número con un límite de mensajería de 2.000 destinatarios al día o más, que se alcanza usando el número con normalidad: Meta revisa calidad y volumen cada pocas horas y va subiendo el escalón;
    • el campo calls suscrito en el webhook (paso 8).

    Cumplido eso, en WhatsApp Manager › Números de teléfono abre la configuración del número y activa Llamadas. Si prefieres hacerlo por API, es una sola petición:

    POST https://graph.facebook.com/v20.0/<PHONE_NUMBER_ID>/settings
    
    {
      "calling": {
        "status": "ENABLED",
        "call_icon_visibility": "DEFAULT",
        "callback_permission_status": "ENABLED"
      }
    }

    Sobre cómo se comportan después: para llamar a un cliente hace falta su permiso, y W-Chat lo pide solo con un botón dentro del chat. El permiso caduca, el cliente puede revocarlo y Meta lo retira tras cuatro llamadas seguidas sin contestar. Las llamadas que entran desde el cliente no necesitan permiso de nada.

12. Dar de alta las plantillas

    W-Chat › Campañas · o WhatsApp Manager › Plantillas de mensajes

    Para escribirle primero a un cliente pasadas 24 horas desde su último mensaje, WhatsApp obliga a usar una plantilla aprobada: avisos de corte, recordatorios de pago, confirmación de visita técnica. Con el token del paso 6 ya cargado, W-Chat las envía a revisión desde el propio sistema y muestra el estado.

    La aprobación suele tardar minutos, a veces horas. Se rechazan por prometer cosas que no se cumplen, por parecer publicidad no pedida o por errores de redacción. Las respuestas dentro de la ventana de 24 horas no usan plantilla: se escriben libres.

Comprobación final

• La app de Meta está en modo Activo y asociada al portafolio del ISP.
• El webhook apunta a https://api.wchatisp.com/api/whatsapp/webhook y tiene messages suscrito.
• El token es de usuario del sistema, sin caducidad y con los dos permisos de WhatsApp.
• La cuenta de WhatsApp tiene método de pago cargado.
• En W-Chat, Ajustes › WhatsApp muestra el número como conectado.
• Un mensaje de prueba entra a la bandeja y la respuesta llega al celular.
• La verificación del negocio está aprobada o en revisión.

Cuando algo falla