Connect one conversation

Before pairing

First get a local reply. Keep Ward stopped before using the same messaging account so two installations cannot answer the same conversation.

WhatsApp uses the unofficial WhatsApp Web ecosystem. It can break or carry account-policy risk. Choose an account whose loss you can tolerate during the trial. Nookins also supports Telegram; this initial acceptance path checks WhatsApp.

Review identity and routing

Stop Nookins. Review owner identities in config/owners.yaml, the account in config/channels.yaml, and one owner-only direct route in the selected agent’s YAML. Use your actual account and agent IDs; personal and main are examples. Keep additional routes and automations for later.

For example, config/owners.yaml maps an owner to an identity on the account:

owner:
  display_name: Owner
  identities:
    personal:
      - 15551234567@s.whatsapp.net

config/channels.yaml enables the account:

personal:
  channel: whatsapp
  enabled: true
  sender_roles: {}

In config/agents.d/main.yaml, replace the initial empty routes with:

routes:
  owner_dm:
    account: personal
    conversation: "+15551234567"
    activation:
      mode: all_messages
    access:
      roles: [owner]
      senders: []

The phone number above is a synthetic example: replace it consistently with the intended owner's identity. An all_messages route here applies only to that direct conversation and allowed owner role; do not reuse it for a group without reviewing its activation and access.

Validate and review before applying:

"$NOOKINS_HOME/bin/nookins" config validate
"$NOOKINS_HOME/bin/nookins" config apply --offline --dry-run
"$NOOKINS_HOME/bin/nookins" config apply --offline

Pair or check your account

For a fresh home, with Nookins stopped, pair a new linked device: Pair only in your own session and never share the QR or pairing code. An existing native Nookins account should retain its pairing; inspect its status before attempting a new one.

"$NOOKINS_HOME/bin/nookins" channel whatsapp --account personal auth

The command displays a terminal QR code. To use WhatsApp’s Link with phone number flow, add --phone followed by your phone number.

After starting Nookins again, open a second terminal with the same NOOKINS_HOME:

"$NOOKINS_HOME/bin/nookins" channel whatsapp --account personal doctor --wait

If onboarding left a generated owner placeholder, run "$NOOKINS_HOME/bin/nookins" channel whatsapp --account personal configure-owner after the supervised transport connects. doctor --wait waits up to 30 seconds and reports pairing, connection, import, and reconnect state.

Check a round trip

Send one short message from the intended owner conversation. Expect the intended agent to reply once. Stop and restart Nookins, repeat the health check, and send a second message.

Do not add more conversations until this works. A connected account does not prove that the right agent received the message or that routing is correct.

If behavior is wrong, stop Nookins and preserve both homes before switching back. Messages already sent cannot be undone by a rollback. Report the first failure.