← All action domains

Conversations

50 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

conversations.archivewrite

Archive conversations out of the inbox — the inbox row's and the open thread's Archive button. NOT a delete: every message stays, the contact and their timeline are untouched, and the threads move to the inbox's Archived tab. A thread comes back to the inbox on its own the next time the contact writes in (spam excepted). Pass every thread id of a contact to clear their row completely; the inbox folds a contact's threads into one row. Visible to everyone in the account. Nothing is sent. Reversible with conversations.unarchive.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to archive.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.archive \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_archive at https://app.chirply.io/api/mcp, same bearer token, same input.

Assign a conversation

conversations.assignwrite

Assign a thread to a teammate, or pass assigned_to = null to leave it unassigned. The user must be a member of this organization.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation to assign.
assigned_tostring (uuid) (or null)requiredThe teammate's user id, or null to unassign.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.assign \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "assigned_to": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_assign at https://app.chirply.io/api/mcp, same bearer token, same input.

Cancel scheduled outreach

conversations.cancel_scheduled_outreachwriteconfirm

Cancel a future email, text, or call before dispatch starts. It cannot recall a provider submission already in progress.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredConversation that owns the scheduled action.
type"message" | "call"requiredWhether the id belongs to a scheduled message job or call.
idstring (uuid)requiredScheduled message job id or scheduled call id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.cancel_scheduled_outreach \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "type": "message",
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_cancel_scheduled_outreach at https://app.chirply.io/api/mcp, same bearer token, same input.

Create an autoresponder

conversations.create_autoresponderwriteconfirm

Create a named autoresponder containing ordered keyword/default cases. Once active and attached to a number, matching cases can SEND REAL MESSAGES, modify CRM data, and PLACE BILLABLE CALLS such as sales bridges with no human in the loop. Create it inactive to stage it safely.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
namestringrequiredThe responder's name in phone-number attachment pickers.
channel"sms" | "email"optionalWhich inbound message channel this responder handles. Default: "sms"
branchesobject[]optionalOrdered switch cases. The first matching keyword case wins; an optional default case is the fallback.
branches[].namestring (or null)optionalHuman label for this case, such as Call me or Default reply.
branches[].is_defaultbooleanoptionalWhether this is the fallback case used only when no keyword case matches. Default: false
branches[].match_type"contains_any" | "contains_all" | "exact_any"optionalHow the inbound message is compared with this case's keywords. Default: "contains_any"
branches[].keywordsstring[]optionalKeywords or multi-word phrases. Required for non-default cases; ignored for the default case. Default: []
branches[].reply_bodystring (or null)optionalReply to send when this case matches. Supports merge fields; null runs actions without replying.
branches[].actionsobject[]optionalOrdered real-world actions to run after a match. These can send messages, change CRM data, or place billable calls such as a sales bridge. Default: []
branches[].actions[].typestringrequiredA shared action type, such as sales_bridge, add_tag, send_sms, or create_task.
branches[].actions[].configmap of string → objectoptionalConfiguration for that action type, using the same fields as the visual action builder. Default: {}
branches[].workflow_idstring (uuid) (or null)optionalOptional automation to start for the matched contact in addition to the direct actions.
branches[].is_activebooleanoptionalWhether this individual case can currently match. Default: true
trigger"inbound_message" | "keyword" | "missed_call"optionalLegacy single-rule input. Use branches for the grouped model.
keywordstringoptionalThe word that fires a keyword rule. Required when trigger='keyword'.
bodystringoptionalLegacy single-rule reply body, used only when branches is omitted.
workflow_idstring (uuid) (or null)optionalLegacy single-rule automation, used only when branches is omitted.
is_activebooleanoptionalfalse stages the responder without arming any of its cases. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.create_autoresponder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_create_autoresponder at https://app.chirply.io/api/mcp, same bearer token, same input.

New snippet

conversations.create_snippetwrite

Save a new snippet to the account's shared library so everyone on the team can insert it from the Snippets button under the message box. Fails if a snippet with the same name already exists (ignoring case) or the account already has 500. Sends nothing.

Parameters

FieldTypeRequiredDescription
namestringrequiredWhat the Snippets picker lists and searches, e.g. "Pricing" or "Directions to the office". Up to 80 characters, and unique in the account (ignoring case).
bodystringrequiredThe text the snippet inserts into a message, up to 10,000 characters. Line breaks are kept. May contain merge fields such as {{first_name}}, {{contact.first_name}} or {{first_name | "there"}}, which fill in for the contact when the snippet is inserted.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.create_snippet \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "body": "example"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_create_snippet at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete conversation

conversations.deletewriteconfirm

Permanently delete one conversation thread and every message in that thread — the inbox row's and the open thread's Delete. The CRM contact and their call history are kept. This cannot be undone. The inbox folds a contact's threads into one row, and its Delete removes each of them, so call this once per thread id to match it; conversations.archive clears a thread from the inbox without deleting anything.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation thread to permanently delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.delete \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_delete at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete an autoresponder

conversations.delete_autoresponderwriteconfirm

Permanently delete an auto-reply rule and all of its keyword cases, replies and actions. Inbound messages on any phone number it was attached to stop getting an automatic reply immediately. Messages already sent are unaffected, but the rule itself cannot be recovered — pause it with conversations.toggle_autoresponder instead if you may want it back.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe autoresponder to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.delete_autoresponder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_delete_autoresponder at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete snippet

