> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Phone Numbers

> Manage your WhatsApp phone numbers and agent assignments

## Overview

The WhatsApp Phone Numbers page lets you:

* View all connected WhatsApp phone numbers
* Assign inbound chat agents to handle messages
* Register numbers to CLOUD\_API provider
* Add new phone numbers

***

## Viewing Phone Numbers

Navigate to **Dashboard → WhatsApp → Phone Numbers** to see all your WhatsApp numbers.

### Phone Number Table

| Column             | Description                                |
| ------------------ | ------------------------------------------ |
| **Phone Number**   | Your WhatsApp number                       |
| **WhatsApp Agent** | Inbound chat agent assigned to this number |
| **Verified Name**  | Business name verified with WhatsApp       |
| **Platform Type**  | Provider type (`CLOUD_API` or other)       |
| **ID**             | WhatsApp phone number ID                   |
| **Quality Rating** | Meta's quality rating for this number      |
| **Actions**        | Register or status indicator               |

***

## Assigning Inbound Chat Agent

Any inbound WhatsApp message to your number will be answered by the assigned agent.

<Steps>
  <Step title="Ensure CLOUD_API Provider">
    Number must have **Platform Type: CLOUD\_API**

    If not, [register the number](#registering-phone-numbers) first
  </Step>

  <Step title="Click WhatsApp Agent Column">
    Click on the **WhatsApp Agent** cell for your number

    Shows:

    * **"Assign…"** if no agent assigned
    * **Agent name** if already assigned
  </Step>

  <Step title="Select Agent">
    Modal opens with dropdown

    1. Select agent from list
    2. Can search by agent name
    3. Can clear selection to unassign
  </Step>

  <Step title="Save Assignment">
    Click **"Save"**

    Agent is now assigned to handle inbound messages
  </Step>
</Steps>

<Note>
  Only **CLOUD\_API** numbers can have agents assigned. Non-CLOUD\_API numbers show "Register via Actions" instead.
</Note>

### How It Works

**Inbound Message Flow:**

```
WhatsApp User sends message
    ↓
Your WhatsApp Number receives it
    ↓
Assigned Agent responds automatically
    ↓
User receives agent's reply
```

**Use Cases:**

* Customer support via WhatsApp
* Automated FAQ responses
* Lead qualification
* Appointment booking
* Order status inquiries

***

## Registering Phone Numbers

If **Platform Type** is NOT `CLOUD_API`, you must register the number.

<Steps>
  <Step title="Check Platform Type">
    Look at **Platform Type** column

    * ✅ `CLOUD_API` - Ready to use
    * ❌ Other value - Needs registration
  </Step>

  <Step title="Click Register">
    In **Actions** column:

    * Click the cloud upload icon
    * Button shows loading spinner
  </Step>

  <Step title="Wait for Registration">
    Registration process runs

    On success:

    * Platform Type changes to `CLOUD_API`
    * Actions shows ✅ **"Registered"**
  </Step>

  <Step title="Retry if Needed">
    If registration fails:

    * Error toast appears
    * Try clicking register again
    * May need multiple attempts
  </Step>
</Steps>

<Warning>
  Registration may fail occasionally. Simply retry by clicking the register button again until successful.
</Warning>

### After Registration

Once registered as `CLOUD_API`:

* ✅ Can assign inbound chats agent
* ✅ Can use as outbound number in agents
* ✅ Fully functional for WhatsApp messaging

***

## Adding New Phone Numbers

There are two ways to add phone numbers:

### Option 1: Via Callkaro Platform

<Steps>
  <Step title="Click Add Number Button">
    On WhatsApp Phone Numbers page, click **"Add Phone Number"** button
  </Step>

  <Step title="Follow Facebook Flow">
    Meta popup opens

    1. Select or add phone number
    2. Verify via OTP
    3. Complete setup
  </Step>

  <Step title="Number Appears in Table">
    New number added to your numbers list
  </Step>
</Steps>

***

### Option 2: Via Meta Platform

<Steps>
  <Step title="Go to Meta Business Manager">
    Visit [business.facebook.com](https://business.facebook.com)
  </Step>

  <Step title="Navigate to WhatsApp">
    1. Select your App
    2. Go to **Settings → Business Settings**
    3. Click **WhatsApp Accounts**
    4. Select your account
  </Step>

  <Step title="Add Phone Number">
    1. Click **"Add Phone Number"**
    2. Enter number details
    3. Verify via OTP
    4. Complete setup
  </Step>

  <Step title="Sync with Callkaro">
    Number automatically syncs to Callkaro

    Refresh your Phone Numbers page to see it
  </Step>
</Steps>

***

## Using as Outbound Number

To use a WhatsApp number as outbound in an agent:

<Steps>
  <Step title="Ensure CLOUD_API">
    Number must be registered as `CLOUD_API`
  </Step>

  <Step title="Go to Agents Page">
    Navigate to **Dashboard → Agents**

    Or visit: `https://callkaro.ai/dashboard/agents`
  </Step>

  <Step title="Find WhatsApp Outbound Column">
    Locate **"WhatsApp Outbound Number"** column in agents table
  </Step>

  <Step title="Select Phone Number">
    Click dropdown and select your phone number

    **Note:** Only `CLOUD_API` numbers appear in dropdown
  </Step>

  <Step title="Save">
    Agent now uses this number for outbound WhatsApp messages
  </Step>
</Steps>

<Tip>
  Only numbers with **Platform Type: CLOUD\_API** are available for selection as outbound numbers.
</Tip>

***

## Quality Rating

Meta assigns quality ratings to phone numbers based on:

* User feedback
* Message content quality
* Compliance with WhatsApp policies
* Spam reports

### Improving Quality

* Send only relevant, valuable messages
* Get explicit user opt-in
* Respond to user messages promptly
* Avoid spam or promotional overload
* Follow WhatsApp Business policies

<Warning>
  Low quality ratings can lead to reduced messaging limits or account suspension.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion title="One Agent Per Number" icon="user">
    **Recommendation:** Assign one agent per WhatsApp number

    **Why:**

    * Clear conversation ownership
    * Consistent customer experience
    * Easier to track performance
  </Accordion>

  <Accordion title="Register Numbers Immediately" icon="cloud-arrow-up">
    **Action:** Register all non-CLOUD\_API numbers right away

    **Benefits:**

    * Unlock agent assignment
    * Enable outbound messaging
    * Full feature access
  </Accordion>

  <Accordion title="Monitor Quality Ratings" icon="gauge-high">
    **Check regularly:** Review quality ratings weekly

    **If rating drops:**

    * Review recent message content
    * Check for spam reports
    * Adjust messaging strategy
  </Accordion>

  <Accordion title="Use Dedicated Numbers" icon="hashtag">
    **Strategy:** Use different numbers for different purposes

    **Examples:**

    * Support: +91 98765 43210
    * Sales: +91 98765 43211
    * Notifications: +91 98765 43212
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot assign agent" icon="ban">
    **Issue:** WhatsApp Agent column shows "Register via Actions"

    **Cause:** Number is not CLOUD\_API

    **Solution:**

    1. Click register icon in Actions column
    2. Wait for registration to complete
    3. Retry if it fails
    4. Once CLOUD\_API, click WhatsApp Agent cell
  </Accordion>

  <Accordion title="Registration keeps failing" icon="rotate">
    **Issue:** Register button fails repeatedly

    **Solutions:**

    * Wait 1-2 minutes between attempts
    * Check Meta Business Manager for issues
    * Verify number is properly added in Meta
    * Contact Callkaro support if persists
  </Accordion>

  <Accordion title="Number not showing in list" icon="eye-slash">
    **Issue:** Added number doesn't appear

    **Solutions:**

    * Refresh the page
    * Check WhatsApp connection status
    * Verify number added in Meta Business Manager
    * Re-sync by reconnecting WhatsApp
  </Accordion>

  <Accordion title="Cannot select number in agents" icon="circle-xmark">
    **Issue:** Number doesn't appear in agent's outbound dropdown

    **Cause:** Number is not CLOUD\_API

    **Solution:**

    1. Go to WhatsApp Phone Numbers page
    2. Register the number
    3. Return to agents page
    4. Number should now appear
  </Accordion>

  <Accordion title="Quality rating is Low" icon="triangle-exclamation">
    **Issue:** Number has low quality rating

    **Actions:**

    1. Stop sending promotional messages
    2. Only respond to user-initiated messages
    3. Improve message relevance and value
    4. Wait for rating to improve (can take weeks)
    5. If doesn't improve, consider new number
  </Accordion>
</AccordionGroup>

***

## Understanding Platform Types

### CLOUD\_API

**What it is:** Meta's Cloud API for WhatsApp Business

**Features:**

* ✅ Assign inbound chat agents
* ✅ Use as outbound number
* ✅ Full WhatsApp Business API features
* ✅ Reliable message delivery

**This is the required type** for full functionality.

***

### Other Types

**What they are:** On-premises API or legacy setups

**Limitations:**

* ❌ Cannot assign agents
* ❌ Cannot use as outbound
* ⚠️ Limited features

**Action:** Register to convert to CLOUD\_API

***

## FAQs

<AccordionGroup>
  <Accordion title="How many agents can I assign to one number?" icon="users">
    **One agent per number.** Each WhatsApp number can only have one inbound chat agent assigned.
  </Accordion>

  <Accordion title="Can I use same number for multiple agents?" icon="clone">
    **No.** One number = one agent for inbound. But you can use the same number as outbound on multiple agents.
  </Accordion>

  <Accordion title="What happens if I don't assign an agent?" icon="question">
    Inbound messages to that number won't be handled automatically. Users will receive no response.
  </Accordion>

  <Accordion title="How long does registration take?" icon="clock">
    Usually instant (few seconds). May fail and require retry. Rarely takes more than 1-2 attempts.
  </Accordion>

  <Accordion title="Can I delete a phone number?" icon="trash">
    Phone number deletion must be done through Meta Business Manager, not Callkaro dashboard.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="WhatsApp Connect" icon="link" href="/whatsapp/signup">
    Connect your Meta WhatsApp account
  </Card>

  <Card title="Heltar Integration" icon="whatsapp" href="/integrations/heltar">
    Alternative WhatsApp provider
  </Card>

  <Card title="AI Sensy Integration" icon="whatsapp" href="/integrations/aisensy">
    Another WhatsApp provider
  </Card>

  <Card title="Agents" icon="robot">
    Configure your AI agents
  </Card>
</CardGroup>