Stop Sharing One Phone: How to Route WhatsApp Chats to Your Support Team

·8 min read
Stop Sharing One Phone: How to Route WhatsApp Chats to Your Support Team

You have a team of five support agents in Karachi or Noida. They are all trying to log into the same WhatsApp Business App on their web browsers. Every hour, someone gets kicked out because of device limits. Customers wait hours for replies because nobody knows who is handling which chat. Someone archives a conversation by mistake, and a hot lead vanishes.

This setup does not scale. If you want to grow, you must move away from the basic WhatsApp Business App and build a proper chat assignment system using the WhatsApp Business Platform (Cloud API).

This is a complete guide to setting up a multi-agent routing system from scratch. We will cover the prerequisites, the technical steps, the routing logic you should use, and how to handle the inevitable errors.

What You Need Before You Start

Do not write a single line of code until you have these four things ready. If you skip these, you will hit a wall halfway through the setup.

  • A clean phone number: This number must not have an active WhatsApp personal or business account. If it does, you must delete that account first. Once you migrate a number to the API, you can no longer use it on the standard mobile app.
  • A Meta Business Manager account: This must be associated with your business. While you can start testing in sandbox mode without verification, you will need a verified business to scale your messaging limits.
  • A server to host your webhook: You need a server running Node.js, Python, or PHP with a public SSL certificate (HTTPS). WhatsApp will not send messages to an insecure HTTP endpoint.
  • An international credit card: Meta bills you directly for API conversations. In Pakistan, make sure your bank has enabled international transactions and internet banking on your card. In India, ensure your card supports RBI-compliant e-mandates for recurring USD payments, or Meta will pause your account within days.

Step 1: Connect to the WhatsApp Cloud API

Go to the Meta for Developers portal at developers.facebook.com. Create a new app and select "Other" as the use case, then choose "Business" as the app type.

Scroll down to the products list and add "WhatsApp". Meta will ask you to link your Meta Business Account. Once linked, they will provide a temporary access token and a test phone number. This is your playground.

To use your actual business number, go to the WhatsApp Setup tab, click "Add Phone Number", and enter your details. You will receive a verification SMS or voice call. Once verified, this number is locked into the API ecosystem.

Step 2: Set Up Your Webhook to Receive Messages

When a customer sends a message to your WhatsApp number, Meta does not store it in an inbox for you. Instead, they send a POST request containing a JSON payload to your server. Your server must listen for this payload, process it, and show it to your agents.

First, write a simple endpoint on your server that handles the GET request for webhook verification. Meta sends a verification request to confirm your server is alive and secure. Your code must read the hub.challenge parameter and return it back as plain text.

Here is what the verification code looks like in Node.js:

app.get('/webhook', (req, res) => {
    const mode = req.query['hub.mode'];
    const token = req.query['hub.verify_token'];
    const challenge = req.query['hub.challenge'];

    if (mode && token) {
        if (mode === 'subscribe' && token === 'YOUR_CHOSEN_VERIFY_TOKEN') {
            res.status(200).send(challenge);
        } else {
            res.sendStatus(403);
        }
    }
});

Once verified, configure your webhook to handle POST requests. When a customer sends a text message, the payload looks like this:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550101234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [{
              "profile": { "name": "Zubair Khan" },
              "wa_id": "923001234567"
            }],
            "messages": [{
              "from": "923001234567",
              "id": "wamid.HBgLOTIzMDAxMjM0NTY3FQIAERgSQjM0NTY3ODkwMTIzNDU2Nzg5MAA=",
              "timestamp": "1672531199",
              "text": { "body": "I need help with my delivery." },
              "type": "text"
            }]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Extract the sender's phone number from contacts[0].wa_id and the message text from messages[0].text.body. Store these in your database.

Step 3: Build Your Assignment Logic

Now that messages are arriving in your database, you need to assign them to your support team. Do not let agents pick their own chats from a giant list. This leads to agents cherry-picking easy questions while complex issues sit unanswered for days.

Use one of these three assignment logics in your backend database:

1. Round Robin Assignment

This is the simplest automated system. You maintain a list of online agents. When a new chat arrives from a user who does not have an open ticket, your system assigns it to the agent who has gone the longest without receiving a new chat.

To build this, create an agents table in your database with fields for id, name, status (online/offline), and last_assigned_at. When a message arrives from a new customer, query your database for the online agent with the oldest last_assigned_at timestamp, assign the chat, and update that timestamp to the current time.