conversations.delete_snippetwriteconfirm

Permanently delete a snippet from the account's library. It disappears from every teammate's Snippets picker at once and cannot be recovered. Messages already sent with it are untouched. Only the snippet's author or an account owner/admin may delete it (API keys act as the owner).

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe snippet's id, from conversations.list_snippets.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.delete_snippet \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_delete_snippet at https://app.chirply.io/api/mcp, same bearer token, same input.

Remove a sorting rule

conversations.delete_sorting_rulewrite

Delete one inbox sorting rule — the Remove button beside it on Settings → Spam & blocked senders → Inbox sorting. Threads already sorted stay where they are; the sender's next email is sorted by its headers and Gmail's categories again. Nothing is sent or deleted besides the rule.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe rule's id, from conversations.list_sorting_rules.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.delete_sorting_rule \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_delete_sorting_rule at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a conversation

conversations.getread

Open one thread and read its history. Returns the conversation, the contact, and — exactly like the inbox — EVERY message exchanged with that contact across all channels and threads plus their calls, merged chronologically oldest to newest, not just this thread's own messages. By default it returns as much of that history as one answer can hold: the newest 700 timeline items, messages and calls counted together. A long-lived contact can exceed that, so the result always reports `has_older` and, when there is more, a `next_before` cursor: pass it back as `before` to read the page immediately older than the one you just got, and keep going until `has_older` is false. Every page is one unbroken run of history, so following the cursor to the end reads the whole thread with nothing skipped and nothing repeated. `limit` returns only the newest N items instead — the same tail-first window the inbox itself opens on. Read-only; nothing is sent, marked read, or changed.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation's id.
limitintegeroptionalReturn only the newest N timeline items (messages and calls together, 1–500) instead of the whole history — what the inbox loads when it opens a thread. Omit for the default full read.
beforestringoptionalPaging cursor: return only the history immediately OLDER than this point. Pass back the `next_before` value from the previous call, unchanged, to walk backwards through a long thread; omit it to start at the newest end. Treat it as an opaque string — it pins an exact position, not just a moment, so that a run of messages sharing one timestamp (a bulk insert, or an imported Facebook/Instagram history) pages through instead of being skipped. A plain ISO 8601 timestamp with an offset is still accepted for callers written against the earlier form, but it cannot separate rows recorded in the same instant.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.get \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_get at https://app.chirply.io/api/mcp, same bearer token, same input.

View bot pause on teammate replies

conversations.get_auto_pauseread

Read whether a teammate's own activity pauses a conversation's bots in this account. When `pause_on_teammate_activity` is true (the default for every account that never changed it), a teammate replying in a thread — from the inbox, the contact record or messages.send — or a teammate or API caller opening one with conversations.start pauses that thread's bot replies and conversation workflows until someone resumes them; when false, bots and keyword workflows keep answering. Deliberate pauses (conversations.take_over, a workflow's Human handoff card, an AI agent asking for a human) happen either way. Changes nothing and sends nothing.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.get_auto_pause \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool conversations_get_auto_pause at https://app.chirply.io/api/mcp, same bearer token, same input.

Open an autoresponder

conversations.get_autoresponderread

Fetch one named autoresponder with its ordered keyword cases, default fallback, replies, direct actions, and attached automations.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe autoresponder container to fetch.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.get_autoresponder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_get_autoresponder at https://app.chirply.io/api/mcp, same bearer token, same input.

See call scheduling options

conversations.get_scheduling_optionsread

List the active AI agents, caller ID numbers, voicemail recordings, IVR menus, and SalesBridge configurations available to schedule a call from one conversation.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredConversation whose contact may receive a scheduled call.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.get_scheduling_options \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_get_scheduling_options at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a snippet

conversations.get_snippetread

Fetch one snippet by id with its name, full text exactly as saved (merge fields unfilled), author, last editor and timestamps. Read-only.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe snippet's id, from conversations.list_snippets.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.get_snippet \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_get_snippet at https://app.chirply.io/api/mcp, same bearer token, same input.

Count the inbox

conversations.inbox_countsread

Count how much is waiting in the inbox right now: threads nobody has read, threads whose last message came from the contact and so are waiting on a reply, threads a teammate starred, and threads assigned to the caller (which includes anything sent to an email address they own). Also returns `categories`: unread threads in each category tab (primary, promotions, social, notifications). These are the numbers on the Conversations tabs. The caller's own count is 0 for a machine caller with no signed-in person behind it. Read-only — it changes nothing and marks nothing read.

Parameters

FieldTypeRequiredDescription
category"primary" | "promotions" | "social" | "notifications"optionalCount only this category, the way the view tabs read when that category tab is open. Omitted counts every category. `categories` is always across all of them.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.inbox_counts \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "primary"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_inbox_counts at https://app.chirply.io/api/mcp, same bearer token, same input.

Open latest messages

conversations.latestread

Open one inbox thread for a fast mobile view. Returns the conversation and only its newest messages, newest first, so a phone can start at the latest reply without downloading the contact's complete cross-channel history. Read-only.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation to open.
limitintegeroptionalHow many newest messages to return (1–100). Default: 40

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.latest \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_latest at https://app.chirply.io/api/mcp, same bearer token, same input.

List conversations

conversations.listread

