Skip to content
ClinicFlow Docs

WhatsApp Setup Guide

WhatsApp Setup Guide

Section titled “WhatsApp Setup Guide”

Connect a clinic’s phone number to Meta Cloud API so the AI chatbot can receive and send messages.

Prerequisites

Section titled “Prerequisites”
  • A Meta Business Account (business.facebook.com)
  • A phone number not currently registered on WhatsApp (can be a mobile number that receives SMS or voice calls)
  • Admin access to the clinic’s ClinicFlow dashboard

Step 1: Create a Meta App

Section titled “Step 1: Create a Meta App”
  1. Go to developers.facebook.com → My Apps → Create App
  2. Select Business as the app type
  3. Name the app (e.g., “ClinicFlow - Clínica X”)
  4. Link it to your Meta Business Account

Step 2: Add WhatsApp to the App

Section titled “Step 2: Add WhatsApp to the App”
  1. In the App Dashboard → Add Products → WhatsApp → Set Up
  2. Under WhatsApp → Getting Started:
    • Create or select a WhatsApp Business Account (WABA)
    • Note the WABA ID (you’ll need it in Step 4)
  3. Get a temporary access token: WhatsApp → API Setup → Temporary access token
    • This token expires in 24 hours — complete the setup before it expires
    • For production, generate a permanent System User token (Meta Business Settings → System Users)

Step 3: Configure Webhook in Meta App

Section titled “Step 3: Configure Webhook in Meta App”
  1. In your Meta App → WhatsApp → Configuration → Webhook
  2. Set Callback URL: https://api.clinicflow.lat/webhooks/whatsapp
  3. Set Verify Token: the value of your WHATSAPP_WEBHOOK_VERIFY_TOKEN environment variable
  4. Click Verify and Save
  5. Subscribe to the messages field

Step 4: Register the Number in ClinicFlow

Section titled “Step 4: Register the Number in ClinicFlow”
  1. In the clinic dashboard → Configuración → WhatsApp
  2. Enter:
    • WhatsApp Business Account ID: the WABA ID from Step 2
    • Access Token: the temporary (or permanent) token from Step 2
  3. Click Conectar número
  4. Enter the phone number (E.164 format: +503XXXXXXXX)
  5. Choose OTP delivery method: SMS or Voice call
  6. Click Solicitar código OTP

Step 5: Verify OTP

Section titled “Step 5: Verify OTP”
  1. The phone receives a 6-digit OTP from Meta/WhatsApp
  2. Enter the OTP in the dashboard
  3. Click Verificar
  4. Status should update to Activo ✓

If status shows Verificando (verifying), wait 1-2 minutes and refresh — the status auto-heals by polling Meta.

Step 6: Enable the Bot

Section titled “Step 6: Enable the Bot”
  1. In Configuración → WhatsApp, toggle Bot habilitado to ON
  2. Test by sending a WhatsApp message to the clinic’s number
  3. The chatbot should respond with the welcome menu

Troubleshooting

Section titled “Troubleshooting”

Status stuck on “Verificando”

Section titled “Status stuck on “Verificando””

Meta’s number activation can take 1-5 minutes. The dashboard polls /api/whatsapp/status which self-heals verifying → active. If it’s been more than 10 minutes:

  • Check that the OTP was entered correctly
  • Try disconnecting and re-registering
  • Verify the phone number format is correct E.164 (e.g., +50377654321)

Token Expired

Section titled “Token Expired”

Temporary Meta tokens expire in 24 hours. If the chatbot stops working:

  1. Generate a new temporary token (or create a System User for a permanent token)
  2. Update in ClinicFlow: Configuración → WhatsApp → Actualizar token

For production, always use a System User token — these don’t expire.

Bot Not Responding

Section titled “Bot Not Responding”
  1. Check bot_enabled = true in clinic settings
  2. Verify the patient is not is_blocked = true
  3. Check human_handover is not set on the chat session
  4. Check the Meta App webhook subscription is active (messages field subscribed)
  5. Look for errors in Railway logs: POST /webhooks/whatsapp

“Phone number already registered”

Section titled ““Phone number already registered””

The phone number is already connected to a WhatsApp account. You must:

  1. Delete the number from its current WhatsApp account (via the WhatsApp app)
  2. Wait for the deletion to propagate (up to 24 hours)
  3. Then register through ClinicFlow

Webhook Verification Failed

Section titled “Webhook Verification Failed”

Ensure WHATSAPP_WEBHOOK_VERIFY_TOKEN in your .env exactly matches what you entered in the Meta App webhook configuration.

System User Token (Production)

Section titled “System User Token (Production)”

For production, use a System User token that never expires:

  1. Meta Business Settings → System Users → Add
  2. Create a system user with Employee role
  3. Add your WhatsApp app with Full Control
  4. Generate a token with permissions: whatsapp_business_messaging, whatsapp_business_management
  5. Copy the token → update in ClinicFlow Settings