Skip to main content

WhatsApp Setup

Connect your WhatsApp Business to Orki to let your AI agent handle customer conversations.

Accessing WhatsApp Integration​

  1. Go to Integrations in the sidebar
  2. Click WhatsApp
  3. Click Add Integration (requires Admin or Super Admin permission)

This opens Meta's embedded signup dialog.

Choosing Your Setup Path​

You have two options when connecting WhatsApp:

OptionBest For
Create a WhatsApp Business AccountBusinesses who will reply through Orki only (no phone app needed)
Connect a WhatsApp Business AppBusinesses already using the WhatsApp Business app on their phone

Want to Test First?​

If you don't have a number yet or want to test Orki before adding your real number, choose "Create a WhatsApp Business Account". During setup, you can select Use a test number — Meta provides a free American test number you can use temporarily.

Step 1: Business Portfolio​

First, select or create your Meta Business Portfolio.

Important: Fill in ALL details accurately:

  • Business name (use your real business name, not "test")
  • Website (use your Instagram link if you don't have a website)
  • Business phone number
  • Business address
warning

Meta reviews business accounts. Incomplete or fake details may result in your account being blocked. Use your real business information.

Step 2: WhatsApp Business Account​

Option A: Create a WhatsApp Business Account (API Only)​

Choose this if you want to handle all messages through Orki without using the WhatsApp app on your phone.

  1. Select Create a WhatsApp Business Account
  2. Enter your WhatsApp Business Account details
    • This is different from app details
    • Use a proper business name (not "test" — fake names get banned)
  3. Add your phone number
  4. Verify with OTP
note

Do not select "Use display username only" — this is not supported by Orki yet.

Option B: Connect a WhatsApp Business App​

Choose this if you already have WhatsApp Business app installed and want to use both the app and Orki.

  1. Select Connect a WhatsApp Business App
  2. Enter your phone number (the one with WhatsApp Business app)
  3. Verify with OTP
  4. Scan the QR code with your phone

Step 3: Complete Setup​

Click Next and then Complete on the final screen.

Your WhatsApp integration will appear as a card on the Integrations > WhatsApp page.

Managing Your Integration​

Integration Card​

Each WhatsApp integration shows:

  • Status - Current state of your number (see statuses below)
  • Open in new tab icon - Takes you to business.facebook.com to manage your number
  • Default Agent dropdown - Select which AI agent handles incoming messages
  • Default Handler dropdown - (App connections only) Select who takes over when using the phone app

Phone Number Statuses​

Statuses come directly from Meta and indicate your messaging health:

StatusMeaning
ConnectedActive and can send outgoing messages within your messaging limit
PendingRegistration or connection is not complete yet
FlaggedQuality rating dropped to Low — on track to be downgraded to a lower message tier
RestrictedReached messaging limit — can only reply to user-initiated messages
DisconnectedConnection is offline (token issues or infrastructure changes)
BannedPolicy action enforced by Meta — blocked from sending and receiving

Display Name Review​

After setup, your display name goes under review by Meta. This typically takes 24 hours.

During review:

  • You CAN receive messages
  • You CANNOT send messages

Display Name Guidelines​

Your display name must follow Meta's Display Name Guidelines. Common requirements:

  • Must represent your business accurately
  • No misleading names
  • No generic terms like "Support" or "Customer Service" alone
  • Must match your business documentation
tip

Following these guidelines helps avoid restrictions. Non-compliant names will be rejected.

We strongly recommend getting your WhatsApp Business verified with Meta. This helps:

  • Avoid account bans
  • Increase messaging limits
  • Build customer trust

What You'll Need​

Typically, you'll need to upload:

  • Commercial Registration (CR) documents
  • Business license
  • Other official business documentation

Verification is done through business.facebook.com.

If You Get Banned or Restricted​

If your number is banned or restricted:

  1. Check what caused the issue (display name, quality rating, policy violation)
  2. Fix the underlying problem
  3. Submit an appeal through business.facebook.com
  4. Wait for Meta to re-review

Common causes:

  • Non-compliant display name
  • High block/report rate from customers
  • Policy violations
  • Incomplete business details

Default Handler (App Connections Only)​

If you connected via the WhatsApp Business App, you'll see a Default Handler dropdown.

What is Default Handler?​

This setting controls what happens when someone sends a message from the WhatsApp Business app (your phone):

SettingBehavior
Empty (default)AI continues handling the chat even if you text from the app
User selectedWhen that user texts from the app, the chat automatically transfers to them and AI stops

Why Use This?​

If you don't set a Default Handler and you reply from your phone, both you AND the AI might respond — causing double messages.

We highly recommend selecting a user to avoid confusion. The AI will automatically stop when that person responds from the app.

What If You Want AI to Resume?​

If the AI stops because a human responded, you can assign the chat back to the AI from the Chats page in Orki.

Stopping the AI (Without Deleting)​

If you want to temporarily stop the AI from responding:

  1. Go to Agents
  2. Find the agent assigned to this WhatsApp integration
  3. Disable the agent

This stops the AI without deleting your integration.

Deleting an Integration​

To remove a WhatsApp integration from Orki:

  1. Go to Integrations > WhatsApp
  2. Click delete on the integration card

Important: Deleting from Orki only revokes our access. Your WhatsApp Business Account and phone number still exist on Meta. To fully delete them, go to business.facebook.com.

Integration Limits​

The number of WhatsApp integrations you can add depends on your plan. Check your limits in Settings > Billing.

Next Steps​