Documentation

Complete guide to deploying and using your WhatsApp Claude Agent.

Overview

WhatsApp Claude Agent connects Claude AI to WhatsApp, allowing you to chat with Claude directly from your phone. The agent runs on your own infrastructure (Railway) using your own API keys.

Key features:

Full Claude AI capabilities via WhatsApp
File operations in a configured working directory
Session persistence across restarts
Phone number whitelisting for security
Multiple permission modes for different use cases

Prerequisites

Before you begin, you'll need:

Requirement	Where to Get It
Anthropic API Key	console.anthropic.com
Railway Account	railway.app (free tier available)
WhatsApp Account	Phone with WhatsApp installed

About Costs

Railway's free tier works but may not persist sessions. For reliable operation, the paid tier (~$5/mo) is recommended. Anthropic charges per API usage — see Costs section.

Deployment

Follow these steps to deploy your WhatsApp Claude Agent:

1 Click Deploy Button

Go to the homepage and click the "Deploy on Railway" button. You'll be redirected to Railway to configure your deployment.

2 Configure Environment Variables

Railway will prompt you to enter two required values:

Variable	Value	Example
`ANTHROPIC_API_KEY`	Your API key from Anthropic	`sk-ant-api03-xxx...`
`WHATSAPP_WHITELIST`	Your phone number with country code	`+14155551234`

3 Deploy and Wait

Click "Deploy" and wait approximately 2-3 minutes for Railway to build and start your container. You can watch the progress in the Railway dashboard.

4 Get Your Deployment URL

Once deployed, Railway will provide a public URL like https://your-app.up.railway.app. If you don't see it, go to your project > Settings > Networking > Generate Domain.

5 Scan QR Code

Open the deployment URL in your browser. You'll see a QR code. Scan it with WhatsApp:

Open WhatsApp on your phone
Go to Settings → Linked Devices
Tap "Link a Device"
Point your camera at the QR code

You're Ready!

Once authenticated, you can start sending messages to Claude via WhatsApp.

Environment Variables

Configure your agent's behavior with these environment variables:

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	Yes	—	Your Anthropic API key
`WHATSAPP_WHITELIST`	Yes	—	Allowed phone number(s)
`PERMISSION_MODE`	No	`default`	Claude's permission level
`WORKING_DIRECTORY`	No	`/app`	Directory for file operations
`AGENT_NAME`	No	`Claude`	Custom name for the agent
`MODEL`	No	`claude-sonnet-4-20250514`	Claude model to use
`PORT`	No	`3000`	QR server port

Permission Modes

Control what Claude can do with different permission modes:

Mode	Description
`default`	Claude asks for permission before making changes
`acceptEdits`	Claude can edit files without asking, but asks for other operations
`bypassPermissions`	Claude can perform any operation without asking
`plan`	Claude plans actions but doesn't execute them

Use with Caution

bypassPermissions mode gives Claude full control. Only use this if you understand the implications.

Scanning QR Code

Via Web Page (Recommended)

Open your deployment URL in any browser. The page will show:

"Initializing..." — Waiting for WhatsApp connection
QR Code — Ready to scan
"Connected!" — Successfully authenticated

The page auto-refreshes every few seconds, so you'll see updates automatically.

Via Deployment Logs

Alternatively, view the QR code in Railway's deployment logs:

Go to your Railway dashboard
Click on your deployment
Click "View Logs"
Find the ASCII QR code in the output

Chatting with Claude

Once connected, simply send messages via WhatsApp. Claude will respond to any message from your whitelisted number.

Example Conversations

You: What's the capital of France?
Claude: The capital of France is Paris.

You: Write a Python function to calculate fibonacci numbers
Claude: Here's a Python function for Fibonacci numbers:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

You: Can you help me debug this code? [paste code]
Claude: I'd be happy to help! Looking at your code...

WhatsApp Commands

The agent supports special commands you can send via WhatsApp:

Command	Description
`/session`	Show current session info
`/fork`	Create a branch of the current conversation
`/mode [mode]`	Change permission mode
`/model [model]`	Change Claude model
`/prompt [text]`	Set custom system prompt
`/config`	View current configuration

Troubleshooting

QR code not showing

Wait a moment — the app needs time to initialize
Check deployment logs for errors
Try redeploying the service

QR code expired

QR codes expire after ~60 seconds
Refresh the page or redeploy to get a new one

Bot not responding

Verify your phone number is in WHATSAPP_WHITELIST (with + and country code)
Check that ANTHROPIC_API_KEY is valid
Review deployment logs for errors

Session disconnected

WhatsApp sessions can disconnect periodically
Redeploy to generate a new QR code
Use Railway's paid tier for persistent storage

"Unauthorized" or API errors

Verify your Anthropic API key is correct
Check your Anthropic account has available credits
Ensure the API key hasn't been revoked

Costs

Service	Cost	Notes
Railway (Free tier)	$0/mo	Limited hours, sessions may not persist
Railway (Paid)	~$5/mo	Persistent storage, always-on
Anthropic API	Pay per use	See anthropic.com/pricing

Typical Usage

For casual use (a few conversations per day), expect ~$5-15/month total including Railway and API costs.

Security

What's protected

API Keys: Stored as encrypted environment variables in Railway
Access Control: Only whitelisted phone numbers can interact with the bot
Your Infrastructure: Everything runs on your own Railway account

Best practices

Don't share your deployment URL publicly
Regularly rotate your Anthropic API key
Use default permission mode unless you need more access
Monitor your Anthropic usage for unexpected activity

WhatsApp Terms of Service

Automated WhatsApp usage may violate WhatsApp's Terms of Service. Use at your own risk and avoid high-volume messaging.