Most people know Claude Code as a coding tool in the terminal, but you can connect it to WhatsApp and control it from your phone. Send it tasks, get answers, and keep working on your project when you are away from the computer. In this guide we walk step by step through connecting a Claude Code agent, separately for each project, to a dedicated WhatsApp group, through a service called Green API. We set this up ourselves, including the problems along the way, so you get the fixes too. The guide is written for complete beginners; you do not need to be a developer.
How to connect Claude Code to WhatsApp: the short version
You connect Claude Code to WhatsApp through a service called Green API, without knowing how to code. In short, six steps:
- Create an instance in Green API and link a WhatsApp number with a QR scan.
- Copy the two keys:
idInstanceandapiTokenInstance. - Create a dedicated WhatsApp group for the project and add the bot number to it.
- Find the group's Group ID (an ID ending in
@g.us). - Clear the webhook so you can receive messages in polling mode.
- Run two scripts, listen and send, which Claude Code runs in a loop.
From then on, every message you send in the group reaches the agent, it carries out the task with the full project context, and it replies to your phone, as long as the session is open on the computer.
What to know before you connect (November 2026)
The method in this guide, two scripts and polling against Green API, is still the fastest way to control Claude Code from WhatsApp without a server or a public URL. But after months of running this connection in practice, three points separate a connection that holds from one that quietly fails:
- Keep the session alive. The computer is the brain; if the terminal closes, the agent stops. Run the session inside
tmuxorscreenso it survives a closed window, an SSH disconnect or a locked screen, and you keep controlling it from your phone without touching the computer. - There is now an MCP route too. If you would rather not maintain bash scripts, Green API offers an official hosted MCP server at
https://mcp.green-api.com/mcp, so Claude can send and receive messages through a ready-made tool. It requires an authorized instance in the Green API console. If MCP is new to you, start with our guide to the best MCP servers. - Know when to upgrade. This connection is perfect for personal control of a project. Once the goal is answering real customers at commercial volume, it is no longer the right tool: that is where you move to a server with a permanent webhook or to Meta's official WhatsApp Business Platform. For the bigger picture, see our guide to building an AI agent with Claude.
| What you need | The right route |
|---|---|
| Control one project from your phone | Local polling (this guide) |
| A ready connection without scripts | Green API's MCP server |
| Answering customers at commercial volume | Permanent webhook / WhatsApp Business Platform |
What is Green API?
Green API is a service that connects WhatsApp to any system or script through a simple HTTP API, without the official WhatsApp Business Platform. It works exactly like a Linked Device in WhatsApp: you scan a QR code once, and from that moment you can send and receive messages programmatically. There is a free Developer plan (limited to one instance and 3 chats) and a paid Business plan for ongoing use, billed per instance.
Why connect Claude Code to WhatsApp
Claude Code runs on your computer and knows your whole project: the files, the code, the history. A regular chat does not. The WhatsApp connection gives you a remote control for the agent:
- You are in a meeting and remember a task: send a WhatsApp message, and the agent starts working.
- You are on the road: ask for a status, a fix or a report, and get the answer on your phone.
- Each project gets its own WhatsApp group as a clean, separate control channel.
| Regular AI chat | Claude Code on WhatsApp | |
|---|---|---|
| Knows your project | ❌ | ✅ All files and history |
| Takes real actions (files, code, commands) | ❌ | ✅ |
| Accessible from your phone | ✅ | ✅ |
| Works when the computer is off | ✅ | ❌ (the computer is the "brain") |
One important limitation to understand up front: this works only while the Claude Code session is open on the computer. The computer is the brain, and WhatsApp is just the pipe.
What you need before you start
- A computer with Claude Code installed and running. If not, follow the official setup guide.
- A WhatsApp phone number for the "bot". A number separate from your personal one is recommended, but your personal one also works.
- A free Green API account.
- 15 minutes and a little patience.
Step 1: Open an account and create an instance in Green API
Green API connects WhatsApp to any system through a simple API, without the official business platform. The connection works exactly like a Linked Device in regular WhatsApp.
- Go to console.green-api.com and sign up (free). Official docs: Green API Docs.
- Create a new instance on the Developer plan (free) to start. You can create one Developer instance per account.
- The instance is "the connection". Each project can get its own instance, or you can use the same one with different groups.
Step 2: Link WhatsApp with a QR scan
This is the part that feels like magic:
- Inside the instance you will see a QR code.
- On the bot's phone: WhatsApp → Settings → Linked Devices → Link a device.
- Scan the QR.
- After a few seconds the instance status changes to
authorized. That's it, WhatsApp is connected.
Step 3: Copy the idInstance and API token
Inside the instance there are two keys you will need: idInstance (a numeric ID) and apiTokenInstance (a long, secret string).
An important security warning: these keys are like a password to your WhatsApp. Anyone who holds them can send and read messages. Never publish them on a blog, on GitHub or in a public chat. Below we show how to store them safely.
Step 4: Create a dedicated WhatsApp group
Now create the control channel:
- Create a new WhatsApp group on your personal phone.
- Add the bot number (the one you connected in Green API).
- Give it a clear name based on the project, for example: "Claude dev, my website".
Why a group and not a private chat? A group gives you a clean, isolated channel for each project, and you can add team members later. Ours had exactly two members: you and the bot. On the free plan, keep in mind that the bot can interact with only 3 chats in total.
Step 5: Find the Group ID
Green API does not work with the group name; it needs the Group ID, which looks like this: 120363XXXXXXXXXXXX@g.us.
The easy way to get it is to ask Green API for the contact list. Run this in the terminal (after replacing the two keys with yours):
curl -s "https://api.green-api.com/waInstance$ID_INSTANCE/getContacts/$API_TOKEN"
Find the group in the list by the name you gave it; next to it will be the id ending in @g.us. That is the Group ID. (Tip: you can also just send a message in the group and read the incoming notification, which contains the same ID.)
Step 6: Clear the webhook (critical for receiving messages)
This one caught us by surprise. There are two ways to receive messages from Green API: a webhook (Green API "pushes" every message to a URL on your server) or polling (you "pull" messages yourself with receiveNotification).
To control Claude Code we use polling, and it works only if the webhook field is empty. If you have a webhook set, go to the instance settings and clear the webhookUrl field.
| Method | How it works | When to use |
|---|---|---|
Polling (receiveNotification) | You actively pull messages from Green API | Connecting a local Claude Code, the method in this guide |
| Webhook | Green API pushes every message to your public server URL | When you have an always-on server with a public URL |
Note: after you clear the webhook, it takes Green API a minute or two to apply the change. Until then, receiveNotification returns the error "custom webhook url is set". That is normal; just wait and try again.
Step 7: The send script, send.sh
Start by storing the keys in a separate, secure file. Create ~/.green-api-creds:
ID_INSTANCE=1101234567
API_TOKEN=put-your-token-here
GROUP=120363XXXXXXXXXXXX@g.us
Lock it so only you can read it:
chmod 600 ~/.green-api-creds
Now create the send script send.sh:
#!/usr/bin/env bash
source ~/.green-api-creds
MESSAGE="$1"
curl -s "https://api.green-api.com/waInstance$ID_INSTANCE/sendMessage/$API_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @<(python3 - "$GROUP" "$MESSAGE" <<'PY'
import sys, json
print(json.dumps({"chatId": sys.argv[1], "message": sys.argv[2], "linkPreview": False}))
PY
)
Note "linkPreview": False, which turns off link previews. We found that when it is left on and you send a message with a link, Green API sometimes gets the send queue stuck. A small switch that saves a big headache.
Step 8: The listen script, listen.sh
This script "listens" to the group and returns the next message that arrives:
#!/usr/bin/env bash
source ~/.green-api-creds
BASE="https://api.green-api.com/waInstance$ID_INSTANCE"
while true; do
RESP=$(curl -s "$BASE/receiveNotification/$API_TOKEN")
[ -z "$RESP" ] || [ "$RESP" = "null" ] && { sleep 2; continue; }
RECEIPT=$(echo "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin).get('receiptId',''))")
echo "$RESP" | python3 -c "
import sys, json, os
d = json.load(sys.stdin); b = d.get('body', {})
sd = b.get('senderData', {})
if b.get('typeWebhook') == 'incomingMessageReceived' and sd.get('chatId') == os.environ['GROUP']:
md = b.get('messageData', {})
txt = (md.get('textMessageData') or {}).get('textMessage', '')
print('MSG:', txt)
"
curl -s -X DELETE "$BASE/deleteNotification/$API_TOKEN/$RECEIPT" > /dev/null
done
An important point: after you read a message, you must delete it from the queue with deleteNotification, or you will receive it again and again.
Step 9: Connect everything to Claude Code
Now connect the two scripts to the agent. The idea is simple. Tell Claude Code:
"Run
listen.shin the background, and when a message arrives, carry it out as if I had typed it to you in the chat, and reply to me withsend.sh. Then listen again."
From now on, every message you send in the group triggers the agent. It carries out the task with the full project context and sends you a reply on your phone. Then it goes back to listening, in a loop, for as long as the computer is on. You have turned Claude Code into an agent you control from your pocket.
Security: don't skip this
- Store the keys only in
~/.green-api-credswithchmod 600. Never in the code. - If the project is in Git, add the file to
.gitignoreso it is never committed by accident. - Never send the idInstance or token in any chat, email or public screenshot.
- If you exposed a token by mistake, reset it immediately in the Green API console.
Troubleshooting common problems
- "custom webhook url is set": the webhook field is not empty, or a minute has not passed since you cleared it. Clear it and wait a minute or two.
- Messages are not sent or get stuck: this happened to us. Check that (1) the bot phone is online and WhatsApp is active, since Green API sends only while the linked device is alive; and (2) you are not over the Developer plan limits, especially the 3-chat cap. If you need more, upgrade to the Business plan. You can inspect a stuck queue with
showMessagesQueue. - No messages arrive at all: make sure you sent in the right group (the same Group ID), that the webhook really is empty, and that the group is one of the chats your plan allows.
Key takeaways
- Claude Code plus WhatsApp is a remote control for an agent that knows your project, from anywhere.
- The connection runs through Green API with a single QR scan, no coding knowledge needed.
- You use polling, so the webhook must be empty.
- A dedicated WhatsApp group per project gives you a clean, separate control channel (mind the 3-chat limit on the free plan).
- Store the keys in a locked file (
chmod 600), never in code or in public. - It works only while the session is open on the computer: it is the brain, and WhatsApp is the pipe.
Summary and next step
You connected Claude Code to WhatsApp: you created an instance in Green API, scanned a QR, set up a dedicated group, found the Group ID, cleared the webhook, and built two scripts, send and listen, that the agent runs in a loop. Now you control your project from your phone.
This is just one example of what custom AI agents can do. To go further, explore essential Claude Code skills, the best MCP servers and how to build an AI agent with Claude.
Want your team to build tools like this themselves? Check out my courses and lectures, or talk to me about full AI implementation.
Frequently asked questions
Do I need to know how to code for this?
No. All you need is to copy and paste the commands and scripts in this guide and replace two keys (idInstance and apiTokenInstance) that you get from Green API.
Is it safe?
Green API connects like a regular linked device in WhatsApp. Keep the keys secret: they work like a password, so store them in a locked file and never inside the code. Also keep in mind that this is an unofficial connection, not Meta's WhatsApp Business Platform, so it suits personal control, not mass messaging.
How much does it cost?
Green API's Developer plan is free, but it is limited: one Developer instance, and you can interact with and receive notifications from only 3 chats (contacts or groups). For more chats or ongoing production use, upgrade to the paid Business plan, which is billed per instance.
Can I have a separate group for each project?
Yes, and that is the beauty of it. Each project gets its own WhatsApp group as a clean, separate control channel, and the agent replies with that project's context. On the free plan, remember the 3-chat limit.
Does it work when the computer is off?
No. The Claude Code session on your computer is the brain, and WhatsApp is just the pipe. As long as the session is running on the computer, you can work from your phone.

