Connecting WhatsApp

Connect your Agento agent to WhatsApp so you can chat with it directly from your phone. This guide walks you through linking your WhatsApp account and configuring access control.

How It Works

Unlike Telegram, WhatsApp doesn't have "bot accounts." Instead, the agent links as a companion device on a real phone number — just like WhatsApp Web or WhatsApp Desktop.

When you scan the QR code, the agent becomes another linked device on your number. Anyone who messages that number on WhatsApp will reach the agent, and responses appear to come from that same number.

For example, if you link the agent to +1 415 555 1234:

1. Someone sends a WhatsApp message to +1 415 555 1234
2. The agent receives the message
3. If the sender passes your access policy (allowlist, pairing code, or open), the agent responds using AI
4. The response appears to come from +1 415 555 1234

This means your agent doesn't get its own separate WhatsApp number — it shares the number you link it to. You'll still receive messages on your phone as usual, but the agent can also see and respond to them.

For production use, we recommend linking a dedicated prepaid SIM or eSIM to the agent rather than your personal number. This keeps your personal conversations separate and gives the agent its own identity.

Prerequisites

Before you start, make sure you have:

• An Agento account with a running agent
• A phone number with WhatsApp installed
• A dedicated phone number is recommended — you can use an eSIM or prepaid SIM just for your agent

Using a separate number keeps your personal WhatsApp conversations separate from the agent. Avoid virtual numbers from services like TextNow or Google Voice, as WhatsApp may block them.

Configure Access Control

Before linking WhatsApp, you need to set an access policy that controls who can message your agent.

1. Open the Agento dashboard and click on your agent
2. Go to the Channels tab
3. Find the WhatsApp card and click Configure
4. Choose an access policy:

• Pairing code — new users must enter a one-time code before they can chat with the agent. This is the most common choice.
• Allowlist — only specific phone numbers can message the agent. Enter numbers in international format (e.g. +14155551234).
• Open — anyone who has the number can message the agent.

5. Click Save to apply the policy

Your agent will restart to pick up the new configuration.

Link WhatsApp

Once your access policy is configured, you can link the WhatsApp account:

1. Go to your agent's Channels tab
2. Click Link WhatsApp on the WhatsApp card
3. A QR code will appear in a dialog
4. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device
5. Scan the QR code with your phone
6. Wait a few seconds — you'll see a "WhatsApp linked successfully" confirmation

The QR code expires after about 30 seconds. If it expires, close the dialog and click Link WhatsApp again to generate a new one.

Test the Connection

1. Send a message to the linked WhatsApp number from another phone, or use WhatsApp's "Message Yourself" chat to test with your own number
2. Your Agento agent will respond through WhatsApp

If you're testing with "Message Yourself," make sure your own number is in the allowlist (if using allowlist policy).

If you chose the pairing code policy, the first message from a new user will trigger a pairing prompt. Once paired, the conversation works normally.

Managing Access

You can change the access policy at any time:

1. Go to your agent's Channels tab
2. Click Configure on the WhatsApp card
3. Update the policy or allowlist
4. Click Save — the agent will restart

Access Policies

Policy	Behavior
Pairing code	New users get a one-time code to enter before chatting
Allowlist	Only listed phone numbers can message
Open	Anyone can message the agent

Disconnecting

To disconnect WhatsApp from your agent, unlink from your phone:

1. Open WhatsApp → Settings → Linked Devices
2. Tap the linked device → Log Out

After unlinking, the WhatsApp card on the Channels tab will show Link WhatsApp again when you're ready to reconnect.

Troubleshooting

Agent doesn't respond: Make sure your agent is running (green status on the dashboard). A stopped agent can't process messages.

QR code expired: The QR code is valid for about 30 seconds. Close the dialog and click Link WhatsApp again.

"Link WhatsApp" button is disabled: You need to configure an access policy first. Click Configure and save a policy before linking.

Messages are delayed: This usually means the AI provider is slow to respond. Check your agent's model settings — faster models like Claude Haiku or Gemini Flash will respond more quickly.

WhatsApp shows "Linked device inactive": The agent may have stopped or restarted. Go to the Channels tab and re-link by clicking Link WhatsApp again.

"Connection failed" or link drops immediately: WhatsApp servers occasionally reject connections (error 515 or 1006). This is a temporary WhatsApp-side issue, not a problem with your agent. Wait a minute, then try linking again. If it persists, restart your agent from the dashboard and try once more.

Stale linked device from a previous attempt: If linking fails or the agent was restarted, a stale "Google Chrome (OpenClaw)" entry may remain in your phone's Linked Devices list. WhatsApp thinks there's still an active session, but the agent no longer has matching credentials. To fix this, open WhatsApp → Settings → Linked Devices, tap the stale entry, and Log Out. Then try the Link WhatsApp QR flow again.

Linked device limit reached: WhatsApp allows a maximum of 4 linked devices per account. If you're at the limit, new linking attempts will be rejected (error 515). Remove an unused linked device from WhatsApp → Settings → Linked Devices before trying again.

"Can't link new devices at this time": Multiple failed linking attempts can trigger a temporary cooldown on your phone number. This is a rate limit imposed by WhatsApp, not Agento. Stop retrying and wait 15-30 minutes before attempting again. The cooldown may be longer if you keep retrying during the waiting period.