WhatsApp Channel

Connect your Moxxy agent to WhatsApp via a bridge.

WARNING

WhatsApp integration uses a third-party bridge and is in Beta. It may have limitations and require periodic re-pairing.

Overview

WhatsApp integration uses Baileys or similar library to connect as a regular WhatsApp user (not a Business API).

Limitations

• Not officially supported by WhatsApp/Meta
• Requires QR code pairing
• May need re-pairing periodically
• Subject to WhatsApp ToS

Setup

Prerequisites

• A phone number for the bot
• Access to scan QR code

Step 1: Initialize WhatsApp Channel

moxxy channel whatsapp --agent default

Step 2: Scan QR Code

A QR code will be displayed in your terminal:

  ┌─────────────────────────────────────┐
  │                                     │
  │    ██████╗ ██╗██╗   ██╗ ██████╗     │
  │    ██╔══██╗██║██║   ██║██╔═══██╗    │
  │    ██████╔╝██║██║   ██║██║   ██║    │
  │    ██╔══██╗██║╚██╗ ██╔╝██║   ██║    │
  │    ██████╔╝██║ ╚████╔╝ ╚██████╔╝    │
  │    ╚═════╝ ╚═╝  ╚═══╝   ╚═════╝     │
  │                                     │
  │     Scan with WhatsApp → Settings   │
  │     → Linked Devices → Link Device  │
  │                                     │
  └─────────────────────────────────────┘

Step 3: Scan with Phone

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices
3. Tap Link a Device
4. Scan the QR code

Step 4: Connected!

Once scanned, the bot is connected and ready to use.

Usage

Direct Messages

Send a message to the connected phone number:

You: Hello bot!

Bot: Hi! I'm your Moxxy assistant. How can I help you?

Group Chats

Add the phone number to a WhatsApp group:

1. Open group info
2. Add participant
3. Enter the bot's phone number
4. The bot will respond to mentions/replies

Triggering Responses

In groups, the bot responds to:

• Messages starting with the bot's number: @1234567890 Hello
• Replies to the bot's messages
• Direct messages

Configuration

Vault Keys

Key	Description
whatsapp_session	Session data (auto-managed)
whatsapp_trigger_prefix	Prefix to trigger bot in groups

Session Persistence

WhatsApp session is stored in:

~/.moxxy/agents/default/whatsapp_session/

This allows reconnection without rescanning.

Features

Text Messages

Send and receive text messages:

You: What's the weather?

Bot: Let me check the weather for you.
The current weather is sunny, 72°F.

Media Support

Receiving:

• Images
• Documents
• Voice notes

Sending:

• Images
• Documents

You: Send me the report

Bot: Here's the report:
[Attachment: report.pdf]

Voice Messages

Voice messages can be transcribed:

[Voice message received]
Bot: I received your voice message saying "remind me to call John tomorrow".
I've set a reminder for you.

Troubleshooting

QR Code Not Displaying

1. Ensure terminal supports ANSI colors
2. Try a different terminal emulator
3. Check if terminal size is large enough

Session Expired

Error: Session expired, please re-pair

1. Run setup again:

   moxxy channel whatsapp --agent default

2. Scan the new QR code
3. Previous session is invalidated

Rate Limited

Error: Rate limited by WhatsApp

1. Reduce message frequency
2. Wait before sending more
3. Avoid spamming

Banned Number

Error: Account temporarily banned

1. Wait for ban to expire
2. Use a different number
3. Follow WhatsApp ToS

Not Receiving Messages

1. Check internet connection
2. Verify session is active:

   moxxy logs | grep -i whatsapp

3. Try re-pairing

Security Considerations

Account Security

• Use a dedicated phone number for the bot
• Don't use your personal WhatsApp account
• Keep session data secure

Privacy

• Messages are processed by Moxxy
• Don't share sensitive information
• Consider data retention policies

ToS Compliance

• Follow WhatsApp Terms of Service
• Don't spam users
• Respect opt-out requests
• Don't automate bulk messaging

API Reference

Send Message

curl -X POST http://localhost:17890/api/agents/default/whatsapp/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "1234567890",
    "text": "Hello from Moxxy!"
  }'

Send Image

curl -X POST http://localhost:17890/api/agents/default/whatsapp/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "1234567890",
    "image": {
      "url": "https://example.com/image.jpg"
    },
    "caption": "Check this out!"
  }'

Send Document

curl -X POST http://localhost:17890/api/agents/default/whatsapp/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "1234567890",
    "document": {
      "url": "https://example.com/doc.pdf"
    },
    "filename": "report.pdf"
  }'

Best Practices

Professional Use

• Inform users they're chatting with a bot
• Provide clear value
• Don't spam

Error Handling

• Handle rate limits gracefully
• Implement retry logic
• Log errors for debugging

Session Management

• Keep session data backed up
• Handle re-pairing smoothly
• Monitor connection status

Alternatives

For production WhatsApp integration, consider:

WhatsApp Business API

Official API from Meta:

• Verified business accounts
• Higher message limits
• Better reliability
• Official support

Third-Party Services

• Twilio WhatsApp API
• MessageBird
• WATI

These provide:

• Managed infrastructure
• Official compliance
• Better support
• Higher costs