List the inbox's conversation threads, most recent activity first. Filter by the inbox's own tabs (unread, needs reply, starred), by channel, Facebook Page or linked Meta asset, status, the direction of the newest message, assigned teammate, whether nobody owns it yet, or contact, and search subjects and last-message previews. Each thread reports whether it is unread, which way the last message went, and when it was starred. This only reads conversations — it sends nothing and does NOT mark anything read.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
channel"sms" | "mms" | "email" | "facebook" | "instagram" | "whatsapp"optionalOnly threads on this channel: SMS, MMS, email, Facebook Messenger, Instagram Direct, or WhatsApp.
meta_page_idstringoptionalOnly Facebook Messenger, Instagram Direct, or WhatsApp threads routed through this connected Page, Instagram account, or phone-number asset id.
status"open" | "closed" | "snoozed"optionalOnly threads in this status.
direction"inbound" | "outbound"optionalOnly threads whose NEWEST message went this way: 'inbound' means the contact wrote last, so the thread is waiting on us; 'outbound' means we wrote last. Use 'inbound' to read the inbox as real replies with an outbound campaign or welcome sequence filtered out, and 'outbound' to review what was sent and never answered. This looks only at the last message, not at whether the thread contains any message in that direction.
category"primary" | "promotions" | "social" | "notifications" | "spam"optionalWhich of the inbox's category tabs to list. 'primary' is people writing in (every text, chat and DM is here too); 'promotions' is newsletters and marketing email; 'social' is alerts from social networks; 'notifications' is receipts, account alerts, delivery reports and automatic replies; 'spam' is threads filed as spam, which no other value ever returns. Email is sorted into these as it arrives, from its headers, Gmail's own categories and the account's sender rules. Omitted lists every category except spam — what this capability returned before categories existed.
view"all" | "unread" | "needs_reply" | "starred" | "mine" | "archived"optionalWhich of the inbox's tabs to list. 'unread' returns only threads where someone wrote in more recently than anyone read the thread; 'needs_reply' returns threads whose last message came FROM the contact, read or not, which is the queue to work after an outbound campaign; 'starred' returns threads a teammate pinned; 'mine' returns threads assigned to the CALLER, which includes anything sent to an email address they own, and is rejected for a machine caller with no person behind it — name the teammate with assigned_to instead; 'archived' returns only threads archived out of the inbox (conversations.archive); 'all' is the whole working inbox. Every view except 'archived' leaves archived threads out, exactly as the inbox's tabs do. Default: "all"
assigned_tostring (uuid)optionalOnly threads assigned to this teammate's user id.
unassignedbooleanoptionalTrue returns ONLY threads nobody has been assigned to — the inbox's Unassigned view and the dashboard's Unassigned operations tile, i.e. the triage queue. Combine with status='open' for what needs picking up now. Cannot be combined with assigned_to. Default: false
contact_idstring (uuid)optionalOnly threads with this contact.
querystringoptionalText to match in the subject or the last message preview.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool conversations_list at https://app.chirply.io/api/mcp, same bearer token, same input.

List autoresponders

conversations.list_autorespondersread

List the org's named, phone-attachable autoresponders and the number of keyword/default cases inside each one.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
channel"sms" | "email"optionalOnly rules on this channel.
is_activebooleanoptionalOnly active (true) or paused (false) rules.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.list_autoresponders \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool conversations_list_autoresponders at https://app.chirply.io/api/mcp, same bearer token, same input.

See scheduled outreach

conversations.list_scheduled_outreachread

List email, text and call actions waiting or needing attention in one conversation, with their schedule and delivery status.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredConversation to inspect.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.list_scheduled_outreach \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_list_scheduled_outreach at https://app.chirply.io/api/mcp, same bearer token, same input.

Snippets

conversations.list_snippetsread

List the account's snippets — the saved replies the team inserts from the Snippets button under the Conversations message box — sorted A to Z by name, with each one's full text, author and whether the caller may edit it. An account holds at most 500. Read-only: nothing is sent or changed.

Also answers to saved replies, canned responses, quick replies, message snippets.

Parameters

FieldTypeRequiredDescription
querystringoptionalOptional search, matched the way the picker's search box matches: every word must appear in the snippet's name or text, and name matches come first.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.list_snippets \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "example"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_list_snippets at https://app.chirply.io/api/mcp, same bearer token, same input.

Inbox sorting rules

conversations.list_sorting_rulesread

Read this account's inbox sorting rules: each email address or domain whose email is filed into a chosen tab (Primary, Promotions, Social or Notifications) the moment it arrives, with who made the rule and when. Rules are made by the inbox's Move to and shown on Settings → Spam & blocked senders → Inbox sorting. Check here first when someone says a sender's email 'stopped showing up' in Primary. Read-only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalHow many rules to return, newest first. Up to 500. Default: 200

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.list_sorting_rules \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 200
  }'
Test with your API key

Over MCP the same operation is the tool conversations_list_sorting_rules at https://app.chirply.io/api/mcp, same bearer token, same input.

Mark all read

conversations.mark_all_readwriteconfirm

Clear EVERY unread conversation in the account at once — the inbox's Mark all read button. This is not undoable: which threads were unread is not recorded anywhere afterwards, so anything nobody had got to yet stops badging for the whole team. Use it for a deliberate inbox-zero, not as a way to tidy up before reading. Nothing is sent and no message is deleted.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
category"primary" | "promotions" | "social" | "notifications"optionalClear only this category's unread threads — the Mark all read button on that category tab, e.g. 'promotions' to clear a pile of newsletters without touching Primary. Omitted clears every category.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.mark_all_read \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "primary"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_mark_all_read at https://app.chirply.io/api/mcp, same bearer token, same input.

