add_chat_label
ChatGPTApply an existing label to a chat.
add_label
ChatGPTCreate a new WhatsApp label, such as "Clients" or "Follow up". Works only on WhatsApp Business accounts. Apply it to a chat afterwards with add_chat_label.
archive_chat
ChatGPTArchive chats (or unarchive with archived=false). Pass chat_ids: [...] to archive many in one call — never loop one call per chat.
automation_delete
ChatGPTDelete an automation and cancel active runs when applicable.
automation_get
ChatGPTRead one Automation by its canonical id. A durable flow includes health over the last 7 days: runs, succeeded/no_action/failed, failure_streak, model_calls, cost_usd, cost_per_run_usd, calls_per_run and last_error.
automation_list
ChatGPTList every Automation, regardless of its internal execution engine, including notifications, recurring tasks, scheduled behavior, event rules, and durable flows. If it can fire in the future, it appears here. enabled/watch/scheduled means armed only; last_run_at, latest_run, and active_run_count are the evidence of whether it has ever started and what happened. Each durable flow's health gives its last 7 days of outcomes, failure_streak and recorded model cost.
automation_run_control
ChatGPTPause, resume, or cancel one active automation run.
automation_runs
ChatGPTInspect automation runs and durable progress state. Each run carries its failure reason (last_error_code/last_error_message) and usage: the model calls, tokens and cost_usd it paid for (null when none were recorded).
automation_set_enabled
ChatGPTEnable or disable an automation. Disabling also cancels its active runs, so nothing further is sent.
chat_settings_get
ChatGPTRead the chat_settings row for a chat. Returns null if no row exists (meaning the chat uses defaults — mode=0, no per-chat notes). This is READ-ONLY and never starts durable work. Finite follow-through belongs to a Mission; standing monitoring or replies belong to an Automation.
chat_settings_list
ChatGPTList all chats with chat_settings rows. Useful for auditing which chats have explicit notes. Chats without rows use defaults and don't appear here.
chats_recent
ChatGPTList the operator's WhatsApp chats, MOST RECENT ACTIVITY FIRST — each with chat_id, name, unread_count, last-activity time, and labels. Optionally restrict to chats with unread messages, and cap the count.
contact_enrich
ChatGPTSet or update structured enrichment fields on a contact, only for stable facts the user asks to keep. Allowed: email, emails, organization, role, location, timezone, pronouns, preferred_name, languages, handles, google_resource_name, last_synced_to_google_at. Birthdays and free-form notes aren't stored here. Scalar fields overwrite; array fields (emails, languages) replace wholesale; object fields (handles) deep-merge.
contact_forget
ChatGPTForget enrichment data for a contact. Pass fields to null out structured fields, OR note_index to remove a legacy note. Used when the operator says 'forget that, I told you wrong'.
contact_get
ChatGPTRead a contact + everything the agent already knows about them (metadata.enrichment). Call this before answering questions about a person or deciding if a newly-observed fact is novel.
contacts_get_batch
ChatGPTResolve a list of JIDs to {name, pushname, lid} in one round trip. Use when chat context has bare JIDs without paired name labels.
create_group
ChatGPTCreate a new WhatsApp group with the given name and initial participants.
delete_chat
ChatGPTDelete chats from the chat list (local only — irreversible history removal). Pass chat_ids: [...] to delete several in ONE call — never loop one call per chat. The batch runs sequentially inside.
delete_message
ChatGPTDelete messages — across any chats. WhatsApp revokes each for everyone if it was your own message and within the revoke window; otherwise it's a local-only delete. Pass messages: [{chat_id, message_id}, ...] to delete several in ONE call — never loop one call per message. The batch runs sequentially, paced, inside.
edit_contact
ChatGPTRename a WhatsApp contact, only when the user asks. The new name is saved to the user's WhatsApp contacts and, if connected, their Google Contacts. Only name is applied; a contact's own WhatsApp display name can't be changed. For other details such as email or organization use contact_enrich.
edit_message
ChatGPTEdit a message you previously sent. WhatsApp only allows editing your own messages within ~15 minutes of sending.
forward_message
ChatGPTForward a message to one or more chats.
get_group_invite
ChatGPTGet the invite URL for a group (only works if operator is admin).
get_messages
ChatGPTRead recent messages from ONE chat, MOST RECENT FIRST. Returns sender (JID), canonical sender_identity / @sender_mention (including for LID group senders), from_me, body, type, attachment filename/mimetype, timestamp, reactions, and any quoted message. Messages deleted for everyone read "This message was deleted" with type revoked and their original text in prev_body. Empty / system / undecryptable rows are skipped, so this is the clean way to read or summarise a conversation. Page to older messages with before.
get_profile
ChatGPTUse this when you need to know which WhatsApp account this connection uses, for example when the user has several Perisclaw connections. Returns a stable account id and the phone number.
group_add
ChatGPTAdd participants to a group. People who are not trusted contacts, or whose privacy blocks the add, are sent an invite instead; the result says which, per participant.
group_demote
ChatGPTDemote admins to regular participants.
group_promote
ChatGPTPromote participants to admins.
group_remove
ChatGPTRemove participants from a group.
group_settings
ChatGPTUpdate a WhatsApp group's name, description, or who may post. The user must be a group admin. Supply at least one of name, description or post_permission.
leave_group
ChatGPTLeave a group (operator stops being a member).
mark_read
ChatGPTMark one or more chats as read, clearing unread count. Pass chat_ids newest-to-oldest by latest_message_timestamp when marking multiple chats.
mark_unread
ChatGPTMark one or more chats as unread, bumping them to the top of the chat list. Pass chat_ids newest-to-oldest by latest_message_timestamp when marking multiple chats.
media_download
ChatGPTFetch the photo, voice note, video or document attached to a message in the user's own WhatsApp so it can be viewed or described here. Use it only for a message the user is asking about. Pass that message's message_id. Files up to 10 MB are shown here; larger files can't be opened in this chat.
media_upload
ChatGPTSend a file from the user's computer: returns a private upload_url and media_id. Only for clients that can run commands, such as Codex or Claude Code: PUT the file bytes to upload_url with its Content-Type (e.g. curl -fsS -T report.pdf -H "Content-Type: application/pdf" "<upload_url>"), then call message_send with media_id. For a file attached in ChatGPT, use message_send media_file instead.
message_send
ChatGPTSend a WhatsApp message now: plain text, or a file the user attached here (media_file), a local file uploaded with media_upload (media_id), media from a public URL (media_url), a poll (poll.name is the question, poll.options the choices), a location, contact cards (contact_ids), an event, or buttons. text is the message, or the caption or body. When the user should review a reply before it goes, show workspace_conversation instead. Plain text is sent at most once per request_id: pass a new UUID for each message and the same one if you retry. Confirm the recipient and content with the user first. Subject to the chat's permission settings.
mute_chat
ChatGPTMute chats (or unmute with muted=false). Mutes notifications without removing the chat from the chat list. Pass chat_ids: [...] to mute many in one call.
pin_chat
ChatGPTPin chats to the top (or unpin with pinned=false). Pass chat_ids: [...] to pin many in one call.
pin_message
ChatGPTPin a message in a chat. Duration is one of three WhatsApp-allowed values: 86400 (1 day), 604800 (7 days), 2592000 (30 days). Defaults to 30 days. Pass pin=false to unpin.
react_to_message
ChatGPTReact to a WhatsApp message with an emoji. Pass an empty string to clear your existing reaction.
remove_chat_label
ChatGPTRemove a label from a chat.
reply_prepare
ChatGPTUse this only to send plain text without a reply card, after the user has approved the exact recipient and text in the conversation. Saves the text; nothing is sent until reply_send. Never use it for a draft shown in a reply card.
reply_send
ChatGPTUse this right after reply_prepare to send that saved reply. It sends at most once: repeating the call returns the same result. If the result is "uncertain", do not prepare it again; tell the user it may not have gone out and check with reply_status.
reply_status
ChatGPTUse this when a reply was not confirmed, to see whether it went out. Returns reply: null when nothing was saved. Never sends anything.
search_chats
ChatGPTFuzzy-match a chat (group or DM) by name. Same matching as search_contacts.
search_contacts
ChatGPTFuzzy-match a contact by name, or find the contact an exact email address belongs to (its contact_id is also their WhatsApp chat). Handles typos, phonetic variants, and word-order swaps.
search_messages
ChatGPTHybrid semantic and full-text search across WhatsApp messages. Returns relevant messages with authoritative chat and sender metadata, authorship provenance, and quoted-message context when present. Use this for finding past conversations by meaning or keyword. Pass a natural-language query. The semantic path uses the full text; the FTS path safely tokenises it as ANY-of-these words. FTS operators, quotes, and * are stripped rather than interpreted.
update_contact_metadata
ChatGPTUpdate a contact's custom metadata fields (advanced; use contact_enrich for standard fields such as email or organization). metadata.enrichment is not writable here.
workspace_conversation
ChatGPTUse this when the user wants to reply to a WhatsApp chat. Shows a card with the latest messages and your draft; the user edits it and presses Send in the card, which sends it. Never call reply_prepare or reply_send for a draft shown in a card: if the user says "send it", tell them to press Send in the card. To change the draft, call this again with new draft_text. Resolve the chat first. Sends nothing by itself.
workspace_open
ChatGPTUse this to answer whenever the user asks what needs their attention or reply on WhatsApp, or to catch up. First read the relevant chats with chats_recent and get_messages, then always show this card instead of writing the list out: pass up to 8 chats in priority order, each with a one-line reason naming who is waiting and on what ("Sarah asked you to confirm Friday"). The card is the answer, so add at most one or two sentences. Without chats it shows the most recent chats; that is only for opening Perisclaw from the sidebar. Does not mark anything read.