M
MedicIA
Guía de conexión · WhatsApp

Conectá WhatsApp a tu clínica en MedicIA

Una guía clara, paso a paso, para que tu clínica reciba y responda mensajes, mande recordatorios y confirmaciones por WhatsApp — con el bot de MedicIA atendiendo 24/7.

⏱️ 20–30 min 🧩 Cuenta de Meta Business 💳 Tarjeta de crédito 📱 Un número de teléfono

Antes de empezar

WhatsApp para empresas lo provee Meta (la dueña de WhatsApp). MedicIA se conecta a ese servicio. Tené a mano estas tres cosas:

Cuenta de Meta BusinessEn business.facebook.com (gratis).
Un número dedicadoQue nunca haya tenido WhatsApp normal ni WhatsApp Business.
Tarjeta de créditoMeta la exige para enviar. Los primeros 1.000 mensajes/mes son gratis.
Consejo: hacelo desde una computadora, no desde el celular. Vas a copiar y pegar códigos largos y es mucho más cómodo en pantalla grande.
El número tiene que ser dedicado. No puede estar —ni haber estado— en uso en la app de WhatsApp normal ni en WhatsApp Business. Si ese número ya tuvo WhatsApp, primero borrá esa cuenta desde la app (Ajustes → Cuenta → Eliminar mi cuenta) y recién después conectalo acá. Un número que sigue activo en la app de WhatsApp no se puede registrar.
¿Es una línea fija? (en Guatemala, las que empiezan con 2). Sirve igual, pero Meta la verifica solo por llamada de voz (opción “Llamarme”), nunca por SMS —a un fijo el SMS no llega. Tené a alguien junto al teléfono para escuchar el código. Elegir “SMS” en un fijo es el motivo #1 de que el número quede “Pendiente” y no se pueda usar.
1

Crear la app en Meta

developers.facebook.com/apps

La "app" es el puente entre WhatsApp y MedicIA. Se crea una sola vez.

  1. Entrá a developers.facebook.com/apps e iniciá sesión con tu cuenta de Meta.
  2. Clic en “Crear app”.
  3. En “Detalles de la app” ponéle un nombre interno (ej. “Clínica Salud Integral”) y confirmá el correo de contacto. Clic en Siguiente.
  4. En “Casos de uso” elegí “Conectarte con los clientes a través de WhatsApp”, luego tu portfolio/negocio, y finalizá con Crear app.
Meta cambió este flujo: ya no se elige “tipo Empresa”. Ahora primero ponés nombre y después elegís el caso de uso de WhatsApp. Si tu pantalla se ve distinta, buscá el caso de uso de WhatsApp.
developers.facebook.com — Crear app
Pantalla Crear una app en Meta for Developers
Pantalla “Crear una app”: ponéle un nombre. El caso de uso de WhatsApp se elige en el paso siguiente.
Si ya tenías una app creada para WhatsApp, podés reutilizarla y saltear este paso.
2

Agregar WhatsApp y elegir el número

App → WhatsApp → Configuración de la API

Acá conseguís el dato más importante para MedicIA: el Identificador de número de teléfono (Phone Number ID).

  1. En tu app, buscá “Agregar productos” y agregá WhatsApp. Elegí tu portfolio/negocio.
  2. En el menú lateral entrá a WhatsApp → Configuración de la API.
  3. En “De”, seleccioná tu número (o el número de prueba que da Meta).
  4. Copiá el Identificador de número de teléfono 📋 — lo vas a pegar en MedicIA.
  5. Copiá también el Identificador de la cuenta de WhatsApp Business (WABA ID) — es opcional pero conviene tenerlo.
