How to connect Codex to your WhatsApp business number

What you need

• Codex installed and signed in, in the terminal or your IDE.
• A Spaces account. Your trial 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 short notes file about the business: hours, prices, and the things you never want promised.
• If you want Codex to run in the background, a computer or server that stays on.

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 business number your customers already message, with the phone it lives on. A number with a long history of real conversations is the safest choice. A brand-new number gets no new chats at all from Spaces for its first 24 hours, though replies to people who message you go out from day one.

Step 2: add Spaces to Codex

1. Run the command below once. It is saved in ~/.codex/config.toml for every Codex client.
2. Run codex mcp login spaces and sign in to Spaces in the browser.

codex mcp add spaces --url https://api.spacesos.com/mcp
codex mcp login spaces

To check it worked: Run codex mcp list, or /mcp inside Codex. Spaces is listed with its tools.

You sign in on Spaces' own page during this step, so Codex 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 Codex so it reads the new settings.
• If it still does not appear, the Codex MCP docs have the current steps, and our Codex setup page has ours.

Step 3: try it

Start a Codex session in the folder with your notes file, and ask in plain words. Start with requests that only read:

• List my WhatsApp chats with unread messages, without sending anything.
• Group today's messages by what the customer wants.
• Draft replies to the booking questions using notes/whatsapp.md, and do not send them.
• Which customers have been waiting more than two hours for a reply?

Start with a question that only reads, like the first one. It shows you that Codex 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 ChatGPT or Claude in the browser, Codex can run on its own, without you starting each session. That means it can keep up with your WhatsApp while you work. It also means it can send when you are not watching, so set it up carefully.

Use Codex in normal sessions, as in the example below, until you trust its drafts. Then move to background runs that read and draft, and only later let them send the simplest replies. A Spaces routine is another option for set replies to set triggers, such as an out-of-hours message. It is not an AI, and it sends text you wrote in advance.

Codex may ask you to approve tool calls in a session. Leave that on while you are getting started.

A worked session: a Saturday at a bike repair shop

Here is an interactive Codex session for a two-person bike repair shop whose owner builds their own tools in the evenings. Names and details are examples.

Spaces paces the replies. Replies wait a random 10 to 20 seconds, and a new chat waits 1 to 2 minutes, so messages never go out in bursts. WhatsApp shows “typing…” first. Customers see a normal conversation, not a wall of messages arriving at once.

Notes for Codex to read

Keep a notes file in the folder you run Codex from, and tell it to read the file before it drafts anything. Because it is a file, you can change it in your editor and every session picks it up:

# notes/whatsapp.md
About us: Spokes & Sprockets, bike repairs. Open Tue-Sat 9am-5pm.
Services: full service £75, brake check £15 (same day if in before 3pm), puncture £12.
Bookings: Tue and Thu next week have space. Update this line every Monday.
We do not sell bikes, new or second-hand.
Collections: only say a bike is ready if I have said so in the session.
Tone: friendly, short, first names. No emojis unless they used one.
Never: diagnose from a photo, give a price for a repair we have not seen, or reply to complaints.
Never: message anyone who has not written to us.

Running Codex in the background

Because Codex can be run from a script, it can keep an eye on the shop's WhatsApp while you are in the workshop. OpenAI's Codex docs explain how to run it that way. The part that matters for WhatsApp is how Codex finds out 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.

A careful order of work for the first weeks:

1. Have each background run read and sort only, and send you a short summary, such as a message on another app or a file you check.
2. Let it draft replies, but not send, until you have read a week or two of drafts.
3. Ask Codex to hold replies as drafts in Spaces, and nothing goes out until you approve it. That is a useful halfway step.
4. When you trust it, let it send the low-stakes replies on its own: opening hours, prices from the notes, "your bike is ready".
5. Keep complaints, photos of damage and anything about money for a person, for good.

If you use an API key for background runs, keep it in an environment variable rather than in the config file:

[mcp_servers.spaces]
url = "https://api.spacesos.com/mcp"
bearer_token_env_var = "SPACES_API_KEY"

WhatsApp rules Spaces enforces, whatever Codex is asked

These are checked on every send. A prompt, a bug in your script or a confused run cannot get past them:

• 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 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.
• At least 10 seconds between messages, up to 400 a day and 10 new chats a day once the number has settled in.

When Codex hits one of these, Spaces refuses the send and says why, often with a time to try again. Tell Codex in your notes to wait for that time rather than retry, and never to reword a refused message to get round a rule.

What if...

• A background run starts sending things you did not expect? Pause all sending in Spaces (Settings, then Pause everything). Reading keeps working, so you can see what happened.
• Your computer sleeps at night? Codex stops with it. Customers wait until it is back, or you can set a Spaces routine to send a holding reply. A routine is not an AI, and it runs on Spaces itself.
• You want Codex to check a booking diary first? Spaces does not connect to booking systems. If your diary has its own tools, you can give Codex access to them separately.
• A customer sends a voice note? Spaces can fetch the attachment for Codex. What it can make of audio depends on how you have set Codex up, so check those replies yourself.

Common mistakes to avoid

• Letting background runs send from day one. Read and draft first.
• Checking for new messages in a tight loop. Use wait_for_events, which waits for you.
• Putting the API key in a file that ends up in a repository.
• Asking Codex to message past customers about an offer. WhatsApp's terms prohibit bulk messaging, and Spaces refuses the same text to many new people.
• Forgetting to update the bookings line in the notes, so Codex keeps offering days you have filled.

Summing up

With Spaces, Codex can read your business WhatsApp and reply from your own number, in a session or in the background. Keep the notes in a file, listen for messages with wait_for_events, start with summaries and drafts, and let Spaces' WhatsApp rules and the pause switch be the safety net underneath it.

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

Plans from $19 a month

Can Codex answer WhatsApp customers without me?

Yes, if you run it in the background on a machine that stays on. That is the main difference from ChatGPT in the browser, which acts only when you ask. Start with summaries and drafts before you let it send.

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.

Where does the Spaces connection live?

In ~/.codex/config.toml, so every Codex client on your computer can use it once it is added. The command in Step 2 writes it for you.

Can Codex start chats with new customers?

Only within the rules: a new chat only goes to someone who has messaged your number before, or whom you marked as opted in on the Accounts page.

What happens if Codex sends too fast?

Spaces holds or refuses the send and says when it can try again, and nothing goes out early. Tell Codex in your notes to wait for that time rather than retry straight away.

How do I stop everything at once?

Pause all sending in Spaces under Settings, then Pause everything. Reading keeps working while it is on, so Codex can still summarise what is coming in.

Do I need to know how to code?

It helps, because Codex lives in the terminal and the IDE. If that is not you, ChatGPT or Claude in the browser does the same WhatsApp job in sessions you start.