Connect Cue to WhatsApp

Use WhatsApp when you want Cue replies inside your existing WhatsApp account on iPhone, macOS, or WhatsApp Web.

Before You Start

• You need WhatsApp on your phone.
• Cue WhatsApp runtime runs inside the background worker for the target agent.
• WhatsApp setup is split into two steps:
  • non-interactive config with cue whatsapp setup
  • interactive QR device link with cue whatsapp login

Fastest Setup

Replace <agent> with the agent you actually run.

If you already use a local dev agent such as main-localhost, use that same agent here.

cue --agent <agent> whatsapp setup \
  --dm-policy open \
  --json

cue --agent <agent> whatsapp login --json
cue --agent <agent> client restart --json
cue --agent <agent> whatsapp status --json
cue --agent <agent> channel status --provider whatsapp --json

What you want to see:

• whatsapp status shows enabled: true and linked: true
• channel status shows WhatsApp running: true

Step 1: Configure Cue

The setup command is the recommended config path because it:

• writes agent-scoped config
• normalizes phone numbers and chat JIDs
• enables WhatsApp without requiring manual JSON edits

Non-Interactive CLI

Fastest first test:

cue --agent <agent> whatsapp setup \
  --dm-policy open \
  --json

Safer DM allowlist setup:

cue --agent <agent> whatsapp setup \
  --dm-policy allowlist \
  --dm-user +15551234567 \
  --json

Useful follow-up commands:

cue --agent <agent> whatsapp login --json
cue --agent <agent> whatsapp status --json
cue --agent <agent> channel status --provider whatsapp --json
cue --agent <agent> client restart --json
cue --agent <agent> whatsapp logout --disable --json

Equivalent agent.json

If you prefer to inspect or edit the config directly, Cue writes agent-scoped config into ~/.cue/agents/<agent>/agent.json.

Open DM test setup:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dm": {
        "policy": "open"
      }
    }
  }
}

Safer allowlist setup:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dm": {
        "policy": "allowlist",
        "allowFrom": ["+15551234567"]
      }
    }
  }
}

Important: enabled: true alone is not enough. dm.policy and group.policy default to disabled unless you set them.

Step 2: Link WhatsApp

The config step is non-interactive. The device link step is not.

Run:

cue --agent <agent> whatsapp login --json

Then on your phone:

1. Open WhatsApp
2. Go to Settings
3. Open Linked Devices
4. Tap Link a Device
5. Scan the QR code from the terminal

If the QR expires, run cue --agent <agent> whatsapp login --json again.

Step 3: Validate the Runtime

Use these checks:

cue --agent <agent> whatsapp status --json
cue --agent <agent> channel status --provider whatsapp --json

If background mode was already running before you linked the device, restart it:

cue --agent <agent> client restart --json

Step 4: Test Messaging

The simplest DM test is your self-chat:

1. Open Message yourself in WhatsApp
2. Send hello
3. Wait for Cue to reply

Self-chat is the easiest first validation because it does not require a second phone number or a group.

Expected behavior:

• your own messages appear on the right
• Cue replies also appear on the right because they are sent from your linked account
• Cue prefixes self-chat replies such as [Cue] so they are easier to distinguish

Optional outbound test:

cue --agent <agent> channel send --provider whatsapp --to 15551234567 --text "whatsapp outbound test" --json

Group Setup

Start with self-chat first. When that works:

cue --agent <agent> whatsapp setup \
  --dm-policy allowlist \
  --dm-user +15551234567 \
  --group-policy open \
  --json

cue --agent <agent> client restart --json

By default, Cue requires group activation by:

• mentioning your linked WhatsApp account, or
• replying to one of the account's previous messages

Troubleshooting

• whatsapp status shows enabled: true but linked: false: Run cue --agent <agent> whatsapp login --json and scan a fresh QR code.
• channel status says WhatsApp is not running: Run cue --agent <agent> client restart --json. The worker may still be running with old config.
• channel status briefly shows runtime_not_initialized right after restart: Wait a moment and run cue --agent <agent> channel status --provider whatsapp --json again. The worker may still be starting the provider runtime.
• QR expired before linking completed: Start the phone camera inside WhatsApp Linked Devices, then rerun cue --agent <agent> whatsapp login --json.
• Cue replies appear on the right side of WhatsApp: That is expected. Cue sends through your linked WhatsApp account, not through a separate bot identity.
• Self-chat works but group messages do not: Check group.policy, and make sure you mentioned the linked account or replied to one of its messages.