# Connect your Number {% hint style="warning" %} This is a beta feature {% endhint %} Automate WhatsApp using your own phone number. Send and receive messages as yourself, access your contacts and groups, and build automations that reply on your behalf. ### How this differs from other WhatsApp features CodeWords DM and group automations use shared CodeWords bot numbers. This feature connects your personal WhatsApp number, so messages are sent from you, not a shared bot. ### What you get | Capability | Details | | ---------------- | ------------------------------------------------------------------------------------------------------------------- | | Send messages | Text, images, videos, audio, files, stickers, contacts, locations, and polls | | Read your data | Contacts, groups, recent chats, chat messages, and group participants | | Manage groups | Create groups, add or remove members, promote or demote admins, and update names and descriptions | | Receive messages | Incoming messages are forwarded to your workflow automatically, including messages, reactions, edits, and deletions | | Media | Download images, videos, and audio from messages | ### Setup Connecting usually takes about 30 seconds. You scan a QR code in WhatsApp, similar to linking WhatsApp Web or a new device. 1. Ask Cody, your AI automation assistant, to connect your WhatsApp. Cody generates a QR code. 2. Open WhatsApp on your phone and go to **Settings -> Linked Devices -> Link a Device**. 3. Scan the QR code. It expires in 30 seconds. If it expires, Cody generates a new one. 4. You are connected. Cody confirms the link, and you can start building automations. ### Walkthrough: connect, test, and go live safely Use this quick walkthrough if you are connecting your personal number for the first time. #### Step 1: Connect your number 1. Ask Cody: **"Connect my WhatsApp number."** 2. Scan the QR code from your phone in **Settings -> Linked Devices -> Link a Device**. 3. Wait for Cody to confirm connection. #### Step 2: Verify inbound messages 1. Send a test message from another phone to your WhatsApp number. 2. Confirm your workflow receives the incoming event. 3. If nothing arrives, ask Cody to check that your trigger is active. #### Step 3: Verify outbound replies 1. Ask Cody to send a reply to your test chat. 2. Confirm the message appears in WhatsApp. 3. Test one media message (image, audio, or file) if your workflow uses media. #### Step 4: Start with known contacts 1. Send your first automated messages to people in your contacts or people who already messaged you. 2. Keep initial volume low and increase gradually as replies come in. 3. Avoid cold bulk outreach to unknown numbers from a newly connected account. #### Step 5: Monitor quality signals 1. Track reply rates and blocks/reports. 2. If replies drop or sends start failing, reduce volume and focus on high-intent conversations. 3. Keep message content useful, expected, and personalized. ### Authentication and control CodeWords does not require your WhatsApp password for this setup. Authentication runs through WhatsApp's Linked Devices flow. You can disconnect your number at any time: * In WhatsApp: **Settings -> Linked Devices** * In CodeWords: ask Cody to disconnect it ### What your workflows can access After you connect, your workflows can read and interact with: * **Your contacts** — full contact list with names and phone numbers * **Your groups** — groups you are a member of (up to 500), including participants, descriptions, and settings * **Chat messages** — messages from selected conversations (recent messages only on first sync) * **Media** — images, videos, audio, and documents from messages ### About message history On first connection, WhatsApp syncs only recent messages for each conversation. Your contact list and group list are available right away. Messages received after connection are stored and available to your workflows. If you need full history for a chat, use WhatsApp's **Export Chat** feature in the phone app. ### Example workflows #### 1) Personal AI assistant Build a workflow that listens to incoming WhatsApp messages, processes them with an AI model, and replies automatically. Examples: * A friend asks, "What was that restaurant we talked about?" -> your assistant checks recent chats and replies * Someone sends an image -> your workflow describes the image and sends a summary * You receive a voice note -> your workflow transcribes it and saves it to Google Docs #### 2) Group digest Build a workflow that reads messages from an active WhatsApp group, summarizes key points with AI, and sends a daily digest by WhatsApp or Email. #### 3) Auto-reply while you are busy Set up a workflow that detects incoming messages during specific hours and sends a custom availability reply. You can customize replies by contact or group. ### Limits and important details | Limit | Detail | | ----------------- | ------------------------------------------------------------------------------------- | | Groups returned | Up to 500 (WhatsApp protocol limit) | | QR code expiry | 30 seconds. Request a new one if needed | | Message history | On first connect, only recent messages per chat are synced | | Multiple numbers | You can connect more than one WhatsApp number | | Session stability | Sessions can disconnect during platform maintenance. Re-scan the QR code to reconnect | ### WhatsApp Limits & Restrictions WhatsApp introduced additional anti-spam safeguards that affect messaging behavior: * **Rolling message cap for unanswered messages**: If you send messages that do not get replies, WhatsApp keeps a rolling count. After an internal threshold (not publicly disclosed), sending to new or non-contacts can be temporarily restricted. The cap eases as recipients reply. * **Applies to both personal and business accounts**: This is not limited to the Business API. Regular personal accounts can also be rate-limited for high volumes of unreplied outreach. * **Known vs unknown recipients are treated differently**: Messages to contacts, or to people who previously messaged you, are generally lower risk than cold outreach to strangers. * **No public fixed limit**: WhatsApp does not publish a simple "X messages/day" rule. The limit is behavior-based and adaptive (for example, reply patterns, account history, and trust signals). * **Spam reports and blocks increase risk**: Recipient reports/blocks can accelerate restrictions and may trigger account penalties faster than volume alone. * **Too many new conversations can trigger temporary bans**: Starting a high number of new chats in a short period (especially with unknown recipients) can trigger temporary restrictions, including 24-hour blocks or longer in repeated/high-risk cases. {% hint style="warning" %} Best practice: prioritize opt-in conversations and high reply rates. If your use case involves cold outreach, start small, monitor replies, and avoid repetitive messaging patterns. Always follow WhatsApp's Terms and applicable policies when sending automated messages. {% endhint %} ## Security CodeWords does not store your WhatsApp password. Authentication is handled through WhatsApp's official Linked Devices protocol. Your connected data is private to your workspace. Other CodeWords users cannot access your connected WhatsApp. You can disconnect at any time from your phone or by asking Cody. Messages between your phone and CodeWords are encrypted in transit. ## Beta notice This is a beta feature. If you run into issues, contact . ## What to do next Open a chat with Cody and try one of these prompts: * "Connect my WhatsApp number" * "Build a WhatsApp auto-reply for when I'm busy" * "Summarize my WhatsApp group messages daily" Cody will guide you through connecting your number and building your workflow. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.codewords.ai/automations/whatsapp/whatsapp-automations/connect-your-number.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.