ViksaAIDocs
Start now

WhatsApp setup

Connect WhatsApp Business Cloud API so approved phone numbers can message your project's agents.

Use cases#

  • Customer support from any phone — no app install required
  • Field ops alerts and agent-driven checklists via WhatsApp
  • Approved partners querying status agents from mobile

Prerequisites#

  • Meta Business app with WhatsApp product enabled
  • WhatsApp Business phone number and Phone number ID
  • System User access token with whatsapp_business_messaging permissions
  • At least one deployed agent in your ViksaAI project

Installation steps#

  1. 1

    Create or configure a Meta app

    In Meta for Developers, create an app with the WhatsApp use case. Connect a WhatsApp Business Account and phone number under WhatsApp → API Setup. Copy the Phone number ID and WABA ID.

  2. 2

    Copy the App secret

    In your app go to App settings → Basic, click Show next to App secret, and copy the value into Channel Hub. Volt uses it to verify X-Hub-Signature-256 on inbound webhooks. Meta docs — Basic settings

  3. 3

    Generate a permanent access token

    Do not use the temporary token from API Setup (it expires in ~24 hours). Create a System User token instead:

    • Meta Business settings → Users → System users → Add (Admin role)
    • Add assets: your Meta app (Full control) and WhatsApp Business Account (Full control)
    • Generate token with whatsapp_business_messaging, whatsapp_business_management, and business_management
    • Copy the token once — paste into Channel Hub Access token

    Meta — WhatsApp get started (Step 5)

  4. 4

    Configure the webhook

    Callback URL: https://api.viksaai.com/v1/webhooks/meta

    Set a strong Verify token (min 8 characters) — use the same value in Channel Hub. Subscribe to messages on whatsapp_business_account.

  5. 5

    Connect in Channel Hub

    Volt → Channel Hub → WhatsApp. Paste access token, phone number ID, app secret, and verify token. Click Validate then Connect.

  6. 6

    Grant access

    Open Access. Use Allow all users (*) with selected agents, or add grants with sender phone in E.164 format (e.g. +14155551234). See Access & security.

  7. 7

    Test

    From an allowed phone, send a plain text message to your WhatsApp Business number. Replies use the same Volt agent pipeline as Slack.

Credentials reference#

FieldRequiredWhere in Meta
Access tokenYesBusiness settings → System users → Generate token (not the temporary API Setup token)
Phone number IDYesApp Dashboard → WhatsApp → API Setup
App secretYesApp settings → Basic → App secret (Show)
Verify tokenYesYou choose — must match Meta webhook verify token
WABA IDNoWhatsApp → API Setup → WhatsApp Business Account ID

Message flow#

  1. User sends a message on the channel.
  2. The platform posts a webhook to volt-engine-service at /v1/webhooks/*.
  3. Engine resolves account, org, and project from the global routing index (App ID, phone number ID, tenant key, etc.).
  4. Access is checked via channel_grants_v1 and optional Viksa project membership.
  5. The same Think→Act→Observe pipeline loads your project agent catalog and runs agents.
  6. The reply is sent back through the channel API (Graph, Telegram Bot API, Bot Framework, etc.).

Pilot limitations#

  • Media (images, audio, video, documents)
  • WhatsApp template / proactive messages outside the 24-hour session window
  • Instagram/WhatsApp story mentions and reactions

Troubleshooting#