How to connect Claude Code to your WhatsApp business number

What you need

• Claude Code installed and signed in on your computer. Anthropic's Claude Code docs explain how to install it.
• A Spaces account. The Free plan starts when you connect a chat account, with no card needed.
• Your business WhatsApp number, and the phone it lives on to scan a QR code.
• A folder on your computer for this work, with a short notes file about the business: what you sell, prices, hours and what you never want promised.
• If you want Claude Code to keep listening, a computer that stays on and awake during the hours you want covered.

Step 1: connect your WhatsApp account to Spaces

You scan a QR code with the phone that has the number, the same way you would link WhatsApp on a computer. Your account stays yours, and you keep using it on your phone as normal.

Once it is connected, the account shows in your Spaces dashboard. Connecting does not send anything. It only means Spaces can read and send on that account when an AI agent you have added asks it to.

Use the number your customers already know, ideally one with a real history of conversations. On WhatsApp, new chats wait up to 24 hours after you connect, then warm up over four weeks. Replies to customers who message you go out from day one.

Step 2: add Spaces to Claude Code

1. Run the command below once. Add --scope user to use Spaces in every project.
2. In Claude Code, type /mcp, pick spaces and sign in to Spaces in the browser.
3. Approve the access Spaces asks for. No key is pasted anywhere.

claude mcp add --transport http spaces https://api.spacesos.com/mcp

To check it worked: Run claude mcp list. Spaces shows as connected, and /mcp lists its tools.

Prefer an API key? Add it as a header instead of signing in.

claude mcp add --transport http spaces https://api.spacesos.com/mcp --header "Authorization: Bearer spc_live_…"

You sign in on Spaces' own page during this step, so Claude Code never sees your WhatsApp login or your Spaces password. If Spaces does not show up:

• Check the address is exactly https://api.spacesos.com/mcp, with nothing added at the end.
• Run the sign-in step again, in case the first sign-in in the browser did not finish.
• Restart Claude Code so it reads the new settings.
• If it still does not appear, the Claude Code MCP docs have the current steps, and our Claude Code setup page has ours.

Step 3: try it

Open a terminal in the folder with your notes file, start Claude Code and ask in plain words. Start with requests that only read:

• List my Spaces accounts and tell me which one is WhatsApp.
• Show me the WhatsApp chats from today that are still waiting for a reply.
• Draft replies to the quote requests using notes.md, and show me before sending anything.
• Which customers asked about end-of-tenancy cleans this week?

Start with a question that only reads, like the first one. It shows you that Claude Code can see your WhatsApp messages before you let it send anything. Then try a draft, read it carefully, and only then let it send.

Good to know

Unlike Claude on the web, Claude Code can keep running without you starting each conversation. That means it can answer a customer at 10am while you are on a job. It also means it can send while you are not watching, so build trust in stages: read, then draft, then send the simplest replies.

Claude Code asks you to approve tool calls unless you tell it otherwise. Leave that on while you are getting started. Each time it wants to send a WhatsApp message, you see what it is about to send and can say no.

A Spaces routine is a different thing. It is not an AI. It sends a reply you wrote in advance when something happens, such as a new message after hours. Routines run on Spaces itself, so they keep working when your computer is off.

Claude Code or Claude in the browser?

Both are made by Anthropic and both write well. The difference is where they run and whether they wait for you.

If you never open a terminal and do not want to, Claude in the browser does the same WhatsApp job in sessions you start. Our guide to connecting Claude to WhatsApp covers that route.

Where to keep your business facts

Keep the facts customers ask about in your Spaces business brief: hours, prices and links, common questions, tone, the things never to promise and when to hand a chat to you. Every AI agent you connect reads the same brief, so if you later add a second agent, it already knows your prices. You can ask Claude Code to set it up for you: it asks a few short questions and saves your answers with set_business_brief.

Keep the working rules for Claude Code itself in a notes file in its folder. That is where you say how it should behave: what to send, what to draft, and what to leave alone. Here is an example you can copy and change:

# notes.md: how to handle WhatsApp for Brightside Cleaning
Read the Spaces business brief before every reply. Never contradict it.
Listen with wait_for_events. Never check the chat list in a loop.
Quote requests: ask for the postcode, number of bedrooms and preferred day. Never give a final price.
Regular clients rebooking: draft a reply, do not send.
Complaints, damage, keys and refunds: do not reply. Hand the chat to me and tell me in the terminal.
Hours for replies: 8am to 6pm, Monday to Saturday. Outside those hours, do nothing.
If Spaces refuses a send, wait for the time it gives. Never reword a message to get round a limit.

Notice the line about hours. Spaces does not let you set working hours on an account, so if you only want replies during the day, say so in the notes, or stop Claude Code in the evening.

A worked example: a morning of quote requests

Here is how a morning might go for a small domestic cleaning company. Claude Code is running in a terminal on the office computer, and the owner checks it between calls. Names and details are examples.

Two things made this go well. The price came from the brief, so Claude Code did not have to guess. And the notes told it to step back the moment damage came up, so the owner handled the delicate part personally, from the phone, in the same chat.

Listening for new messages the right way

An agent that keeps running needs a way to hear about new messages. Ask it to call wait_for_events, which waits until something new arrives and returns it at once, then to call it again with the next_cursor it was given. Checking the chat list over and over looks like a bot to the platforms, and wait_for_events does not touch the platform at all.

You can give Claude Code that instruction in plain words when you start it, or keep it in the notes file. A good opening request looks like this:

