Nakama

WhatsApp

Use WhatsApp when you want the same Nakama agent available from your phone in a direct chat or group.

The WhatsApp bridge talks to the same Nakama server as the web app and CLI. It is a chat channel, not a separate agent system.

Good use cases

WhatsApp works well for:

  • quick questions while away from your desk
  • using one Nakama profile from phone and web
  • simple direct-chat workflows for one linked number
  • lightweight status checks and short back-and-forth conversations

What WhatsApp can do

With WhatsApp enabled, users can:

  • chat with a Nakama profile in a private WhatsApp chat or a group
  • switch org with commands
  • start a new conversation or clear history
  • stop an in-progress reply
  • receive replies with simple WhatsApp-friendly formatting

Reply formatting

Agents can still write normal Markdown-style replies, but Nakama simplifies them for WhatsApp.

In practice:

  • code fences are flattened to plain text
  • headings are converted to normal text
  • bold and italics are reduced to WhatsApp-friendly formatting
  • long replies are split into smaller chat bubbles

This keeps replies readable in WhatsApp without depending on web-style Markdown rendering.

Setup

1. Enable WhatsApp in Nakama

  1. Open Integrations → WhatsApp in the Nakama web app
  2. Choose which profile should reply
  3. Click Enable WhatsApp

2. Start the bridge

From the repo root:

bun run dev:whatsapp

If the Nakama server is not already running, start it too:

bun run dev:server

Nakama supports two ways to link:

Option A: pairing code

  1. In Integrations → WhatsApp, generate or copy the pairing code
  2. Open WhatsApp on your phone
  3. Go to Settings → Linked Devices
  4. Choose Link with phone number
  5. Enter the pairing code

Option B: QR code

  1. Start the WhatsApp bridge
  2. Wait for the QR code to appear in Integrations → WhatsApp
  3. Open WhatsApp on your phone
  4. Go to Settings → Linked Devices
  5. Tap Link a Device and scan the QR code

After linking succeeds, Nakama shows the linked account and the bridge can receive messages.

Chat behavior

WhatsApp works in private chats and groups.

  • direct chats send every message to the agent
  • group chats reply only to a mention of the linked number, a reply to a Nakama message, or a /command
  • each private chat and each group keeps its own Nakama session
  • /org in a group is stored for that group, not your private chat
  • pairing still happens in a private chat first
  • extra numbers in Integrations → WhatsApp → Allowed numbers can also talk to the agent
  • reply to another group message while mentioning Nakama includes that quoted text in the agent turn

This keeps group chats usable without making Nakama answer every message.

If you change the reply profile, new messages use that profile. Starting a new conversation with /new gives you a fresh session.

Commands

Useful WhatsApp commands:

CommandWhat it does
/helpShows available WhatsApp commands
/statusShows server and model status
/orgLists or switches the active organization
/clearClears the current chat history
/newStarts a fresh conversation
/compactCompacts the current conversation history
/stopStops an in-progress reply
/attachSends the most recent saved artifact as a WhatsApp document

When your agent saves a file for you with the save-artifact skill (content file plus .nakama-meta.json sidecar in the same turn), Nakama posts a Publish-style share link after the reply in WhatsApp.

Opening that link does not require a Nakama login. Anyone who can read the WhatsApp message can open the file until the share is revoked from the dashboard.

To receive the file itself in WhatsApp, ask in plain language — for example, “send the file” or “attach it” — or type /attach. Nakama sends a native WhatsApp document when the file is within the attach size limit. If the file is too large, use the share link instead.

In a WhatsApp group, both the share link and a requested document go to the whole group (same visibility as the bot’s other replies).

Unpaired saves (content without a sidecar in the same turn) do not produce share links or attachments.

Troubleshooting

WhatsApp is enabled but messages do not arrive

Check:

  1. the Nakama server is running
  2. the WhatsApp bridge is running with bun run dev:whatsapp
  3. the WhatsApp account is linked
  4. the linked number shown in Integrations → WhatsApp is the one you are messaging from

Pairing code does not work

Check these first:

  1. generate a fresh pairing code from Integrations → WhatsApp
  2. open Settings → Linked Devices → Link with phone number
  3. paste the latest code exactly as shown

If a code was already used or expired, generate a new one.

QR linking is stuck

If QR linking does not finish:

  1. use Reconnect with QR in Integrations → WhatsApp
  2. wait for a fresh QR code
  3. scan it again from WhatsApp

The bot does not reply in a group

In a group, Nakama only answers when someone:

  1. mentions the linked WhatsApp number
  2. replies to a Nakama message
  3. sends a /command

The sender must be the linked WhatsApp number, or a number listed under Integrations → WhatsApp → Allowed numbers. Add country code, like +62812…. Reply to another person's message while mentioning Nakama if the agent should see that text.

The wrong bot is answering

Open Integrations → WhatsApp and check the Reply as profile. That is the profile the bridge uses for new messages.

Next steps

Troubleshooting

Debug the Nakama Telegram bridge worker and fix common configuration issues.

Discord

Set up Nakama as a Discord bot with pairing, slash commands, and server behavior.

On this page

Good use casesWhat WhatsApp can doReply formattingSetup1. Enable WhatsApp in Nakama2. Start the bridge3. Link your WhatsApp accountOption A: pairing codeOption B: QR codeChat behaviorCommandsSaved artifacts and share linksTroubleshootingWhatsApp is enabled but messages do not arrivePairing code does not workQR linking is stuckThe bot does not reply in a groupThe wrong bot is answeringNext steps