Mark read

conversations.mark_readwrite

Clear the unread badge on one or more conversations, exactly as opening them in the inbox does. Read state is shared across the whole account — a team inbox, not a personal one — so this clears the badge for every teammate, not just the caller. Nothing is sent and no message is changed.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to mark read. Pass every thread you want cleared — the app clears all of a contact's threads at once because its inbox rows are per contact, and a machine caller should do the same when it means 'this person is handled'.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.mark_read \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_mark_read at https://app.chirply.io/api/mcp, same bearer token, same input.

Mark unread

conversations.mark_unreadwrite

Put conversations back in the unread pile so they badge again — the inbox's Mark unread button, for a thread you looked at but did not deal with. Shared across the account, so every teammate sees it return. A thread nobody has ever written into has nothing to be unread about and is left alone. Nothing is sent.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to return to the unread pile.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.mark_unread \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_mark_unread at https://app.chirply.io/api/mcp, same bearer token, same input.

Move to

conversations.move_to_categorywrite

Move conversations to another inbox tab — Primary, Promotions, Social or Notifications — exactly like the inbox's Move to menu. For an email thread it also (1) saves a sender rule so every FUTURE email from that sender lands in the same tab, and (2) moves the sender's other existing threads there too, except any a person already moved by hand. Moved threads are never re-sorted automatically. Nothing is sent, deleted or marked read; the threads keep their unread, starred and assigned state. Moving a real customer's sender out of Primary means their future email arrives without a push notification, so move only senders you are sure about. Sender rules are listed by conversations.list_sorting_rules and removed by conversations.delete_sorting_rule.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to change. Pass every thread id of a contact to move their inbox row as a whole — the inbox folds a contact's threads into one row.
category"primary" | "promotions" | "social" | "notifications"requiredThe tab to move them to: 'primary' (people writing to you), 'promotions' (newsletters, marketing), 'social' (social-network alerts) or 'notifications' (receipts, account alerts, automatic replies). To file something as spam use conversations.report_spam.
remember_senderbooleanoptionalTrue (the inbox's behaviour) saves a sender rule and moves the sender's other threads too. False moves only these threads and leaves the sender's future email to the usual sorting. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.move_to_category \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ],
    "category": "primary"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_move_to_category at https://app.chirply.io/api/mcp, same bearer token, same input.

Not spam

conversations.not_spamwrite

Take conversations out of Spam — the Spam tab's Not spam. Each thread returns to the inbox tab it was sorted into, its sender comes off the blocked-sender list, a contact marked as a spammer is unmarked and unhidden, and automatic spam detection never judges that sender again. A domain-wide block someone added on purpose stays. Nothing is sent.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to change. Pass every thread id of a contact to move their inbox row as a whole — the inbox folds a contact's threads into one row.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.not_spam \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_not_spam at https://app.chirply.io/api/mcp, same bearer token, same input.

Recent Communication

conversations.recentread

DEPRECATED — use `communications.list`, which this now calls and which adds direction/type filters, paging and the archive. Returns the newest entries of the communication log (calls, texts and emails merged, newest first) — the same rows the dashboard's Recent Communication column shows. Read-only.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalHow many of the most recent entries to return (1–50). Default: 6

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.recent \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 6
  }'
Test with your API key

Over MCP the same operation is the tool conversations_recent at https://app.chirply.io/api/mcp, same bearer token, same input.

Insert a snippet

conversations.render_snippetread

Return a snippet's text with its merge fields filled in for one contact — what clicking the snippet in the Snippets picker puts into the message box. Uses the same merge renderer as sending, so the text is what that contact would receive; a field the contact has no value for comes back empty (or as its fallback). It does NOT send anything: pass the text to messages.send to deliver it.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe snippet's id, from conversations.list_snippets.
contact_idstring (uuid)optionalContact in this account to fill the merge fields in for — the person the message is going to. Omit to get the text exactly as saved, with its merge fields unfilled.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.render_snippet \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_render_snippet at https://app.chirply.io/api/mcp, same bearer token, same input.

Report spam

conversations.report_spamwriteconfirm

File conversations as spam — the inbox's Report spam. Each thread moves to the Spam tab, its sender's address is added to the account's blocked-sender list, and a saved contact behind it is marked as a spammer and hidden from the CRM. From then on anything from that sender is recorded but filed straight into Spam: nobody is notified, it is not forwarded, and no autoresponder or AI agent answers it. Nothing is deleted and nothing is sent. Reporting a real customer makes their future email disappear into Spam with no bounce, so confirm the threads first. Undo with conversations.not_spam.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to change. Pass every thread id of a contact to move their inbox row as a whole — the inbox folds a contact's threads into one row.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.report_spam \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_report_spam at https://app.chirply.io/api/mcp, same bearer token, same input.

Resume automation

conversations.resume_automationwriteconfirm

Release a human takeover and allow future automated replies and conversation workflows in this thread again. This does not restart canceled runs, but later inbound messages can trigger real outbound messages.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation where automation may speak again.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.resume_automation \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_resume_automation at https://app.chirply.io/api/mcp, same bearer token, same input.

Add a sorting rule

conversations.save_sorting_rulewrite