WhatsApp · Configuración de la API
WhatsApp, Configuración de la API con el Identificador de número de teléfono
El Identificador de número de teléfono es el dato clave para MedicIA.
El número de prueba de Meta es gratis 90 días y sirve para probar. Para usarlo en serio con la clínica, conectá un número propio (requiere verificación y el método de pago del paso 3).
Número de prueba vs. número real: el número +1 555… que da Meta es solo para pruebas: no se puede registrar como el número definitivo de la clínica. Para usar un número propio, Meta primero exige verificar tu negocio (Business Verification) y verificar el número con un PIN. Si lo intentás antes, Meta devuelve un error de “objeto no existe / faltan permisos” (ver Problemas comunes).

Verificar el negocio (requisito para abrir el número al público)

Verificar el negocio es lo que habilita que cualquier paciente te escriba (desbloquea el “Acceso avanzado” — ver Abrir el número al público) y sube el límite de envíos (1.000 → 10.000 → ilimitado). Solo podés dejarlo para después si te quedás en modo prueba, que únicamente conversa con números que cargás a mano como destinatarios de prueba (sin verificar, el tope es de ~250 conversaciones por día).

¿Dónde se hace? En Meta → Configuración del negocio → Centro de seguridad → botón “Verifica tu empresa / Empezar”.

¿Qué documentos pide? Meta pide probar dos cosas (normalmente con 1 o 2 archivos):

  1. Que el negocio existe legalmente — cualquiera de: Patente de Comercio / de Empresa (Registro Mercantil), constancia de RTU / NIT (SAT), o escritura de constitución.
  2. La dirección y/o teléfono — factura de servicios reciente (≤90 días) (luz, agua, teléfono, internet) o estado de cuenta bancario, con el nombre del negocio + dirección.
Formato: archivos PDF, JPG o PNG, completos y legibles (no recortados), que se lea el nombre, la dirección y la fecha. A veces Meta verifica automáticamente contra registros públicos y ni pide subir nada: solo confirmás los datos.
Regla de oro: el nombre legal y la dirección que tipeás en Business Manager tienen que coincidir exactamente con lo que dicen los documentos. Si no coinciden, Meta rechaza. El DPI (documento personal) no sirve para verificar el negocio —eso es verificación de persona, que es otra cosa.

Cómo es el trámite, paso a paso:

  1. Tipo de negocio. Tu RTU lo dice: si figura “PERSONA INDIVIDUAL” es una empresa de un solo dueño con nombre comercial → en Meta elegí “Sociedad unipersonal”. Si es una S.A. → “Empresa privada”. Si es un hospital o entidad → “Institución”.
  2. Nombre legal y dirección exactos como en la patente. Ojo: Meta suele precargar la dirección y a veces trae mal el número de calle — corregilo para que coincida con el documento.
  3. Elegí tu negocio de la lista. Meta lo busca en registros públicos y muestra varios candidatos. Elegí el que coincide con tu dirección y tu sitio web — no otro negocio de nombre parecido. Si ninguno es el tuyo, marcá “Mi negocio no aparece” y subí los documentos.
  4. Confirmá la conexión con un código que Meta envía a un email del dominio de tu negocio (p. ej. nombre@tudominio.com) o por teléfono. Puede pedirte resolver un reCAPTCHA.
  5. Enviás y queda “En revisión”. Meta tarda ~2 días hábiles y te avisa el resultado.
3

Agregar método de pago Imprescindible

Configuración de la API → “Agregar método de pago”
Sin método de pago, WhatsApp NO envía mensajes. Meta lo dice textual: “Solo puedes iniciar mensajes desde cuentas de WhatsApp Business que tengan un método de pago vinculado.” Aunque conectes todo lo demás, los envíos van a fallar hasta hacer este paso.
  1. En la misma pantalla de Configuración de la API vas a ver el aviso “Te falta agregar un método de pago”.
  2. Clic en “Agregar método de pago”.
  3. Cargá una tarjeta de crédito o débito válida a nombre de la cuenta de negocio.
  4. Guardá. El aviso debe desaparecer.
Los primeros 1.000 mensajes por mes son gratis. La tarjeta solo se cobra si superás ese límite.
4

Generar el token permanente El paso clave

business.facebook.com → Usuarios del sistema

