> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp

> Link WhatsApp to Synti with a QR scan and drive the agent from a self-chat or a second phone.

The WhatsApp integration links your account to Synti the same way WhatsApp Web does — you scan a QR code from your phone. Once linked, you can message the agent from a chat with yourself or from another contact. No bot token, no developer account.

## How it connects

Synti links to WhatsApp through a QR-code pairing flow, the same one WhatsApp Web uses. Under the hood it runs Baileys, a WhatsApp Web client, inside an isolated subprocess worker so it stays separate from the main app.

<Warning>
  This is an unofficial connection. Meta may rate-limit or block a linked session at its discretion, and periodically expires inactive linked devices — if that happens, just re-pair.
</Warning>

## Link your account

<Steps>
  <Step title="Open the WhatsApp tile">
    Go to **Settings → Messaging** and click **Connect** on the WhatsApp tile.
  </Step>

  <Step title="Scan the QR code">
    On your phone, open WhatsApp → **Settings → Linked Devices → Link a Device**, then scan the code Synti shows.
  </Step>

  <Step title="Wait for confirmation">
    The dialog confirms success and shows your account name once the link is established.
  </Step>
</Steps>

<Note>
  Linked-device credentials are stored at
  `~/.synti/workspaces/{workspaceId}/messaging/whatsapp-session/`.
</Note>

## Start a conversation

There are two ways to talk to the agent.

<Tabs>
  <Tab title="Self-chat (default)">
    Message your own number in WhatsApp and send `/new` to bind a session. The agent's replies are prefixed with a 🤖 emoji so you can tell them apart from your own messages.

    Self-chat mode is enabled by default and can be toggled under **Settings → Messaging → WhatsApp**. The worker recognizes the newer `lid` (Long-ID) contact format that WhatsApp is rolling out, and filters out its own echoes using the 🤖 prefix and message-ID tracking.
  </Tab>

  <Tab title="Second phone or contact">
    Have another contact send `/new` to your linked number. The agent replies to that contact until they send `/unbind`.
  </Tab>
</Tabs>

## Commands

The core commands you'll use here are `/new` to bind a session and `/unbind` to end it. See the [full command list](/messaging/overview#commands) for the rest.

## Attachments

Photos, documents, voice messages, video, and audio are all supported. Each is stored with its original MIME type and, as on other platforms, capped at **20 MB**.

## Limitations

WhatsApp has no inline buttons and no way to redeem a token through a text reply, which limits a couple of interactive flows:

* **Command approvals.** Prompts to approve actions like running shell commands appear only in the desktop app — the approval channel is fixed to the app on WhatsApp.
* **Plan review.** When a plan is ready, you'll see a text pointer in the chat ("📝 A plan is ready for review"), but you **cannot accept or reject a plan from WhatsApp**. Open the desktop app to act on it.

<Note>
  If Synti is force-quit, the linked session may be lost and any pending outbound replies with it. Inbound messages are held by WhatsApp and delivered once you reconnect.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The QR code won't connect">
    Confirm your phone is online, update WhatsApp to the latest version, then use **Disconnect** and pair again.
  </Accordion>

  <Accordion title="Messages seem delayed">
    Some sync lag between devices is normal. Wait 10–15 seconds or send a test message.
  </Accordion>

  <Accordion title="How do I fully reset the link?">
    The **Disconnect** menu action clears the persisted session and forces a fresh pairing.
  </Accordion>

  <Accordion title="Self-chat stopped working">
    WhatsApp's gradual `lid` migration can require re-binding to your self-chat. Send `/new` again.
  </Accordion>

  <Accordion title="It disconnected on its own">
    Meta expires inactive linked devices from time to time. Re-pair to reconnect.
  </Accordion>
</AccordionGroup>