Skip to content
Docs

Run a self-hosted AI agent on WhatsApp

Voxos links a WhatsApp Business number as a companion device, so your agent can read and reply to direct and group text messages from your own server.

This guide registers a dedicated number and links it to your agent. WhatsApp decides which numbers can register, and it may change how linked devices work or restrict an account. Use a number you can afford to lose access to, not your personal one.

What you need

Section titled “What you need”
  • A local Voxos stack from the Quick Start.
  • A Twilio or Telnyx number connected to Voxos. Start with the Twilio guide or the Telnyx guide.
  • A phone with the WhatsApp Business app. It stays the primary device and may occasionally need you to link again.

Each Voxos user can link one WhatsApp number. Before buying a number, check which numbers work. A UK Telnyx mobile, for example, needs Verify with a call.

1. Choose how to get the code

Section titled “1. Choose how to get the code”

Open Phone, find WhatsApp linked device, and select your number. Pick the way Voxos should catch the code before you request it:

  • Verify with a call, for a Telnyx number. Voxos answers WhatsApp’s call, presses the digit it asks for, and shows you the spoken code.
  • Verify with SMS, only if the number can receive WhatsApp’s message route.

2. Register the number in WhatsApp Business

Section titled “2. Register the number in WhatsApp Business”

In WhatsApp Business, choose Use a different number if it offers your personal one, then enter the Voxos number and request the code. Keep the Voxos page open. Type the complete code it shows into the app, wait for the app to confirm, and select I entered this code in Voxos.

If the number is already registered, choose It is already registered instead.

Section titled “3. Link Voxos as a device”

Choose QR code or Pairing code in Voxos. In WhatsApp Business, open Linked devices, choose Link a device, and scan the code or use Link with phone number instead. Keep the page open until it shows Number verified and connected.

4. Send it a message

Section titled “4. Send it a message”

Message the number from another phone. The agent set on the phone integration picks it up and replies in the chat. Replies run through the durable run worker, which make up starts for you.

If something goes wrong

Section titled “If something goes wrong”

Work through the WhatsApp entries in Troubleshooting, and read WhatsApp linked device for how setup and sessions work.

Next steps

Section titled “Next steps”

Privacy