El token es la “contraseña” que MedicIA usa para enviar por tu WhatsApp. El que aparece en la pantalla de la API es temporal (expira en 24 h) — si usás ese, el bot se cae al día siguiente. Por eso generamos uno permanente, que nunca expira, con un Usuario del sistema.

Token temporal vs. permanente: el temporal (24 h) sirve solo para probar. Para que la clínica funcione de verdad, usá el permanente de este paso.
  1. Entrá a business.facebook.com → Configuración del negocio. (Puede pedirte confirmar tu identidad con una llave de acceso o código de verificación en dos pasos.)
  2. En el menú: Usuarios → Usuarios del sistema → Agregar. (La primera vez te pide aceptar la política de no discriminación: dale Acepto.)
  3. Creá un usuario (ej. “medicia integracion”) con rol Administrador. Usá minúsculas: Meta rechaza nombres con demasiadas mayúsculas seguidas (p. ej. “MedicIA”).
  4. Clic en Asignar activos → elegí tu app → dale control total (Administrar app) → Guardar. (Asigná también la cuenta de WhatsApp / WABA.)
  5. Clic en Generar token nuevo → elegí tu app.
  6. En “Vencimiento del token” elegí “Nunca” (sin vencimiento). ⬅ no te olvides
  7. En permisos, tildá whatsapp_business_messaging y whatsapp_business_management (están al final de la lista).
  8. Clic en Generar token. Puede pedir un código por SMS.
  9. Copiá el token y guardalo en un lugar seguro. Meta no te lo muestra de nuevo.
Configuración del negocio · Usuarios del sistema
Configuración del negocio, Usuarios del sistema
En Configuración del negocio → Usuarios del sistema creás el usuario (rol Administrador) y le asignás la app.
Usuario del sistema · Generar token
Generar token con vencimiento Nunca
Al generar el token, elegí vencimiento “Nunca” y después tildá los dos permisos de WhatsApp.
¿La lista de permisos aparece vacía (“No hay permisos disponibles”) al generar el token? Dos causas, en este orden: (1) Recargá la página (F5) — Meta cachea las asignaciones, así que aunque ya estén hechas el generador sigue vacío hasta el reload. Recargá y reintentá antes de tocar nada. (2) Si tras recargar sigue vacío, falta asignar los dos activos al usuario del sistema: la app (Administrar app) y la cuenta de WhatsApp/WABA (Mensajes + Administrar números y plantillas). Asigná ambos, recargá, y recién ahí “Generar token” muestra whatsapp_business_messaging y whatsapp_business_management.
El token es secreto. No lo compartas por chat ni lo subas a ningún lado. Tratalo como una contraseña.
5

Conectar en MedicIA

MedicIA → Conexiones → Configurar WhatsApp

Ya tenés los datos que MedicIA necesita: el Phone Number ID (paso 2), el token permanente (paso 4) y la Clave secreta de la app (App Secret). Vamos a pegarlos.

  1. En MedicIA, entrá a Conexiones (menú lateral) → tarjeta WhatsApp → “Configurar WhatsApp”.
  2. Avanzá hasta el paso “Agregar WhatsApp y conectar el número”.
  3. Pegá el Phone Number ID en su campo.
  4. Pegá el Access Token (el permanente del paso 4).
  5. Pegá la Clave secreta de la app (App Secret). La sacás en tu app de Meta → Configuración → Básico → “Clave secreta de la app” → Mostrar (Meta te pide tu contraseña de Facebook). MedicIA la usa para validar la firma del webhook de los mensajes entrantes; sin ella, los mensajes de tus pacientes se rechazan y no aparecen en Conversaciones.
  6. (Opcional) Pegá el WABA ID.
  7. Clic en “Verificar y guardar”. Si todo está bien, verás ✓ Conectado.