File every future email from one address — or every address at a domain and its subdomains — into a chosen inbox tab on arrival: the Add rule form on Settings → Spam & blocked senders → Inbox sorting. Saving a rule for a sender that already has one changes its tab. Threads already in the inbox stay where they are (use conversations.move_to_category to move them). Email sorted out of Primary arrives without a push notification. Nothing is sent or deleted.

Parameters

FieldTypeRequiredDescription
kind"email" | "domain"required`email` for one mailbox; `domain` for every mailbox at a domain and its subdomains.
valuestringrequiredThe address or domain. Lower-cased before it is stored; a domain may be given with or without its @.
category"primary" | "promotions" | "social" | "notifications"requiredThe tab their email goes to: primary, promotions, social or notifications.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.save_sorting_rule \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "email",
    "value": "example",
    "category": "primary"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_save_sorting_rule at https://app.chirply.io/api/mcp, same bearer token, same input.

Schedule call

conversations.schedule_callwriteconfirm

Schedule one outbound AI agent, spoken-message, IVR, ringless voicemail, or SalesBridge call to a conversation contact. At the chosen time this uses the account's phone provider and may spend voice, AI, voicemail, and SMS credits; SalesBridge rings its agent pool. The call is cancelable until dispatch starts.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredConversation whose contact will be called.
kind"ai" | "tts" | "ivr" | "rvm" | "sales_bridge"requiredThe kind of outbound call.
scheduled_atstring (date-time)requiredFuture ISO 8601 date and time with timezone offset; at least one minute from now and within one year.
agent_idstring (uuid)optionalVoice AI agent for an AI call.
goalstringoptionalOptional goal overriding the AI agent's standing goal for this call.
from_number_idstring (uuid)optionalCaller ID number for AI, spoken, IVR or voicemail calls.
messagestringoptionalWords to speak on a spoken-message call.
menu_idstring (uuid)optionalIVR menu for an IVR call.
audio_asset_idstring (uuid)optionalVoicemail audio recording for a ringless voicemail drop.
filter_number_idstring (uuid)optionalSecond account number used by a ringless voicemail drop.
sales_bridge_idstring (uuid)optionalSalesBridge configuration and agent pool to ring.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.schedule_call \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "kind": "ai",
    "scheduled_at": "2026-09-17T15:00:00Z"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_schedule_call at https://app.chirply.io/api/mcp, same bearer token, same input.

Schedule message

conversations.schedule_messagewriteconfirm

Schedule one email or SMS from a conversation for a future time. The saved Jobs dispatcher sends a real message to the contact at that time through the account's connected provider, using its current address and opt-out state; email and phone charges may apply. The message can be canceled until dispatch starts.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredThe email or SMS conversation to send from.
scheduled_atstring (date-time)requiredFuture ISO 8601 date and time with timezone offset; at least one minute from now and within one year.
bodystringrequiredMessage body; may be empty when valid media is attached.
subjectstringoptionalSubject for a new email; existing conversation subject is used when omitted.
mediaobject[]optionalUp to ten account-owned attachments.
media[].urlstringrequiredPermanent account media-library URL.
media[].kind"image" | "video" | "audio" | "file"requiredAttachment kind.
media[].namestringrequiredAttachment filename.
email_identity_idstring (uuid)optionalAccount email identity to send from.
email_mode"new" | "reply"optionalWhether this is a new email or a reply.
reply_to_message_idstring (uuid)optionalMessage to reply to in the same email conversation.
from_number_idstring (uuid)optionalAccount phone number to send an SMS from; first active number is used if omitted.
include_signaturebooleanoptionalWhether to include the account's configured email signature. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.schedule_message \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "scheduled_at": "2026-09-17T15:00:00Z",
    "body": "example"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_schedule_message at https://app.chirply.io/api/mcp, same bearer token, same input.

Save bot pause on teammate replies

conversations.set_auto_pausewriteconfirmadmin only

Choose whether a teammate's own activity pauses a conversation's bots in this account. true (the default) — a teammate replying in a thread, or a teammate or API caller starting one, pauses that thread's bot replies and conversation workflows and cancels its running workflow runs until someone resumes them. false — nothing is paused automatically, so keyword workflows, autoresponders and AI agents keep answering customers in threads your team is also replying in; a teammate can still pause any one thread with conversations.take_over. Applies to replies and new threads from now on: threads that are already paused stay paused until resumed (conversations.resume_automation). Sends nothing at the moment of saving, but switching it off lets automations send real messages in threads that would previously have been held for a person.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
pause_on_teammate_activitybooleanrequiredtrue: a teammate reply or a teammate/API-started conversation pauses that thread's bots (the default). false: bots and workflows keep running; pause threads by hand with conversations.take_over.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.set_auto_pause \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pause_on_teammate_activity": true
  }'
Test with your API key

Over MCP the same operation is the tool conversations_set_auto_pause at https://app.chirply.io/api/mcp, same bearer token, same input.

Set conversation status

conversations.set_statuswrite

Move a thread between open, snoozed, and closed — the Status section of the inbox's Manage menu. Use it to close a resolved thread or reopen a closed one; nothing is deleted either way.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation to update.
status"open" | "closed" | "snoozed"requiredopen reopens it, snoozed parks it, closed resolves it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.set_status \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "status": "open"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_set_status at https://app.chirply.io/api/mcp, same bearer token, same input.

Star this conversation

conversations.starwrite

