7 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.
Archive
communications.archivewrite
Take one entry out of the communication log once it's been dealt with. NOT a delete: the call or message stays on file with its recording, transcript and body intact, still visible in its conversation thread and on the contact's timeline — it just stops appearing in the log and in the dashboard's Recent Communication column. Reversible with communications.unarchive.
Parameters
Field
Type
Required
Description
key
string
required
The entry's log key, exactly as `communications.list` returns it: `call:<uuid>` or `message:<uuid>`.
Over MCP the same operation is the tool communications_archive at https://app.chirply.io/api/mcp, same bearer token, same input.
My channels
communications.channelsread
List the account's OWN ends of a conversation — the phone numbers it calls and texts from, the email addresses it sends from, and the Facebook Pages and Instagram accounts it answers DMs on. Read-only, and the companion to `communications.list`: each entry's `address` is exactly the string to pass as that tool's `address` filter (E.164 for a number, the bare address for email, Meta's numeric id for a Page or Instagram account), which is the same list the communication log's channel filter shows. The far side of a conversation is not here — that is every contact the account has ever spoken to, and `communications.list`'s `search` is how you find those.
Parameters
Field
Type
Required
Description
kind
"phone" | "email" | "facebook" | "instagram"
optional
Only one kind of channel: phone, email, facebook, or instagram. Omit for all of them.
Over MCP the same operation is the tool communications_channels at https://app.chirply.io/api/mcp, same bearer token, same input.
Communication log
communications.listread
Read the communication log: every call, text, email, social message, and website live chat in this account on one timeline, newest first, with both sides of each exchange named. Calls carry duration, recording URL, transcript, and `callKind` — what placed the call, so a sales-bridge dispatch, an AI agent’s call and a number somebody dialed by hand are told apart rather than all reading as a plain outbound call; `call_kind` narrows to one of them. Messages and chats carry their latest content. Outbound email also carries an `engagement` object — when it was first opened and how many times, when a link was clicked, when it bounced, and when the recipient reported it as spam — each null until the email provider reports it, and all null when that provider has open tracking switched off, so a missing open never means the message went unread. Read-only. Archived entries are excluded unless `archived` is true, and entries marked as spam are excluded unless `spam` is true; live chats are always read from their dedicated inbox and have neither an archive nor a spam state. ONE DELIBERATE DIFFERENCE FROM THE SCREEN: the /communications page and the dashboard's Recent Communication column both collapse the timeline to the newest entry per contact, and this returns every entry by default so a machine caller can page the raw history. Pass `group_by_contact: true` to see exactly what the screen shows.
Narrows the CALLS in the log to this one kind — what placed the call, so a sales-bridge dispatch, an AI agent's call, a predictive-dialer pass and a number somebody typed into the dialer are told apart instead of all reading as plain calls. It only touches the call side: texts, emails, social messages and live chats come back as they always would, so pair it with `type: "call"` to see nothing but those calls. manual — Someone on your team dialed it — softphone, mobile app, or click-to-call. inbound — Someone called one of your numbers. sales_bridge — A sales bridge rang your agent pool so the first to press 1 got the lead. ai_agent — Your AI voice agent placed or answered the call. queue — Worked from a call queue. predictive — Dialed by a predictive dialer session. voice_campaign — Sent by a voice broadcast campaign. rvm — A voicemail dropped without ringing the phone. call_tracking — Came through a call-tracking number, so the source is attributed. web_widget — A visitor asked to be called back from the website call widget. other — Chirply couldn't tell what placed this call. Omit for every kind. Every call entry carries its own `callKind` whether or not this is set, and calls.list is the richer read when only phone calls matter.
archived
boolean
optional
False (default) reads the working log; true reads ONLY what has been archived out of it. Default: false
spam
boolean
optional
False (default) reads the working log; true reads ONLY what has been marked as spam — the log's own Spam view. Live chats never appear in the spam view. Default: false
search
string
optional
Free text, matched case-insensitively against message subjects and bodies, call transcripts and outcome notes, both addresses of every exchange, and the names, emails, phone numbers and social handles of the contacts involved — so a person's name finds their whole history, not just the rows that spell it out. A phone number matches however it was written down: '(409) 257-8393' finds '+14092578393'.
address
string
optional
Only exchanges involving this address. Any address works — one of the account's own numbers, sending addresses, Facebook Page ids or Instagram account ids (list them with `communications.channels`), or an outside number or email. Phone numbers match however they are formatted, and an email matches inside a `Name <addr>` header.
address_side
"either" | "from" | "to"
optional
Which end `address` has to sit on: 'either' (default) is everything involving it, 'from' is only what it sent, 'to' is only what it received. Ignored when no `address` is given. Website live chats have no 'to' address, so 'to' excludes them. Default: "either"
Only entries whose outcome is this. Matches what the log's own Status column says, so `opened` returns mail that was opened and NOT since clicked, bounced or reported as spam — each entry belongs to exactly one status. Email engagement: opened, clicked, bounced, complained (the recipient reported it as spam). Delivery: delivered, sent (handed over, not yet confirmed), sending (still going out), failed, received (inbound). Calls: call_completed, call_no_answer, call_busy, call_canceled, call_live. Live chat: chat_ai, chat_waiting, chat_human, chat_closed. A status narrows the channels searched to the ones that can carry it, so asking for `opened` returns no calls rather than silently ignoring the filter. Omit for every status.
group_by_contact
boolean
optional
True collapses the timeline to the single newest entry per contact (or per unknown address), each carrying a `groupCount` of how many entries it stands for — what the /communications page and the dashboard's Recent Communication column show. False (default) returns every entry individually, which is usually what a machine wants. Default: false
limit
integer
optional
Entries to return (1–200). Default: 50
offset
integer
optional
Entries to skip, for paging further back in time. Default: 0
Over MCP the same operation is the tool communications_list at https://app.chirply.io/api/mcp, same bearer token, same input.
Mark the log as seen
communications.mark_seenwrite
Clear the caller's unread counts by moving their read line up to now — the same thing that happens automatically when they open the communication log in the app. Pass `types` to clear only some channels (reading the Emails view shouldn't dismiss missed calls). Destroys nothing: every call and message stays exactly where it was, and only this one person's badge changes. Requires a signed-in user; an API key has no personal read line to move.
Over MCP the same operation is the tool communications_unarchive at https://app.chirply.io/api/mcp, same bearer token, same input.
New since you last looked
communications.unreadread
Count what has come in on each channel since the caller last opened the communication log — the numbers the log's filter pills and the top-bar badge show. Inbound only, archived entries excluded, and CALLS ARE COUNTED ONLY WHEN MISSED (no answer, busy, failed or canceled), because an answered call was already handled by a person. Never reaches further back than 30 days. Read-only — this does not mark anything as seen. The read line is per person: an API key has no personal one, so for key callers this returns everything inbound in the whole 30-day window rather than anything about a particular user.
Chirply