MedicIA · Conexiones · Configurar WhatsApp
Agregar WhatsApp y conectar el número Phone Number ID 10859•••••2358 Access Token (permanente) EAAJ•••••••••••••••••••••••••• WhatsApp Business Account ID (opcional) 18621•••••1352 Verificar y guardar
Pegá Phone Number ID + token permanente → Verificar y guardar.
Configuración → Básico · Clave secreta de la app
Clave secreta de la app (App Secret) en Configuración → Básico
En Configuración → Básico tocá “Mostrar” junto a la Clave secreta de la app (Meta pide tu contraseña de Facebook) y copiala. MedicIA la usa para validar la firma del webhook de los mensajes entrantes.

Registrar el número (PIN) — pasar de “Pendiente” a “Conectado”

Verificar el negocio, aprobar el nombre y cargar la tarjeta no ponen el número en línea. El número queda en estado “Pendiente” en WhatsApp Manager hasta registrarlo en la nube con un PIN de 6 dígitos. Recién registrado pasa a “Conectado” y puede enviar y recibir.

1) Verificá el correo del perfil (prerrequisito). Si el botón “Activar” de la pestaña “Verificación en dos pasos” del número sale deshabilitado, es porque el negocio no tiene un correo de perfil verificado:

  1. Meta → Configuración del negocio → Información del negocio → sección “Mi información” → Correo electrónico → “Agregar dirección” y confirmá el código que te llega.
  2. Recargá la página (F5) — Meta cachea; el botón “Activar” queda habilitado recién tras el reload.
Información del negocio · Mi información
Captura no disponible — seguí la ruta de menú indicada arriba.
Verificá el correo del perfil en Mi información: sin esto, “Activar” en la verificación en dos pasos sale deshabilitado.
2) Setear el PIN desde Meta da error — es lo esperado. Si intentás definir el PIN directo en la UI de Meta vas a ver “La cuenta no existe en la API de la nube. Usa ‘/register API’ para crear una cuenta.” No es un bug: el PIN no se setea en la UI, se setea al registrar el número.

3) Registrá el número desde MedicIA. No hace falta tocar la API a mano:

  1. En MedicIA → Conexiones, en el wizard de WhatsApp llegá al paso “Registrar número”.
  2. Ingresá un PIN de 6 dígitos y anotalo (Meta lo pide si hay que re-registrar el número).
  3. Clic en “Registrar número”: MedicIA llama a la nube y el número pasa a “Conectado”.
MedicIA · Conexiones · Registrar número
MedicIA, paso Registrar número, campo PIN de 6 dígitos
El paso “Registrar número” del wizard: ingresás el PIN de 6 dígitos y MedicIA hace el registro.
4) Caso línea fija (Guatemala). Si “Registrar número” falla con “número no verificado”, primero completá la verificación de propiedad del número por llamada de voz (opción “Llamarme”) en Meta — a una línea fija el SMS no llega — y reintentá el registro.
5) Cuando el número figure “Conectado” en WhatsApp Manager, ya envía y recibe. Pasá al webhook para que lleguen los mensajes entrantes.
6

Configurar el webhook

Meta → WhatsApp → Configuración → Webhooks

El webhook es lo que hace que los mensajes entrantes de tus pacientes lleguen a MedicIA. Sin esto, podés enviar pero no recibir.

  1. En tu app de Meta: WhatsApp → Configuración → Webhooks → Editar.
  2. Pegá esta URL de devolución de llamada (Callback URL):
Callback URL https://medicia.app/api/webhooks/whatsapp
  1. Pegá el Token de verificación (Verify Token):
Verify Token medicia_dev_2026
El Verify Token debe ser idéntico al configurado en tu servidor de MedicIA (variable WHATSAPP_WEBHOOK_VERIFY_TOKEN). Si tu instalación usa otro valor, pegá ese. Si no estás seguro, consultá a quien administra el servidor.
  1. Clic en Verificar y guardar. Meta hace una prueba y debe dar OK (200).
  2. En “Campos del webhook”, suscribite a: messages, message_status y message_template_status_update.
