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.
Each profile can connect its own WhatsApp account. Starting, stopping, or reconnecting one profile's worker does not interrupt another. The account can belong to only one profile across the installation.
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
- keep chats attached to the organization that owns the connected number
- start a new conversation or clear history
- stop an in-progress reply
- receive replies with simple WhatsApp-friendly formatting
Reports and saved files
Ask naturally: “send that file again” or “create the September report in one CSV.”
The agent selects the matching file, or creates the requested output first. It
sends only the selected documents. “Save only” keeps a file without sending it.
/attach resends the most recent saved artifact without an agent reply.
For an existing agent, an admin should open Agent → your agent → Tools and assign list_artifacts so it can find saved files when the conversation no longer contains their names. This shared tool lists only the active workspace's artifacts and also works in other chat channels. New default agents receive it automatically; upgrades preserve existing assignments.
The agent needs its file creation and reading tools to build or inspect reports. Without those tools or source data, it may ask for missing information. Document uploads are limited to 16 MiB. If an upload's delivery is unconfirmed, check the chat before asking to resend it.
Reply formatting
Profiles 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
- Sign in as an organization admin or platform admin
- Select the organization, then open Agent → your agent → Channels → WhatsApp
- Check that you opened the agent you want to connect
- Click Connect WhatsApp
The channel settings route is /profiles/:profileId/channels/whatsapp.
2. Start the bridge
Use the bridge's Start control in Agent → your agent → Channels → WhatsApp. Repeat these steps for another agent with a different WhatsApp account.
3. Link your WhatsApp account
Nakama supports two ways to link:
Option A: pairing code
- In Agent → your agent → Channels → WhatsApp, generate or copy the pairing code
- Open WhatsApp on your phone
- Go to Settings → Linked Devices
- Choose Link with phone number
- Enter the pairing code
Option B: QR code
- Start the WhatsApp bridge
- Wait for the QR code to appear in Agent → your agent → Channels → WhatsApp
- Open WhatsApp on your phone
- Go to Settings → Linked Devices
- Tap Link a Device and scan the QR code
After linking succeeds, Nakama shows the linked account and the bridge can receive messages. The connected owner is automatically paired with that WhatsApp account, so the owner can use the private chat without copying a pairing code. Additional users can still pair in a private chat or be added to Allowed numbers.
Chat behavior
WhatsApp works in private chats and groups.
- direct chats send every message to the agent
- group chats reply to a mention of the linked number, a reply to a Nakama message, or a
/command. Turn off Only reply when mentioned in groups in Agents → your agent → Connections → WhatsApp to answer without a tag - group members who are not paired or in Allowed numbers get no answer unless Reply to unpaired group members is on. Connections that already had the mention switch off keep answering everyone until you turn it off
- each private chat and each group keeps its own Nakama session
- an organization-owned number stays in its owning organization;
/orgcannot switch it to another organization - pairing still happens in a private chat first
- extra numbers in Agent → your agent → Channels → 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
Turning off Only reply when mentioned in groups makes every message an eligible trigger. Use Reply to unpaired group members to allow senders who are not paired or listed under Allowed numbers.
The connection always replies as its owning profile. /new starts a fresh conversation with that same profile.
Commands
Useful WhatsApp commands:
| Command | What it does |
|---|---|
/help | Shows available WhatsApp commands |
/status | Shows server and model status |
/org | Reports the fixed organization |
/clear | Clears the current chat history |
/new | Starts a fresh conversation |
/compact | Compacts the current conversation history |
/stop | Stops an in-progress reply |
/attach | Sends the most recent saved artifact as a WhatsApp document |
Saved artifacts and share links
When your profile saves a file for you with the save-artifact skill, 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).
Only successful artifact saves produce share links or attachments.
Troubleshooting
WhatsApp is enabled but messages do not arrive
Check:
- the Nakama server is running
- the WhatsApp bridge is running in the selected agent's Agent → your agent → Channels → WhatsApp settings
- the WhatsApp account is linked
- the linked number shown in Agent → your agent → Channels → WhatsApp is the one you are messaging from
Pairing code does not work
Check these first:
- generate a fresh pairing code from Agent → your agent → Channels → WhatsApp
- open Settings → Linked Devices → Link with phone number
- 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:
- use Reconnect with QR in Agent → your agent → Channels → WhatsApp
- wait for a fresh QR code
- scan it again from Settings → Linked Devices
The bot does not reply in a group
By default, Nakama only answers in a group when someone:
- mentions the linked WhatsApp number
- replies to a Nakama message
- sends a
/command
Turn off Only reply when mentioned in groups in Agents → your agent → Connections → WhatsApp to answer every group message without tagging the bot.
The sender must be the linked WhatsApp number, or a number listed under Agents → your agent → Connections → WhatsApp → Allowed numbers, unless Reply to unpaired group members is on. Add country code, like +62812…. Reply to another person's message while mentioning Nakama if the agent should see that text.
Check connection ownership
Open Agent → your agent → Channels → WhatsApp for the selected agent. Conversations always belong to this agent. Stop keeps its linked account. Disconnect removes credentials and pairings but keeps chat history. Disconnect before moving the agent to another organization. Cloning or exporting an agent does not copy its connection.
Existing installations
Nakama preserves a linked account when its existing settings identify one owner. An ambiguous connection is different: it stays stopped until it is claimed for an agent through the API (POST /v1/settings/channel-legacy/claim). The dashboard has no claim control. Installation-wide connections require a platform admin. Stop manually launched workers before claiming them.
Running the worker directly
A direct local run needs the organization and profile that own the connection:
NAKAMA_CHANNEL_ORG_ID="org_your_org" \
NAKAMA_CHANNEL_PROFILE_ID="your-profile" \
bun run dev:whatsappSave the connection in the same Nakama config directory first. Set NAKAMA_SERVER_URL and NAKAMA_CONFIG_DIR if you use a separate server or config root.