Circles API and MCP documentation

• Know your world. allowed_chats lists every chat open to you and whether you may send there. A chat missing from it cannot be read or searched. The one way past the list is a new chat: when the number's default is read and send, send can start a chat with someone new, by phone number or a saved contact's exact name (GET /recipients?to= over HTTP).
• "What did I miss?" Call activity with a since time first (counts only, cheap), then catch_up for the chats that moved. Voice notes arrive as text in media.transcript.
• A refusal is an answer. It comes with isError: false and names what IS open or allowed. Pass it on to the person; do not retry it.
• Sending speaks as the person. Show the person the exact text and the exact chat, and call send with confirmed: true only after they agree. A send is never retried: if delivery is uncertain, read the chat before deciding anything.
• Times are UTC. Circles does not know where the person is; convert times for them yourself.
• Not connected yet? The person links WhatsApp and connects you by following the guides at usecircles.app/en/docs. Circles never asks you for their password or a WhatsApp code.

allowed_chats: no parameters. The chats open to agents, each with name, kind, access (read only or read and send) and archived where set. This is the whole world: a chat missing here cannot be read, searched or sent to. Also carries connection (not_linked, subscription_ended) and subscription.ends_at when a cancelled plan is running out.

activity: since (ISO 8601, required). Which open chats moved: message count, last_at / last_at_iso, last_from. Counts only, no text. The cheap first call for "what did I miss?".

catch_up: since (required), chat, limit, per_chat, kind. Messages since a time, oldest first, senders by name. With chat: that chat, limit default 50, max 200, newest kept. Without it: every open chat that moved, newest chat first, per_chat default 20, max 50, within a total of 150; a chat with more says more. kind is voice, audio or recording (either). Attachments are announced only. Fetch one with get_media.

search: query (required), chat, days (1 to 36,500; default: all history kept), kind. Case-insensitive text search in one open chat or all of them, matching what was written and what voice notes and audio files say. Each hit names its chat when searching all.

people: since (required), limit (default 60, max 150), min_messages (default 3). Who the person talks with across open chats: direct-chat counts, shared groups, messages per group. It returns names only, with no numbers and no text.

group_members: chat (required). Members of one open group from WhatsApp's member list, including those who never wrote. Saved name, else the name they write under, else their WhatsApp name marked ~. Admins marked. At most 300 names; members with no known name are counted in unnamed. Never phone numbers.

documents: since (required). Every PDF, Word file and sheet sent in open chats: filename, date, the chats it was sent to (one entry per file), ref and state. Names and dates only.

get_media: ref (required). One attachment, base64 in bytes_base64, with mime, filename and size_bytes. Up to 50 MB per file. For an on_request file it asks the phone to re-upload and waits about 25 seconds. One ref per call. The agent reads the file itself. Circles does not run OCR, describe images or extract PDF text.

send: chat, text, confirmed (all required), file (mime, data_base64, filename), from. One message to a chat open for sending: text up to 65,536 characters, or a file up to about 3 MB with the text as its caption (up to 4,096). A JPEG, PNG or WebP goes as a photo, an MP4 or 3GP as a video, anything else as a named document. When the number's default is read and send, chat may be a phone number with its country code or a saved contact's exact name, to start a new chat; from picks the number when more than one could. Capped per day, never retried. confirmed is the agent's statement that the person agreed to this exact text in this exact chat; Circles cannot verify it and does not treat it as permission.

The envelope. Every tool answers with one text item. For an answer, content[0].text is JSON (pretty-printed). For a refusal, it is a plain sentence. Either way isError is false: read a refusal and pass it on. Do not retry it.

Refusals name what IS allowed. "No chat named X is open to agents. What IS open: A, B." or "X is open for reading only." A hidden chat is never named, so a refusal cannot tell an agent whether a chat exists. "No messages" and "you cannot see that chat" are never confused.

Coverage. When a request reaches further back than anything held, the answer carries coverage saying where the kept history starts and why, ending "Nothing was hidden from you." No coverage means nothing in the window is missing.

Times are UTC: at in milliseconds since 1970 and at_iso in ISO 8601 ending in Z (last_at / last_at_iso likewise). Circles does not know where the person is and converts nothing.

