Skip to main content

Set up a WhatsApp number for your AI agent

Give your AI agent its own WhatsApp number: keep it on a spare phone, register it with the code on My numbers, link it to TimelinesAI by QR, warm it up, and connect your AI agent through MCP or the API.

This guide shows how to give your AI agent its own personal WhatsApp number from TimelinesAI Numbers. You keep the number on a spare phone, link it to TimelinesAI by QR like any teammate's number, and your AI agent reads and sends through the TimelinesAI MCP or Public API. Your team sees every chat in the shared inbox and can take over at any time.

The steps: get a spare phone → register the number in WhatsApp → link it to TimelinesAI by QR → warm it up → connect your AI agent.

Read this first: the ban risk. This is a personal WhatsApp account, not the official WhatsApp API. WhatsApp's terms don't allow automated or bulk messaging from WhatsApp and WhatsApp Business app accounts, and WhatsApp can ban a number it sees as automated or spammy. A ban is decided by WhatsApp, often without warning, and can be permanent. TimelinesAI can't prevent or lift bans. What lowers the risk: a dedicated number, the warm-up below, replies rather than cold outbound, and Safe Sending (step 4).

1. What you need

  • A spare phone (Android or iPhone) with WhatsApp or WhatsApp Business from the official app store. Don't use a rooted or jailbroken phone or a modified WhatsApp app.

  • Keep that phone charged, online and in use. A personal WhatsApp account needs the app on a phone as its main device. TimelinesAI is a linked device, and WhatsApp logs out linked devices when the main phone is offline for about 14 days. Leave the phone on a charger with Wi-Fi or mobile data, and open WhatsApp on it regularly. It doesn't need a SIM card: the number's text messages arrive in TimelinesAI Numbers.

  • A number from numbers.timelines.ai bought for the WhatsApp app (personal) setup, not the WhatsApp API setup. One setup per number.

  • A TimelinesAI workspace, on any plan.

  • An AI agent that can use MCP (for example Claude, ChatGPT or Cursor), or your own code that calls the TimelinesAI Public API.

2. Register the number on the spare phone

  1. Open My numbers, sign in with the email you bought the number with, and click Open next to the number. Keep the Verify screen open: WhatsApp's code appears there live.

  2. On the spare phone, open WhatsApp or WhatsApp Business, choose to set up a new account, and enter the number with its country code.

  3. Ask for the code by SMS. These numbers can't receive calls.

  4. Copy the 6-digit code from the Verify screen into WhatsApp. If you turned on Email me incoming SMS, the code is also emailed to you.

  5. Set a profile name and photo, for example your business name.

  6. Turn on two-step verification in WhatsApp (Settings → Account → Two-step verification) so nobody else can register the number on another phone.

  7. Use the number in the app for at least 2–3 days before you link it. Save a few contacts who know you, such as teammates, and have real back-and-forth chats with them from the phone: text, photos, voice notes. New accounts that start messaging at once are more likely to be suspended, and virtual numbers are watched more closely than SIM numbers.

WhatsApp decides which numbers it accepts. If WhatsApp shows an error such as "Login not available right now", see Virtual Numbers on TimelinesAI and send support the exact error.

Keep the number subscription active for as long as the AI agent uses the number. You need the number to receive any future WhatsApp code, and releasing a number is permanent.

3. Connect the number to TimelinesAI by QR

Each TimelinesAI profile can connect one WhatsApp number. Pick the case that fits you:

  • Your TimelinesAI profile has no number connected yet (for example, you just signed up): connect the AI agent's number from your own profile.

  • Your profile already has a number: give the AI agent its own profile. In Team, invite a new member with an email address you can open, for example [email protected]. Name it so your team can tell it apart, for example "Sales AI agent". Put it on the same team as the people who will supervise it, so they see its chats. The profile and its number use one seat on your plan.

Tip: set the AI agent's profile to the role called Agent in TimelinesAI. With that role, the profile sees only the number it connected and chats assigned to it, so an AI agent signed in as that profile can't read your other numbers. See Roles and permissions.

