Skip to main content

​
WhatsApp Connection

Kaanha AI supports two ways to connect a WhatsApp number, and every organization uses exactly one of them at a time (Organization.connectionType):
  • Cloud API (default, recommended) — the official Meta Cloud API. Full compliance, template support, and access to all WhatsApp Business features (Flows, Commerce, Product Lists).
  • Kaanha AI Connect — a WhatsApp Web bridge (QR-code linked device) for organizations that can’t or don’t want to go through Meta’s business verification process. Fewer official features, but no WABA approval required.

​
Cloud API — Prerequisites

Before you start, you’ll need:
  • A Meta Business Account — business.facebook.com
  • A WhatsApp Business Account (WABA) — approved by Meta
  • A verified phone number registered in your WABA (only needed if you’re not letting Embedded Signup provision one for you)
The fastest way to connect is Meta’s own one-click OAuth flow — no credentials to copy-paste by hand:
  1. Go to Settings → Cloud API (or the Onboarding Wizard on first login) and click Connect with Facebook
  2. Meta’s Embedded Signup popup opens — log in to your Meta Business account
  3. Select or create a WhatsApp Business Account and phone number inside the popup
  4. Approve the requested permissions
Kaanha AI receives the phone number ID, business account ID, and access token directly from Meta and finishes the connection automatically — including subscribing the webhook for you.

​
Cloud API — Connecting (manual credential entry, fallback)

If you manage your own Meta App directly and prefer not to use Embedded Signup:
  1. Navigate to Settings → Cloud API in your Kaanha AI dashboard
  2. Fill in the following credentials:
  1. Save — connection status shows as a read-only badge (Connected / Not Connected) once your webhook starts receiving events. There’s no separate “Test Connection” button, since Meta doesn’t offer a synchronous connectivity check the same way a database or SMTP connection would.
  2. Configure the Webhook in Meta Business Manager:
    • URL: https://app.kaanha.ai/api/webhooks/whatsapp
    • Verify Token: (the token you set in step 2)
    • Subscribe to events: messages, message_deliveries, message_reads, message_echoes

​
Meta App Permissions Required

Your Meta App must have the following permissions approved:
  • whatsapp_business_messaging
  • whatsapp_business_management

​
Kaanha AI Connect (WhatsApp Web Bridge)

If you don’t want to go through Meta Business verification — or want to use a personal/small-business number without a formal WABA — Kaanha AI Connect links to WhatsApp the same way WhatsApp Web does: by scanning a QR code with your phone.

​
Connecting a device

  1. Go to Settings → Connection and switch connection type to Connect
  2. Go to /connect/authorize (or follow the in-app prompt) and scan the QR code with WhatsApp on your phone (Linked Devices → Link a Device)
  3. Once linked, the device appears under Settings → Connect Devices
You can link multiple devices to one organization — useful for spreading send volume across several numbers, or as failover if one device goes offline. A per-device daily send quota and cold-recipient cap protect against WhatsApp Web bans; devices exhausting their quota are automatically skipped in favor of another linked device.

​
What’s different in Connect mode

  • Templates aren’t submitted to Meta for approval — a “template” is just a saved message sent as plain text through the linked device
  • Groups are supported (WhatsApp groups can be used as a channel, including for chatbot/Ops Agent routing) — not available in Cloud API mode
  • WhatsApp Flows, Commerce Products, and Product Lists are Cloud-API-only features and are not available in Connect mode
  • Broadcasts sent via Connect are deliberately throttled slower with randomized jitter between sends, to keep the linked device’s send pattern looking natural

​
Failover and device strategy

Configure how Kaanha AI picks a device to send from under Settings → Compliance:
  • Primary — always use one designated device, failing over to another only if it goes offline
  • Round-robin — spread sends evenly across all linked devices
  • Hash-by-recipient — the same contact always sends from the same device (keeps a contact’s conversation history from one linked number)

​
WhatsApp Compliance

Kaanha AI enforces Meta’s messaging policies automatically on every message, on both connection modes:
  • Opt-in enforcement — All outbound messages check Contact.optedIn before sending
  • 24-hour window — Template messages required for new conversations or after 24h inactivity
  • Rate limiting — 20 messages/hour per recipient (Meta policy)
  • STOP keyword — Contacts replying STOP / UNSUBSCRIBE are automatically opted out
  • Broadcast safeguards — Frequency cap prevents marketing spam

​
Other Channels

Beyond WhatsApp, Kaanha AI supports SMS (Twilio) and Slack (DM, channel, and bot messages) as unified inbox channels. Configure these at Settings → Channels. Instagram DM was removed from the platform on April 30, 2026.