Sign inStart free trial

← All action domains

Conversations

34 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.

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.

Delete conversation

conversations.deletewriteconfirm

Permanently delete one conversation thread and every message in that thread. The CRM contact and their call history are kept. This cannot be undone.

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.

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.

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.

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). 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

No parameters — POST an empty body.

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 '{}'
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.
view"all" | "unread" | "needs_reply" | "starred" | "mine"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; 'all' applies no extra narrowing. 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.

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

No parameters — POST an empty body.

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 '{}'
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.

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.

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.

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.

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. 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.

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. Omit for a thread with no CRM record.
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.

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.

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. Takes one outbound SMS or email that failed and sends the same text to the same recipient again, through the account's own billable Twilio, Mailgun or Resend account. It reaches an actual person with no draft or undo, and it is billed again — the original attempt may already have been charged for. This is the honest way to confirm a settings fix worked: after a country is switched on in Twilio's console, a text that came back 21408 either goes through now or comes back with the same refusal. Only outbound messages that actually failed can be resent, so a delivered message cannot be duplicated through this.

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. Its recipient, text and channel are all reused as they were.

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.

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.