Then link the number:

  1. Sign in to TimelinesAI as the profile that will hold the number. A private browser window helps if you're also signed in as yourself.

  2. Open WhatsApp Accounts → My account → Generate QR.

  3. On the spare phone, open WhatsApp → Linked devices → Link a device, and scan the QR code.

  4. Check that the number shows as connected under WhatsApp Accounts → All accounts. Its chats now appear in the shared inbox as their own line.

WhatsApp may show a security warning while linking. That is expected when you scan a QR code you generated in TimelinesAI; see WhatsApp Safety Warning. For other ways to link and for troubleshooting, see Connect WhatsApp to TimelinesAI.

4. Warm up the number in the first days

A new number that suddenly sends many messages looks like spam to WhatsApp. What counts most is how many different people the number messages in a short time. Ramp up slowly:

  1. First days: 5–10 messages a day, mostly replies to people who messaged the number first.

  2. Then add people who expect to hear from you, such as customers who gave you their number and agreed to be contacted on WhatsApp.

  3. Increase a little each day, and only while people keep replying. Aim for at least 3 replies for every 10 messages sent. Many messages that get no reply are a strong ban signal.

For a new number

Guideline

Different people messaged per day

40 at most

Sending pace

1–2 messages a minute, with random pauses

Sending hours

Not around the clock: take breaks between batches

Reply rate

At least 30%

At every stage:

  • No cold outbound. Don't use the AI agent's number to message people who don't know you.

  • Don't send the same text to many chats. Vary and personalize messages.

  • In a new chat, don't send links or attachments in the first message.

  • Don't keep messaging someone who doesn't reply or has blocked the number.

Safe Sending is on automatically

WhatsApp can temporarily stop a number from messaging new contacts if it reaches out to too many people. While that restriction lasts, TimelinesAI's Safe Sending holds back one-to-one messages to people who haven't messaged the number recently, so the restriction isn't made worse. Replies to people who wrote recently and messages to groups still go out. Held-back messages show as Failed and don't use messaging credits. You don't need to turn Safe Sending on, and you can't turn it off.

If you use the Public API, GET /whatsapp_accounts shows reachout_timelock_active and reachout_timelock_ends_at for each number, and the webhooks whatsapp:account:reachout_timelock:active and whatsapp:account:reachout_timelock:cleared tell you when a restriction starts and ends. Use them to stop your AI agent from starting new chats until the restriction ends.

5. Connect your AI agent through MCP or the API

MCP (Claude, ChatGPT, Cursor and other MCP clients)

The quickest way: paste this prompt into your AI agent. It adds the TimelinesAI MCP server and asks you to sign in.

Set up TimelinesAI WhatsApp MCP for me. Fetch https://timelines.ai/whatsapp-mcp-setup.md and follow it.

To add it by hand, use the server URL https://mcp.services.timelines.ai/mcp and follow Connect TimelinesAI to your AI assistant (MCP).

  • Sign in as the AI agent's profile if you created one in step 3. The AI agent then acts as that profile and sees only what it can see.

  • Test with a read-only request first, for example "List the WhatsApp accounts you can see." Check that the AI agent's number is there.

Public API (your own code)

An Owner or Admin generates the API token under Integrations → Public API. The token works for the whole workspace, so make sure your code sends only from the AI agent's number. See TimelinesAI Public API and the API reference.

Messaging credits

Every message your AI agent sends through MCP or the API uses your workspace's monthly messaging credits (1 per message, 2 with an attachment). Reading chats uses no messaging credits. Messages your team types one by one in the inbox are unlimited. See Mass sending quota overview.

Rules to give your AI agent

Add rules like these to your AI agent's instructions. TimelinesAI doesn't enforce them; your AI agent follows them because you told it to.