WhatsApp · Configuración · Webhooks
WhatsApp, Configuración, Webhooks con Callback URL y Verify Token
Pegá la Callback URL y el Token de verificación, y dale a Verificar y guardar.
7

Probar que funciona

Tu teléfono → MedicIA
  1. Desde otro teléfono, mandá un WhatsApp al número que conectaste.
  2. En segundos, la conversación debe aparecer en MedicIA (sección Conversaciones) y el bot responder.
  3. Probá pedir un turno por el chat para ver el flujo completo.
¡Listo! Si el mensaje aparece en MedicIA, la conexión está completa: enviás, recibís y el bot atiende.

Abrir el número al público (de prueba a producción)

Apenas conectás, tu app de Meta arranca en modo prueba: el número solo conversa con teléfonos que cargás a mano como “destinatarios de prueba”. Para que cualquier paciente pueda escribir y el bot responda, hay que pasar a producción. Son 4 cosas, en este orden:

  1. Verificá el negocio (ver Verificar el negocio) — es lo que destraba todo lo demás.
  2. Acceso avanzado al permiso whatsapp_business_messaging. En tu app: caso de uso WhatsApp → Permisos y funciones. Si el permiso dice “Listo para la prueba” está en Acceso estándar (solo prueba); pasalo a Acceso avanzado para que escriba el público.
  3. Poné la app en modo “Live” (no “Desarrollo”), desde el panel de la app.
  4. El número debe quedar “Conectado” (no “Pendiente”): terminá el registro — código de verificación + nombre para mostrar + PIN de 6 dígitos.
¿En qué modo estoy? Si le escribís desde un WhatsApp cualquiera y no llega nada (o solo funciona con tus números de prueba), seguís en modo prueba / Acceso estándar. Cuando los 4 puntos están listos, cualquier número escribe y el bot atiende. La verificación del negocio tarda ~2 días hábiles; el resto es inmediato.

Problemas comunes

“Me rechaza el nombre al crear el usuario del sistema”
Meta no acepta nombres con demasiadas mayúsculas seguidas (p. ej. MedicIA). Usá minúsculas, por ejemplo “medicia integracion”, y vas a poder crearlo.
“Al generar el token la lista de permisos está vacía”
Sale “No hay permisos disponibles” por dos motivos, en este orden: (1) Recargá la página (F5) — Meta cachea las asignaciones, y el generador (e incluso las pestañas “Activos asignados” / “Apps instaladas”) siguen vacíos hasta el reload. Recargá y reintentá antes de re-asignar nada. (2) Si tras recargar sigue vacío, falta asignar los dos activos al usuario del sistema: la app (Administrar app) y la cuenta de WhatsApp/WABA (Mensajes + Administrar números y plantillas). Asigná ambos, recargá, y ahí ya aparecen whatsapp_business_messaging y whatsapp_business_management.
“Me pide una llave de acceso / verificación en dos pasos”
Al entrar a Configuración del negocio Meta puede exigir confirmar tu identidad con una llave de acceso (passkey) o un código de verificación en dos pasos. Es seguridad de Meta, no de MedicIA: confirmalo desde tu teléfono o llave registrada y seguí. La primera vez también te puede pedir aceptar la política de no discriminación (dale Acepto).
“El asistente para crear la app se ve distinto (no aparece ‘tipo Empresa’)”
Meta cambió el flujo: ahora primero ponés nombre + correo y después elegís el caso de uso. Elegí “Conectarte con los clientes a través de WhatsApp” y seguí. El resultado es el mismo.
“El bot funcionaba y de repente se cayó”
Casi siempre es porque se configuró el token temporal (24 h) en vez del permanente. Generá el token permanente (paso 4, vencimiento “Nunca”) y reemplazalo en MedicIA (paso 5).
“No puedo enviar mensajes / fallan los envíos”
Revisá que la cuenta de WhatsApp Business tenga un método de pago vinculado (paso 3). Meta no deja enviar sin tarjeta, aunque uses el tramo gratis de 1.000 mensajes/mes.
“Me da error al registrar el número de teléfono”
Si es un mensaje de “página no disponible, intentá en unos minutos”, suele ser un error temporal de Meta: esperá unos minutos y recargá. Si usás un número propio, además necesita verificarse (Meta te manda un PIN). El número no puede estar en uso en WhatsApp personal.
Error “Unsupported post request… Object with ID … does not exist / missing permissions”
Es un error de Meta (Graph API), no de MedicIA, al dar de alta el número. Las causas más comunes:
  • Estás usando el número de prueba (+1 555…): no se puede registrar como número real — usá un número propio.
  • El número no está bien agregado a tu cuenta de WhatsApp Business (WABA), o pertenece a otra cuenta.
  • Te faltan permisos: tenés que ser administrador del negocio y de la WABA en Meta.
  • Falta la verificación del negocio (Business Verification) en Configuración del negocio.
