Skip to main content

Channel — WhatsApp Business

The WhatsApp channel lets your customers contact you via their WhatsApp app and get instant responses, 24/7, powered by Aiterava Intelligence.

Prerequisites​

  • A verified Meta Business Suite account: business.facebook.com
  • A dedicated phone number for your WhatsApp Business (not used on a personal account)
  • Your Aiterava instance accessible publicly via HTTPS (for the Meta webhook)
  • The AI_BYOK_MASTER_KEY variable set in your .env (on-premise)

Step 1 — Create a Meta application​

  1. Go to developers.facebook.com.
  2. Click My apps → Create app.
  3. Choose type Business.
  4. Name it (e.g. Aiterava – Hotel Le Palmier).
  5. Under Add products, click Set up next to WhatsApp.

Step 2 — Retrieve your credentials​

In WhatsApp → Getting started of your Meta app:

CredentialWhere to find it
Phone Number ID"Phone numbers" section
WhatsApp Business Account ID (WABA ID)Page header
System User Access TokenMeta Business Suite → Settings → System users
Permanent token

Use a System User Token (from Meta Business Suite → System settings), not the temporary test token that expires after 24h.

Step 3 — Configure the Meta webhook​

  1. In WhatsApp → Configuration, section Webhook, click Edit.
  2. Fill in:
    • Callback URL: https://your-domain.com/api/v1/whatsapp/webhook/
    • Verify token: the value of WHATSAPP_VERIFY_TOKEN in your .env
  3. Click Verify and save.
  4. Subscribe to the messages field.

Step 4 — Environment variables (on-premise)​

Add to your .env:

# ─── WhatsApp channel ────────────────────────────────────────────────────────
WHATSAPP_VERIFY_TOKEN=a-secret-string-of-your-choice
WHATSAPP_APP_SECRET=your-meta-app-secret   # Meta App → Settings → Basic

# Required if not already set
AI_BYOK_MASTER_KEY=<openssl rand -hex 32>

Restart the API:

make restart
# or
docker compose -f docker-compose.onprem.yml restart api celery

Step 5 — Activate in the dashboard​

  1. Log in to the Aiterava dashboard.
  2. Go to Settings → WhatsApp.
  3. Fill in:
    • Phone Number ID
    • WABA ID
    • Display name (what your customers see in WhatsApp)
    • Access Token (System User Token)
  4. Check Enable and click Save.

Step 6 — Test​

In Settings → WhatsApp, click Test connection. Enter your personal WhatsApp number and click Send.

You should receive:

✅ Test Aiterava Intelligence — [Your Establishment] WhatsApp assistant operational.

What the assistant can answer​

The WhatsApp assistant has read-only access to public data:

Customer questionData used
Room availabilityReal-time bookings
Descriptions, ratesAccommodation profile
Services, hours, locationMarketplace profile

The assistant responds concisely (suited for WhatsApp), without markdown (no bold/italic), and in your establishment's configured language.

It cannot make a booking or access private data — it politely invites the customer to contact you directly for those cases.

Troubleshooting​

Webhook fails to verify

  • Make sure WHATSAPP_VERIFY_TOKEN in Meta exactly matches the value in your .env.
  • Make sure https://your-domain.com/api/v1/whatsapp/webhook/ is reachable from the internet.

Messages received but no response

  • Check Celery logs: docker logs aiterava_onprem_celery
  • Make sure the WhatsApp configuration is active (is_active = true) in the dashboard.
  • Make sure the AI provider is configured (valid key with available credits).

Signature error (403)

  • Check that WHATSAPP_APP_SECRET matches the "App Secret" in Meta App → Settings → Basic.

Rate limit (429)

  • The assistant limits to 1 request per 5 seconds per customer. This is normal — burst messages are silently dropped.