You send WhatsApp messages through TimelinesAI from our AI agent's number only.
1. Reply only in chats where the contact has written to us. Don't start new chats unless a person on our team asks you to.
2. Skip any chat that is assigned to a person on our team. That person is handling it.
3. Message no more than 40 different people a day, and send no more than 1-2 messages a minute.
4. Don't send the same text to more than one chat.
5. Don't send links or attachments as the first message in a new chat.
6. If a message shows Failed, don't resend it. Tell us instead.

6. How people stay in control

These are the controls available today:

  • Watch every chat. All chats on the AI agent's number appear in the shared inbox for everyone who can see that number. To see only those chats, create a filter by WhatsApp account and share it with your team; see Connect multiple WhatsApp numbers.

  • Take over a chat. Assign the chat to yourself or a teammate and reply from the inbox; see Assigning a chat to a teammate. Your reply comes from the same number, so the contact sees one conversation. Assigning a chat doesn't by itself stop the AI agent, so give it rule 2 above.

  • Disconnect the AI agent. For MCP, remove the TimelinesAI connector in your AI assistant's settings. For the API, regenerate the token under Integrations → Public API; this stops every integration that used the old token.

  • Stop all sending from the number at once. On the spare phone, open WhatsApp → Linked devices, tap TimelinesAI and choose Log out. Nothing can be sent from that number through TimelinesAI until you scan a new QR code.

  • Check what was sent. Every message the AI agent sends appears in the chat history in the inbox. For the API, you can also download a log of your latest 1,000 API requests.

7. If the number gets banned

You'll know because WhatsApp on the spare phone says the number is banned or not allowed to use WhatsApp, and the number shows as disconnected in TimelinesAI.

  1. Stop the AI agent so it doesn't keep trying to send (see "Disconnect the AI agent" above).

  2. Ask WhatsApp for a review from the app on the spare phone, using the button on the ban screen. WhatsApp decides, and a review can take a few days. See WhatsApp bans: what to do if my number was banned.

  3. Keep the number subscription active while the review is open. Don't release the number.

  4. Contact TimelinesAI support in the chat or at [email protected]. Send your Numbers account email, the number, when the ban happened, and what the AI agent was sending in the days before. We can't lift WhatsApp bans, but we can help you review what happened.

  5. If WhatsApp restores the number, use it in the app for 1–2 days before you link it again, then warm it up again from step 4.

A temporary restriction is not a ban. If messages to new contacts show as Failed but the number is still connected and replies still go out, WhatsApp has limited outreach for a while and Safe Sending is holding messages back (step 4). Keep replying to people who write to you, and don't retry the failed messages.

Frequently asked questions

Can my AI agent use the number without a phone?

No. A personal WhatsApp account needs the WhatsApp app on a phone as its main device, and that phone has to stay on and online. If you don't want to keep a phone, buy the number for the WhatsApp API setup instead.

What happens if the spare phone goes offline?

The TimelinesAI connection keeps working for a while. If the phone stays offline for about 14 days, WhatsApp logs out linked devices, including TimelinesAI. Bring the phone back online and scan a new QR code in WhatsApp Accounts.

Do contacts see that they're talking to an AI agent?

Messages arrive from the AI agent's number like any other WhatsApp message. TimelinesAI doesn't add a label. If you want contacts to know, say so in the profile name or in the AI agent's first reply.

Can I use the official WhatsApp API for my AI agent instead?

Yes. Buy the number at numbers.timelines.ai and choose the WhatsApp API setup. Don't register that number in the WhatsApp app. Meta charges for WhatsApp API messages, and Meta's rules allow AI agents that do a business job, such as support, sales or booking, but not general-purpose AI assistants. See Virtual Numbers on TimelinesAI.

What does this cost?

The number subscription from TimelinesAI Numbers, your TimelinesAI plan (a seat for the AI agent's profile if it has its own), and the messaging credits your AI agent uses. The number subscription is separate from your TimelinesAI subscription.

Questions? Chat with us in the bottom-right corner or email [email protected].

Did this answer your question?