2. Sticky Agent Routing

Customers hate explaining their problems twice. If Zubair spoke to agent Sarah yesterday about a broken router, any new message from Zubair today should go straight back to Sarah.

To implement this, keep a conversations table that links the customer's phone number to an agent_id. When a new message arrives, check if there is an active conversation record for that phone number from the last 72 hours. If yes, route the message directly to that agent's screen. If the agent is offline, fall back to the Round Robin system.

3. Skill-Based Routing Using Interactive Buttons

If you have different teams for Sales and Technical Support, do not guess where the message should go. Use WhatsApp's interactive button messages to let the customer choose.

When a customer sends their first message, reply automatically with a list button message asking: "How can we help you today? 1. Billing, 2. Technical Support". When the customer clicks a button, Meta sends a webhook payload with the button selection. Your routing code reads this selection and assigns the chat to the corresponding agent pool.

Step 4: Manage Agent Availability and Statuses

If an agent goes on a lunch break or leaves for the day, they must not receive new chats. Your system needs an agent status toggle.

Build a simple dashboard where agents can toggle their status between "Online", "Break", and "Offline". When an agent is not "Online", remove them from the assignment pool. If your system attempts to assign a chat to an offline agent, the customer will sit in an empty queue. If all agents are offline, trigger an automated out-of-office message stating your operating hours.

How to Confirm Your Setup is Working

To test your routing pipeline, follow this checklist:

  1. Change your agent status to "Online" in your dashboard.
  2. Send a message from a personal WhatsApp account to your business API number.
  3. Check your server logs to verify that Meta sent a POST request to your webhook and that your server responded with a 200 OK status code.
  4. Verify that the message appears on your agent's dashboard screen and that the database has assigned the chat to your active agent.
  5. Reply to the message from your agent dashboard. Verify that the message arrives on your personal phone within three seconds.

What to Do When Things Fail

Building on top of APIs means dealing with network drops, expired tokens, and configuration errors. Here are the most common points of failure and how to fix them.

The Webhook Verification Fails

If Meta refuses to save your webhook URL, check your SSL certificate. Meta requires a valid, trusted SSL certificate. Self-signed certificates will not work. If you are developing locally, use a tool like Ngrok to create a secure HTTPS tunnel to your local machine. Verify that your verification token matches exactly between the developer portal and your code.

Messages Arrive on Your Server but Replies Do Not Reach the Customer

This is almost always an authentication issue. Check if your Meta temporary access token has expired. Temporary tokens only last 24 hours. For production, you must generate a Permanent System User Token inside your Meta Business Manager under System Users.

Error Code 131030: "Recipient phone number not in allowed list"

This error occurs when your Meta app is still in development mode and you try to send a message to a phone number that has not been added to your developer portal sandbox whitelist. To fix this, either add the phone number to your sandbox test list or go live by completing your business verification and adding a real payment method.

What to Do Next

Once you have basic chat routing running, you need to manage performance. Monitor your First Response Time (FRT) and Resolution Time. If you find writing the webhook parser, managing database state, and building a custom UI from scratch too time-consuming, you can use a pre-built platform.

We at WA Link provide a team inbox built specifically for this. It handles the webhook infrastructure, agent status management, and round-robin routing out of the box, allowing your team to start replying to messages immediately without writing custom code. However, if your business requires deep integration with an in-house database or custom ERP software, building your own routing engine using the steps above is the best path forward.

Frequently Asked Questions

Can I still use the free WhatsApp Business app on my phone after setting up the API?

No. A phone number can only be registered on either the WhatsApp App ecosystem or the Cloud API ecosystem. If you register your number on the API, the mobile app will log you out and refuse to register the number again until you delete your API setup.

What is the 24-hour customer service window?

Meta enforces a strict rule: you can only send free-form messages to a user within 24 hours of their last incoming message. If 24 hours pass without a message from the customer, the session closes. To reopen it, your agents cannot type a manual message; they must send a pre-approved Template Message, which incurs a cost depending on your country.

How much does it cost to route chats through the API?

Meta charges on a per-conversation basis, defined as a 24-hour window. The cost varies based on the category of the conversation (Utility, Marketing, Authentication, or Service) and the customer's country code. You can find the latest exact pricing schedules in your local currency (PKR or INR) on the official Meta WhatsApp API Pricing Page.

Share:WhatsAppFacebookXLinkedIn

Start a free trial