Star or unstar conversations so they collect on the inbox's Starred tab — the account's own shortlist of threads worth coming back to. Visible to everyone in the account. Nothing is sent and the thread is not otherwise changed.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe conversation ids to star or unstar.
starredbooleanoptionalTrue stars them; false removes the star. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.star \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_star at https://app.chirply.io/api/mcp, same bearer token, same input.

Start a conversation

conversations.startwriteconfirm

Open a new SMS or email thread with a contact. For SMS without a contact_id, match the recipient's phone to an existing contact or create one, then link the thread and message to it. For email without a contact_id, link the thread to the existing contact at that address if there is one; a new address stays unlinked until it replies, and the reply joins this thread. If `body` is supplied it is SENT IMMEDIATELY as the first message — a real text or email leaves the org's own Twilio, Mailgun, or Resend account, reaches the recipient, and bills the tenant. Leave `body` empty to open an empty thread without sending anything. Merge tokens like {{first_name}} are rendered against the contact. When the account pauses bots on teammate activity (the default — see conversations.get_auto_pause) the new thread opens with automation PAUSED, so keyword workflows and AI replies ignore the recipient's answers until conversations.resume_automation; when that setting is off it opens active.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
channel"sms" | "email"optionalWhich channel to open the thread on. Default: "sms"
contact_idstring (uuid)optionalThe contact to message. When omitted for SMS with to_addr, Chirply finds or creates the recipient's contact automatically. When omitted for email, the existing contact at to_addr is linked; a new address stays unlinked.
to_addrstringoptionalRecipient address — a phone number for SMS, an email address for email. Defaults to the contact's own.
subjectstringoptionalSubject line (email threads only).
bodystringoptionalFirst message. Supplying it SENDS a real message; omit it to just open the thread.
from_addrstringoptionalSMS only: which of the org's active numbers to send from. Ignored unless it's one of them; defaults to the org's outbound number.
email_identity_idstring (uuid)optionalEmail only: verified account identity to send from. Defaults to the contact, thread, then account preference.
unsubscribed"skip" | "override"optionalEmail only. What to do when this recipient has UNSUBSCRIBED from email. Omitted or "skip" refuses the send, which is the default and the safe answer. "override" SENDS THE EMAIL ANYWAY to somebody who asked not to be emailed, requires `unsubscribed_reason`, and is a real legal exposure the account owner carries — use it only where you have permission, such as a customer who asked by phone to be put back on. The unsubscribe is NOT removed: it stays on file and the next message is skipped again. An unsubscribe footer is forced onto the email even if this account turned footers off. A spam complaint or a hard bounce is still refused, because sending to those damages every other sender on the account's domain. Ignored for SMS and Meta channels: a text opt-out is usually STOP to a carrier, which enforces it itself.
unsubscribed_reasonstringoptionalRequired when `unsubscribed` is "override", and refused if blank. Why this recipient may still be emailed after unsubscribing, in a sentence someone would read in a complaint — for example "They asked us by phone to start their renewal reminders again". Saved on the message and on the contact's timeline, so "who emailed someone who had unsubscribed, and why" has an answer.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.start \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "contact_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_start at https://app.chirply.io/api/mcp, same bearer token, same input.

Summarize a thread

conversations.summarizeread

Summarize a conversation into a few bullets — what the customer wants, the key facts, and the next step. Grounded only in that thread's own messages. Runs on the org's own OpenRouter connection and fails with a plain message when AI isn't connected. Reads only; nothing is sent or saved.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation to summarize.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.summarize \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_summarize at https://app.chirply.io/api/mcp, same bearer token, same input.

Resync messages

conversations.sync_metawrite

Check Facebook or Instagram for messages missing from one existing inbox thread and import up to the latest 500. This repairs missed webhooks, including replies written directly in Facebook or Instagram. It does not send anything or alter provider data.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe Facebook Messenger or Instagram DM conversation to resync.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.sync_meta \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_sync_meta at https://app.chirply.io/api/mcp, same bearer token, same input.

Take over automation

conversations.take_overwriteconfirm

Pause every automated responder on this conversation so a real teammate can handle it without the bot speaking over them. Active conversation workflow runs are canceled; no customer message is sent.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe conversation a person is taking over.
assigned_tostring (uuid) (or null)optionalAccount teammate who owns the handoff. Defaults to a human caller; machine callers and null keep the current assignee.
reasonstring (or null)optionalOptional internal reason for pausing automation.
paused_untilstring (date-time) (or null)optionalOptional future instant when automation may resume automatically; null pauses until an explicit resume.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.take_over \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_take_over at https://app.chirply.io/api/mcp, same bearer token, same input.

Activate or pause an autoresponder

conversations.toggle_autoresponderwriteconfirm

Flip an auto-reply rule's Active checkbox. Activating it arms real automatic sends on the next matching inbound message; pausing it stops them without deleting the rule.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe autoresponder to toggle.
is_activebooleanrequiredtrue arms the rule, false pauses it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.toggle_autoresponder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "is_active": true
  }'
Test with your API key

Over MCP the same operation is the tool conversations_toggle_autoresponder at https://app.chirply.io/api/mcp, same bearer token, same input.

Move to inbox

conversations.unarchivewrite

Move archived conversations back into the inbox — the Archived tab's Move to inbox button. They return to their usual place by latest activity, with their read, starred and assigned state as it was. Nothing is sent.

Parameters