Para registrar un número real, hacé estos 4 pasos en orden: (1) agregá el número a tu WABA, (2) pedí el código de verificación (SMS o llamada), (3) verificá el número con ese código y (4) registralo con un PIN de 6 dígitos. El error desaparece cuando el negocio está verificado y el número quedó bien dado de alta.
“El número real aparece en gris y no puedo seleccionarlo en ‘De’”
El número está agregado a tu cuenta (por eso aparece en la lista) pero todavía no está registrado/verificado, y Meta solo deja elegir números ya conectados. Andá a WhatsApp Manager → Números de teléfono, abrí ese número y mirá su estado (suele decir “Pendiente” o “Requiere acción”): verificalo con el código (SMS o llamada), completá el nombre para mostrar y el PIN de 6 dígitos. El número no puede estar abierto en la app de WhatsApp mientras tanto. Cuando quede “Conectado”, volvés a la pantalla de la API y ya aparece seleccionable (en negro, tildable). No uses el número de prueba (+1 555…) para la clínica.
Le escribo al número desde otro WhatsApp y me dice “invitar a WhatsApp”
Ese aviso significa que el número todavía no está activo en WhatsApp: sigue en estado “Pendiente” en la API de Meta y por eso no existe como contacto. No se prueba escribiéndole desde tu WhatsApp personal hasta que quede “Conectado”. Pasos: terminá de registrar el número (verificarlo con el código, completar el nombre para mostrar y el PIN de 6 dígitos) en WhatsApp Manager → Números de teléfono hasta que diga “Conectado”. Además, mientras la app esté en modo desarrollo, Meta solo deja conversar con los números que cargaste en la lista de destinatarios de prueba (Meta → WhatsApp → Configuración de la API): agregá ahí el celular desde el que vas a probar, o publicá la app (modo Live) para recibir de cualquier número.
“Solo me escriben mis números de prueba / no me escribe cualquiera”
Tu app está en modo prueba y el permiso whatsapp_business_messaging en Acceso estándar (“Listo para la prueba”): así Meta solo deja conversar con destinatarios de prueba, no con el público. Para abrirlo a cualquier paciente seguí los 4 pasos de Abrir el número al público: verificar el negocio → Acceso avanzado → app en Live → número “Conectado”.
“La verificación del webhook falla”
El Verify Token debe coincidir exactamente con el del servidor de MedicIA (WHATSAPP_WEBHOOK_VERIFY_TOKEN). Verificá que la Callback URL esté bien escrita (https://medicia.app/api/webhooks/whatsapp) y que el servidor esté en línea.
¿Cuánto cuesta?
Crear la app y conectar es gratis. Meta da 1.000 mensajes de conversación por mes sin costo; pasado eso, cobra por conversación según tu país. La tarjeta del paso 3 es para ese excedente.
¿Tengo que repetir esto por cada sucursal?
No necesariamente. El número de la clínica sirve para todo. Si una sucursal necesita su propio número, en MedicIA → Conexiones usás “+ Agregar número para una sucursal” y repetís solo la parte del número + token para esa sede.