# Your users' own WhatsApp, inside a Composio agent > Composio gives an agent 1,500+ tools through one session. Circles adds a person's own WhatsApp to it, as a Custom MCP toolkit: the chats they open, ready to read, and to write in where they allow. **To give a Composio agent a personal WhatsApp:** create a Custom MCP toolkit with the address `https://app.usecircles.app/api/mcp` and the header `Authorization: Bearer {{generic_api_key}}`, and each user connects with their own Circles token. The agent then reads the chats that user opened in Circles, which is free for 2 chats for up to 3 months, $14.90 a month on Plus or $29.90 a month on Pro per number, with 14 days of Pro free, as of November 2026. Source: https://usecircles.app/en/agents/composio ยท Updated 2026-11-01 ## Composio's WhatsApp toolkit, or Circles? Composio's own WhatsApp toolkit works through the WhatsApp Business API, and its page says it does not support personal accounts (as of November 2026). It is the right choice for a business number: templates, customer messaging at scale, the official API. Circles is for a person's own number: the groups, family chats and voice notes on the phone they already use, given to their agent chat by chat. ## Four steps: two for each user, two for you 1. **Each person links their WhatsApp in Circles**: Your user starts a trial at usecircles.app and links their number as a linked device: a code typed on their phone, or a QR on their computer. They choose which chats agents may read, and which they may send in. 2. **They make a token**: On Circles' Agents page, *New token*, pick Other, keep MCP, and choose what it allows. The token starts with `circ_` and is shown once. 3. **You add Circles as a Custom MCP toolkit, once**: In your Composio project, create a toolkit with Circles' address and the header `Authorization: Bearer {{generic_api_key}}`, shared with `user_id="all"`. Composio fills in each user's own token when it calls Circles. 4. **Each user connects, and your agent asks**: Composio asks each user for their token through its connect link, and the tools sync on the first connection. Add the toolkit's slug to a session; your agent finds the tools with `COMPOSIO_SEARCH_TOOLS`. ## The code Python, with Composio's SDK. TypeScript has the same calls under `composio.experimental.customToolkits`. Set `mcp_url` to the address exactly, with no key in it. Composio fixes the address, the auth scheme and `user_id` at creation, so to change one, delete the toolkit and create it again. When Circles adds a tool, sync the toolkit again. ``` from composio import Composio composio = Composio() # reads COMPOSIO_API_KEY # Once per project: Circles as a shared Custom MCP toolkit toolkit = composio.experimental.custom_toolkits.create( name="Circles (personal WhatsApp)", mcp_url="https://app.usecircles.app/api/mcp", auth_schemes=[{ "mode": "API_KEY", "headers": {"Authorization": "Bearer {{generic_api_key}}"}, }], user_id="all", ) print(toolkit.slug) # keep it: CUSTOM_CIRCLES... # Per user: a session with Circles beside your other toolkits session = composio.sessions.create(user_id="user_123", toolkits=[toolkit.slug]) tools = session.tools() ``` ## Signing in by address instead of a token Composio's Custom MCP also takes OAuth with dynamic client registration: `"mode": "DCR_OAUTH"` with `"discovery_url": "https://app.usecircles.app/.well-known/oauth-authorization-server"`. Circles registers clients that way, and each person approves on Circles' own page, choosing whether the agent may send. This pairing has not been tried yet, so use a token until it has. ## What your users can ask Invented examples, real shapes. - **"What did I miss in the building committee group?"**: `catch_up` on one group since a time, voice notes already as text. - **"Put the dates from the school group into my calendar"**: Circles reads the group; your Google Calendar toolkit writes the events. - **"Find the invoice the accountant sent and file it in Drive"**: `documents` finds it, `get_media` fetches it, another toolkit files it. - **"Tell the running group I'm out on Thursday"**: Only if the token allows sending and that group is open for sending. ## What a Composio agent can and cannot do here **The agent can:** - See which chats you opened, and which of them moved since a time, with counts and no text (`allowed_chats`, `activity`). - Catch up and search, in one chat or all of them, with senders by name and voice notes already transcribed (`catch_up`, `search`). - See who you talk with and who is in a group, by the name you saved, with their number wherever WhatsApp shows it (`people`, `group_members`). - List the documents sent in your chats and open a photo, PDF or file, up to 50 MB (`documents`, `get_media`). The agent opens the file and reads it itself. - Send a message or a file in chats open for sending, which on a newly linked number is every chat (`send`). **The agent cannot:** - See a hidden chat. It is not listed, not searchable, and never named, not even in a refusal. - Send in a chat you set to read only, reach a chat you hid, or have a send retried automatically. - Reply with a quote or react with an emoji. Those exist only in the [HTTP API](https://usecircles.app/en/whatsapp-api-personal-number). - Keep access after you disconnect it. Disconnecting ends it at once, and every request it made stays in your activity log. ## Changing access, plans and invites **Changing what your agents can do.** Every agent you connect reads and writes by default in the chats you leave open, from the start. To narrow that, set a chat to read only or hide it on the Chats page in the Circles app, or message Circles Customer Service, the virtual service on the Circles number: [wa.me/972553091640](https://wa.me/972553091640). Write to it from your own WhatsApp. Your agent can draft the message for you. It cannot open, read or send in that chat, because the chat carries your sign-in links. **Plans.** Every plan reads and writes and sees all available history: 2 chats on Free, for up to 3 months from linking, 10 on Plus, and every chat you allow on Pro. Every signup starts with 14 days of Pro, with no card. Nothing is ever charged without your plan choice. [Plans and prices](https://usecircles.app/en/pricing). **Invites.** A friend you invite gets 28 days of Pro instead of 14, from the day they link WhatsApp. You get 14 days once their agent first reads through Circles, for up to 10 friends a week. Ask Circles Customer Service for your invite link. ## Questions and answers ### Does Composio have a WhatsApp toolkit? Yes, for WhatsApp Business accounts through the Business API, and its page says personal accounts are not supported (as of November 2026). Circles adds a personal number to Composio as a Custom MCP toolkit. ### Can each of my users connect their own WhatsApp? Yes. Share one Circles toolkit with `user_id="all"`; each user connects with their own Circles token, and their agent sees only the chats they opened in Circles. ### Is Circles in Composio's toolkit catalog? Not yet, as of November 2026. Add it as a Custom MCP toolkit; Composio's docs say shared custom toolkits work on every Composio plan. ### Can it sign in with OAuth instead of a token? Composio supports OAuth with dynamic registration, and so does Circles, but the two have not been tried together yet. Use a token until then. ### Can the agent send WhatsApp messages? Only if the user's token allows sending, and only in chats open for sending (every chat, by default). A send is never retried automatically. ### What does it cost? Circles is priced per WhatsApp number: free for 2 chats for up to 3 months, $14.90 a month on Plus, or $29.90 a month on Pro, with 14 days of Pro free. Composio's own plan is separate. ## Keep reading - [Any MCP client](https://usecircles.app/en/agents/grok): The same address and token, for clients that take a remote server. - [The HTTP API](https://usecircles.app/en/whatsapp-api-personal-number): The same chats as JSON, with quoted replies and reactions. - [What the agent can reach](https://usecircles.app/en/security): Per-chat permissions and the activity log. --- 14 days to try everything, free and with no credit card. Then you choose a plan by what you actually used. Start: https://usecircles.app/start?lang=en