FieldTypeRequiredDescription
idsarray of (string (uuid))requiredThe archived conversation ids to put back in the inbox.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.unarchive \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool conversations_unarchive at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit an autoresponder

conversations.update_autoresponderwriteconfirm

Replace or update a named autoresponder's ordered cases. Changes take effect on the next inbound message; active cases may immediately send real messages, change CRM data, or place billable calls.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe autoresponder to edit.
namestringoptionalNew phone-picker name; omitted leaves it unchanged.
channel"sms" | "email"optionalNew channel; omitted leaves it unchanged.
branchesobject[]optionalComplete replacement ordered case list. Omit to keep all existing cases.
branches[].namestring (or null)optionalHuman label for this case, such as Call me or Default reply.
branches[].is_defaultbooleanoptionalWhether this is the fallback case used only when no keyword case matches. Default: false
branches[].match_type"contains_any" | "contains_all" | "exact_any"optionalHow the inbound message is compared with this case's keywords. Default: "contains_any"
branches[].keywordsstring[]optionalKeywords or multi-word phrases. Required for non-default cases; ignored for the default case. Default: []
branches[].reply_bodystring (or null)optionalReply to send when this case matches. Supports merge fields; null runs actions without replying.
branches[].actionsobject[]optionalOrdered real-world actions to run after a match. These can send messages, change CRM data, or place billable calls such as a sales bridge. Default: []
branches[].actions[].typestringrequiredA shared action type, such as sales_bridge, add_tag, send_sms, or create_task.
branches[].actions[].configmap of string → objectoptionalConfiguration for that action type, using the same fields as the visual action builder. Default: {}
branches[].workflow_idstring (uuid) (or null)optionalOptional automation to start for the matched contact in addition to the direct actions.
branches[].is_activebooleanoptionalWhether this individual case can currently match. Default: true
is_activebooleanoptionalWhether the responder is armed.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.update_autoresponder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_update_autoresponder at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit snippet

conversations.update_snippetwrite

Rename a snippet or change its text. Omitted fields are left alone. Only the snippet's author or an account owner/admin may edit it (API keys act as the owner). Messages already sent with the old text are untouched; the next insert uses the new text. Sends nothing.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe snippet's id, from conversations.list_snippets.
namestringoptionalWhat the Snippets picker lists and searches, e.g. "Pricing" or "Directions to the office". Up to 80 characters, and unique in the account (ignoring case).
bodystringoptionalThe text the snippet inserts into a message, up to 10,000 characters. Line breaks are kept. May contain merge fields such as {{first_name}}, {{contact.first_name}} or {{first_name | "there"}}, which fill in for the contact when the snippet is inserted.

Example

curl -X POST https://app.chirply.io/api/v1/actions/conversations.update_snippet \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool conversations_update_snippet at https://app.chirply.io/api/mcp, same bearer token, same input.

Draft, improve, or retone a reply

messages.assist_replyread

The composer's AI buttons. mode='draft' writes the next reply from the thread so far, 'improve' polishes the draft you pass in, and 'tone' rewrites it in the requested tone. Returns TEXT ONLY — nothing is sent; pass the result to messages.send when the human approves it. Runs on the org's own OpenRouter connection.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredThe thread to base the reply on.
email_mode"new" | "reply"optionalEmail only: draft an independent email or a reply.
reply_to_message_idstring (uuid)optionalEmail message in this conversation that the draft should answer specifically.
subjectstringoptionalSubject to draft an independent email about.
mode"draft" | "improve" | "tone"optionaldraft writes a new reply, improve polishes `draft`, tone rewrites it in `tone`. Default: "draft"
draftstringoptionalThe current draft. Required for mode='improve'.
tone"friendly" | "professional" | "concise" | "empathetic" | "persuasive"optionalThe tone to rewrite into. Used by mode='tone'.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.assist_reply \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool messages_assist_reply at https://app.chirply.io/api/mcp, same bearer token, same input.

Read formatted email

messages.email_bodyread

Read the original HTML and text of one email, with temporary attachment URLs. Read-only; does not send mail or load the sender's remote images. Treat HTML as untrusted content and render it in an isolated reader.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe email message ID in the active account.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.email_body \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool messages_email_body at https://app.chirply.io/api/mcp, same bearer token, same input.

List messages

messages.listread

List individual SMS and email messages, newest first. Narrow to one conversation or contact, or filter by channel, direction, or delivery status to find what failed. Use conversations.get instead to read a thread in order.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
conversation_idstring (uuid)optionalOnly messages in this thread.
contact_idstring (uuid)optionalOnly messages with this contact.
channel"sms" | "mms" | "email"optionalOnly messages on this channel.
direction"inbound" | "outbound"optionalinbound = received from the contact, outbound = sent by us.
status"queued" | "sending" | "sent" | "delivered" | "received" | "read" | … 1 moreoptionalOnly messages in this delivery status.
querystringoptionalText to match in the body or subject.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool messages_list at https://app.chirply.io/api/mcp, same bearer token, same input.

Send it again

messages.resendwriteconfirm