Voice notes. media.kind is voice for a WhatsApp voice note and audio for an audio file. Both carry transcript and transcript_state: pending (still being transcribed), done, empty (nothing was said) or failed; and duration_seconds where WhatsApp gave it. Transcription is automatic, Hebrew and English. A voice note older than about 25 days at linking is transcribed once it is fetched.

Attachment states. Every announced file has a state:

• available: get_media returns it now.
• downloading: arriving by itself, usually within a minute. Ask again shortly.
• on_request: WhatsApp no longer has it; get_media asks the person's phone to re-upload it (the phone must be online) and waits about 25 seconds.
• fetching: the phone has not answered yet. It is NOT gone: ask again with the same ref in about a minute; a repeat joins the request already running.
• gone: the phone could not re-upload it. Say so; do not retry.
• too_large: over 50 MB, the limit for one call.
• failed: could not be downloaded yet. Nothing for the person to do.

Also in messages: reactions (emoji, who, when) once someone reacted, from 2026-10-27 onward. Edits in WhatsApp update the stored text; "delete for everyone" removes the message. Locations, contact cards and polls are kept as empty messages so a chat has no holes. Link previews and quoted-message context are not included.

A shortened example, with invented people:

Scope narrows; it never widens. A token holding every scope still reaches only the chats the person opened, because the chat levels are read again on every call.

Every request carries Authorization: Bearer <key>: a minted circ_ key or an MCP client's OAuth token. Nothing else is accepted, no cookies.

• Reads: GET https://app.usecircles.app/api/v1/agent/allowed_chats, /activity, /people, /catch_up, /search, /documents, /group_members, with the same parameters as the tools.
• Details: GET /chats/{chat_ref} and GET /messages/{message_ref} return what is allowed (capabilities, with reasons and notes) and complete actions.
• Send: POST /chats/{chat_ref}/messages (text, or a file up to about 3 MB with an optional caption).
• Reply: POST /messages/{message_ref}/replies, a native WhatsApp quoted reply. A reply that cannot be quoted is refused.
• React: POST /messages/{message_ref}/reactions, an emoji reaction.
• New chat: GET /recipients?to= with a phone number (country code, URL-encoded) or a saved contact's exact name; answers like a chat's details.
• Write receipt: GET /writes/{submission_ref}.
• Files: POST /get_media (may ask the phone for the file), GET /media/{ref}/status, /content and /view (never ask the phone).
• Connect code: POST https://app.usecircles.app/api/v1/connect/exchange.

Acting. To send, reply or react, GET the chat's or message's details and perform one of its actions as given: a complete request (method, URL, headers, body) to which the agent adds only its Authorization header and the text.

Idempotent writes. Each write carries a server-issued, target-bound submission reference. Reusing it cannot send again or take another slot of the daily cap, for 24 hours. An uncertain delivery returns delivery_unknown and is never retried: read the receipt and the chat before making a new, deliberate submission.

Pagination. List answers carry pagination.next_url and has_more at the top level. Follow next_url until it is null; each page rechecks authorization. catch_up pages run from the newest messages back.

Errors. A 401 means the key no longer works. A 403 scope_required means the person did not grant that permission. An invalid argument names the field and its allowed range.

Not supported: poll voting, removing a reaction, quoting a message that is not text.

• 2026-10-27: Instinct connects with a one-time code sent from WhatsApp, with no key shown or pasted.
• 2026-10-27: A message can be as long as WhatsApp allows: 65,536 characters.
• 2026-10-27: Reactions are kept on their message and shown in every read.
• 2026-10-27: Direct chats open for reading by default on a new number.
• 2026-10-27: HTTP API 2.0.0: browser agents removed; the agent API accepts a Bearer key only.
• 2026-10-26: A cancelled subscription keeps working to the end of the paid period, and allowed_chats tells the agent the date.
• 2026-10-23: Agents can message someone with no chat yet, by phone number or saved contact name.
• 2026-10-19: Agents can send a file of any type: a PDF, a document, a video or an image.
• 2026-10-19: Recordings: kind=voice|audio|recording filters and duration_seconds; every time is stated as UTC.
• 2026-10-19: Claude and Codex connect by address, with consent on Circles' page.
• 2026-10-18: Voice notes are transcribed automatically and agents read the transcript on the message.
• 2026-10-18: Full history is the default, for new and existing numbers.
• 2026-10-16: HTTP API with native replies and reactions; edits and deletions made in WhatsApp are applied.