Read notes.md and my Spaces business brief.
Then call wait_for_events for WhatsApp messages and keep listening.
For each new customer message, draft a reply and show it to me before sending.
Skip messages I sent myself. Stop if I type "stop".

If Claude Code ever starts calling list_messaging_chats over and over instead, stop it and point it back at wait_for_events. Repeated checks are exactly the pattern that makes an account look automated.

Drafts first: holding replies until you approve them

Ask your AI agent to hold replies as drafts, and nothing goes out until you approve it. In Spaces this is a setting your AI agent changes for you, using set_approvals: it can hold every message, only posts, or nothing. While replies are held, you ask Claude Code to list them, then approve or reject each one.

If anything ever goes wrong, pause all sending in Spaces under Settings, then Pause everything. Reading keeps working, so Claude Code can still tell you what is coming in.

WhatsApp rules Spaces keeps to

• A new chat only goes to someone who has messaged your number before, or whom you marked as opted in on the Accounts page.
• The first message to someone new is plain text, with no links, photos, files or voice notes.
• New chats and follow-ups go out between 8:00 and 21:00 local time. A reply to someone who wrote in the last two hours goes out at any time.
• Anyone who says stop, unsubscribe or similar, in English, French or Spanish, is never messaged again from that number.
• The same or nearly the same message goes to at most 2 new people a day, so your agent writes each first message for the person it is going to.

When Claude Code hits one of these, Spaces refuses the send and says why, often with a time to try again. Nothing goes out early. Tell Claude Code to wait for that time rather than retry straight away.

What if...

• Your computer goes to sleep at lunchtime? Claude Code stops with it. Messages wait in WhatsApp as normal, and wait_for_events picks them up when it starts again, from where it got to.
• A customer asks for a time slot? Spaces does not connect to booking systems. Keep the free days in your notes, or set Claude Code up with your diary's own tools separately.
• A customer sends a voice note? Spaces can fetch the attachment for Claude Code. How well it handles audio depends on your set-up, so check those replies yourself.
• You want to take over a chat? Ask Claude Code to hand it to you, and it stops replying there until you hand it back.
• You want replies at night too? Leave the computer on and Claude Code running, or let a Spaces routine send a set holding reply after hours.

Common mistakes to avoid

• Turning off tool approvals on the first day. Keep them on until the drafts are right.
• Putting prices in the notes file and the brief, then updating only one. Keep customer facts in the brief.
• Checking for messages in a loop instead of using wait_for_events.
• Pasting an API key into a file that gets shared or backed up somewhere public. Sign in through /mcp instead.
• Asking Claude Code to message every past customer about an offer. WhatsApp's terms prohibit bulk messaging, and Spaces refuses the same text to many new people.

Summing up

With Spaces, Claude Code can read your business WhatsApp and reply from your own number, and it can keep listening while you work. Add it with one command, keep customer facts in the business brief and working rules in a notes file, listen with wait_for_events, hold replies as drafts until you trust them, and keep complaints and anything delicate for yourself.

How Spaces keeps your account safe

Whatever you ask, Spaces keeps your WhatsApp account inside safe limits: at least 10 seconds between messages, up to 400 a day, and 10 new conversations a day at most, with a gentler start for a newly connected account. If your AI tries to go faster, Spaces holds the message and says when it can try again.

New conversations warm up over the first weeks after you connect:

A reply to someone who wrote in is never held back by the daily limits, so customers get answers from the first day. Only messages that are not replies to someone who wrote in count toward the messages a day, which rise each week of the warm-up.

These are Spaces' own limits. They lower the risk of a restriction, but they cannot remove it, because WhatsApp makes its own decisions about accounts. Read the note at the top of this page before you connect.

Pricing

Free to start, then $9 per connected account a month

Do I need to be a programmer to use Claude Code for WhatsApp?

No, but you need to be comfortable typing a few commands in a terminal. You talk to Claude Code in plain words once it is running. If a terminal is not for you, Claude in the browser does the same job in sessions you start yourself.

Can Claude Code answer customers while I am out?

Yes, while it is running on a computer that stays on. It listens for new messages with wait_for_events and replies or drafts from your notes. Start with drafts, and only let it send simple replies once you trust it.

Does this use the WhatsApp Business Platform?

No. Spaces links your own number with a QR code, like WhatsApp on a computer. WhatsApp's terms for its apps apply, so read the note at the top of this page before you connect.

Will I still see the messages on my phone?

Yes. Your number stays on your phone as normal, and every reply Claude Code sends appears in the chat as a message from you. You can step in at any point from the phone.

How do I stop it replying at night?

Spaces does not have working hours for live replies on an account. Tell Claude Code in its notes when to answer, stop it in the evening, or pause all sending in Spaces under Settings.

Can Claude Code start chats with new customers?

Only within WhatsApp's rules in Spaces: a new chat only goes to someone who has messaged your number before, or whom you marked as opted in on the Accounts page. New chats also wait up to 24 hours after you connect.

What happens if Claude Code tries to send too fast?

Spaces holds or refuses the send and says when it can try again, so nothing goes out early. Replies go out at least 10 seconds apart whatever Claude Code asks.

Can Claude Code use WhatsApp and my other channels at once?

Yes. The main Spaces address covers every channel you connect. If you only want it to reach WhatsApp, add https://api.spacesos.com/mcp/whatsapp instead, which only shows your WhatsApp accounts.