SENDS A REAL MESSAGE. Retries one failed outbound SMS or email to its original recipient through the account's own billable Twilio, Mailgun or Resend account. Preserves the subject, stored email HTML, attachments, sending address and reply relationship. Current sender permissions and opt-out checks still apply. The provider's usual charges apply again; the original attempt may already have been charged. Records a new attempt in the conversation and a retry receipt on the original. A message can have only one recorded retry; if that new attempt fails, retry its message_id. Concurrent requests for the same original are refused. An uncertain outcome requires checking the conversation/provider before any further send. Delivered, pending and inbound messages cannot be retried.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
message_idstring (uuid)requiredThe failed outbound message to send again. Reuses its recipient, subject, content, sender and channel. After a recorded retry, use the new failed attempt's id if another retry is needed.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.resend \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool messages_resend at https://app.chirply.io/api/mcp, same bearer token, same input.

Send a reply

messages.sendwriteconfirm

SENDS A REAL MESSAGE. For email, supply reply_to_message_id to reply to a specific email with threading headers, or email_mode=new plus subject for an independent email. Replies on an existing SMS, email, Facebook Messenger, Instagram DM, or WhatsApp thread. SMS/email use the org's own billable Twilio, Mailgun, or Resend account; Meta replies use the connected Page or WhatsApp Business number and are limited to Meta's 24-hour messaging window. It reaches an actual person with no draft or undo. Merge tokens like {{first_name}} are rendered against the contact before sending. Files from the account media library can be attached — note that attaching one to an SMS makes it an MMS, which the org's carrier bills at a higher rate than a text. When the account pauses bots on teammate activity (the default — see conversations.get_auto_pause) sending also pauses this thread's automation and cancels its running conversation workflows, exactly like a reply from the inbox.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
email_mode"new" | "reply"optionalEmail only: reply requires reply_to_message_id; new sends an independent email with its own subject. Omit for legacy conversation sending.
reply_to_message_idstring (uuid)optionalExact email message ID from messages.list to reply to, in this conversation. Sets real email threading headers and replies to its sender.
subjectstringoptionalRequired for a new email. Replies preserve the selected email subject with Re:.
conversation_idstring (uuid)requiredThe thread to reply on. Its channel decides SMS, email, Facebook Messenger, Instagram DM, or WhatsApp.
bodystringoptionalThe message text to send. May be empty when `media` is given — an attachment with no caption is a valid message. Default: ""
mediaarray of (string (uri))optionalUp to 10 files to attach, as media-library URLs from assets.list (assets.import_from_url puts a new file in the library first). They must belong to this workspace's own library — any other address is ignored, because the messaging providers fetch these URLs directly. Images send inline; anything else sends as a link or document. Attaching to an SMS turns it into a billable MMS.
from_addrstringoptionalSMS only: active account phone number in E.164 format. Uses this exact sender; rejects unavailable numbers instead of substituting another line.
to_addrstringoptionalOverride the recipient address. Defaults to the thread's own.
email_identity_idstring (uuid)optionalEmail only: verified account identity to send from. Selecting it changes the sticky identity for this thread.
include_signaturebooleanoptionalEmail only: false sends this ONE message without the sender's configured email signature appended — the same per-message opt-out as the composer's “include signature” checkbox. Omit (or true) to append the signature exactly as a normal send would. Ignored for SMS and Meta channels, which never carry a signature.
unsubscribed"skip" | "override"optionalEmail only. What to do when this recipient has UNSUBSCRIBED from email. Omitted or "skip" refuses the send, which is the default and the safe answer. "override" SENDS THE EMAIL ANYWAY to somebody who asked not to be emailed, requires `unsubscribed_reason`, and is a real legal exposure the account owner carries — use it only where you have permission, such as a customer who asked by phone to be put back on. The unsubscribe is NOT removed: it stays on file and the next message is skipped again. An unsubscribe footer is forced onto the email even if this account turned footers off. A spam complaint or a hard bounce is still refused, because sending to those damages every other sender on the account's domain. Ignored for SMS and Meta channels: a text opt-out is usually STOP to a carrier, which enforces it itself.
unsubscribed_reasonstringoptionalRequired when `unsubscribed` is "override", and refused if blank. Why this recipient may still be emailed after unsubscribing, in a sentence someone would read in a complaint — for example "They asked us by phone to start their renewal reminders again". Saved on the message and on the contact's timeline, so "who emailed someone who had unsubscribed, and why" has an answer.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.send \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool messages_send at https://app.chirply.io/api/mcp, same bearer token, same input.

Send approved template

messages.send_whatsapp_templatewriteconfirm

SENDS A REAL WHATSAPP MESSAGE. Sends a live Meta-approved template on an existing customer-initiated WhatsApp thread, including after the 24-hour reply window. The connected account is billed by Meta; delivery reaches a real person immediately with no draft or undo. Chirply re-checks the exact template language and current APPROVED status, the account phone DNC and WhatsApp opt-out lists, and durable WhatsApp consent plus the recipient's valid stored timezone and local messaging hours for marketing templates before every send.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
conversation_idstring (uuid)requiredThe existing WhatsApp conversation whose contact receives the template.
template_namestringrequiredThe exact lowercase name of the template approved in WhatsApp Manager.
languagestringrequiredThe exact approved WhatsApp language code, such as en_US or pt_BR.
componentsobject[]optionalMeta header, body, and button component objects with the text, currency, date/time, media, payload, or coupon parameter values required by the approved template.

Example

curl -X POST https://app.chirply.io/api/v1/actions/messages.send_whatsapp_template \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "template_name": "Example",
    "language": "example"
  }'
Test with your API key

Over MCP the same operation is the tool messages_send_whatsapp_template at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=conversations — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.