Sign inStart free trial

← All action domains

AI agents

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

Point a number at an AI agent

ai_agents.attach_to_numberwriteconfirmadmin only

Route a phone number's incoming calls to an AI agent. THIS CHANGES WHO ANSWERS A LIVE BUSINESS PHONE LINE: the number's inbound destination becomes 'ai_agent', so from the next call onward real callers reach the AI instead of the team's phones, and every one of those calls bills the account's own Twilio and OpenRouter accounts. Whatever the number rang before (the team, another agent) stops receiving those calls until it is pointed back with ai_agents.detach_from_number. Manager-only, matching the number settings page.

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
number_idstring (uuid)requiredThe phone number to route.
agent_idstring (uuid)requiredThe AI agent that should answer it.

Example

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

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

Have an AI agent call a contact

ai_agents.call_contactwriteconfirm

Queue an AI agent to call one of your contacts on their stored phone number, dispatched immediately by the outbound call engine (do-not-contact and the wallet guard still apply; quiet hours are deliberately skipped because this is an explicit 'call them now'). THIS DIALS A REAL PERSON and bills Twilio voice minutes plus OpenRouter tokens. The agent must be active and OpenRouter must be connected.

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
agent_idstring (uuid)requiredThe agent that should make the call.
contact_idstring (uuid)requiredContact to call.
goalstringoptionalWhat this call should achieve, overriding the agent's standing goals.
from_number_idstring (uuid)optionalCaller-ID number. Defaults to the account's default outbound number.

Example

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

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

Charge saved cards

ai_agents.charge_caller_paymentwriteconfirm

Immediately charges REAL MONEY for the invoice prepared by this active AI call, on the business's connected Stripe account. Requires agent saved-card permission, one linked Stripe customer with a default saved card, and a separate recorded caller confirmation after the returned confirmation_prompt was spoken verbatim as the entire reply, stating the exact amount, currency, purchase and saved-card authorization. Cannot accept a caller-supplied card/customer id or bypass recorded consent. Stripe processing costs apply. Retries reuse the same order and payment intent.

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
session_idstring (uuid)requiredActive AI call session in this account. The server binds the contact and phone number from this session.
invoice_idstring (uuid)requiredInvoice returned by prepare_caller_payment and recorded in this session's tool events.

Example

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

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

Create an AI agent

ai_agents.createwrite

Create an AI phone agent. Only a name is required; it gets the default Polly voice and no knowledge scope, ready to configure with ai_agents.update. IT IS CREATED ACTIVE, NOT PAUSED — `is_active` defaults to true, exactly as it does when a person creates one in the app. It cannot take a call until something points at it, but the moment a number is routed to it (ai_agents.attach_to_number) or a call campaign names it, this unconfigured agent WILL answer or place real calls with no further switch to flip. Pause it with ai_agents.set_active if you are creating it to configure later.

Parameters

FieldTypeRequiredDescription
namestringrequiredInternal label used to find the agent. Set agent_name for its spoken identity; older agents without it use this label.
agent_namestring (or null)optionalSpoken name used to introduce the agent to customers, such as John. Null uses the existing label.
descriptionstringoptionalInternal note about what this agent is for. Never spoken on a call.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.create \
  -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 ai_agents_create at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete an AI agent

ai_agents.deletewriteconfirm

Permanently delete an AI agent. Refused while any call campaign is still using it — deleting mid-flight would leave every remaining recipient dialed, hearing silence, and metered. Numbers pointed at the agent fall back to the team automatically. 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 agent to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.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 ai_agents_delete at https://app.chirply.io/api/mcp, same bearer token, same input.

Stop an AI agent answering a number

ai_agents.detach_from_numberwriteadmin only

Hand a phone number's incoming calls back to the team (simulring online browser agents, then voicemail). The agent itself is untouched. Manager-only, matching the number settings page.

Parameters

FieldTypeRequiredDescription
number_idstring (uuid)requiredThe phone number to hand back to the team.

Example

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

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

End test

ai_agents.finish_web_testwrite

Close the AI-agent rehearsal session behind a browser 'Start web call' test that never finished — the row the studio leaves open when the tab is closed, the laptop sleeps, or the network drops mid-test. A stranded session stays 'active' forever otherwise, which keeps it out of the agent's call history and out of its cost totals. Closing one stamps it completed and runs the same wrap-up (summary, outcome, pricing) a normally-ended test gets. Costs nothing and starts no call. Already-finished sessions are left exactly as they are.

Parameters

FieldTypeRequiredDescription
session_idstring (uuid)optionalThe rehearsal session to close, from ai_agents.list_calls.
provider_sidstringoptionalThe Twilio CallSid of the browser leg instead, which is what the softphone knows. Give this or session_id.

Example

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

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

Open an AI agent

ai_agents.getread

Fetch one AI agent with every setting — persona, greeting, goals, voice and TTS provider, model, transfer rules, guardrails — plus the brain topics it's scoped to.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe agent's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.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 ai_agents_get at https://app.chirply.io/api/mcp, same bearer token, same input.

Open an AI call

ai_agents.get_callread

Fetch one AI call in full: which agent handled it and on which of your phone numbers, the turn-by-turn transcript, every tool the agent used, the summary and outcome, any message it took or contact fields it updated, and a link to the recording when one was kept.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe AI call session id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.get_call \
  -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 ai_agents_get_call at https://app.chirply.io/api/mcp, same bearer token, same input.

List AI agents

ai_agents.listread

List the account's AI phone agents (AI receptionists) with their voice, model, language and whether each is active.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
is_activebooleanoptionalOnly active (true) or paused (false) agents.
querystringoptionalText to match in the agent's name or description.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.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 ai_agents_list at https://app.chirply.io/api/mcp, same bearer token, same input.

List what an agent can be allowed to do

ai_agents.list_abilitiesread

List every ability an AI phone agent can be granted for use mid-call — messaging, CRM updates, campaigns, automations, and appointment scheduling. Use it to build `abilities` and the optional per-ability `ability_guardrails` map for ai_agents.update. Each entry says whether it reaches a real person immediately.

Parameters

No parameters — POST an empty body.

Example

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

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

List AI calls

ai_agents.list_callsread

List calls AI agents have handled — which agent took it, which of your phone numbers it ran on, direction, who was on the other end, status, outcome, turn count and the voice engine it ran on. `cost_cents` is Chirply's rough internal estimate, not a provider charge — the actual charges are on the account's own Twilio, OpenAI and OpenRouter bills. Use ai_agents.get_call for the full transcript.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
agent_idstring (uuid)optionalOnly calls handled by this agent.
contact_idstring (uuid)optionalOnly calls with this contact.
direction"inbound" | "outbound"optionalOnly calls in this direction.
status"active" | "completed" | "transferred" | "voicemail" | "failed" | "abandoned"optionalOnly calls that ended this way.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.list_calls \
  -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 ai_agents_list_calls at https://app.chirply.io/api/mcp, same bearer token, same input.

List agent models

ai_agents.list_modelsread

List the OpenRouter models an AI agent can run on, with per-1M-token pricing, context window, and whether each supports tool calling (the voice agent requires it). Flags models measured too slow for live voice — a 'smart' model with a 16-second first token is unusable on a phone call.

Parameters

FieldTypeRequiredDescription
querystringoptionalText to match in the model id or name.
tools_onlybooleanoptionalOnly models that support tool calling (what a voice agent needs). Default: true
limitintegeroptionalMax models to return. Default: 50

Example

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

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

List agent voices

ai_agents.list_voicesread

List every voice an AI agent can speak with: the curated Amazon Polly and Google catalogs (included with the platform, no extra account) and — when the account has connected ElevenLabs — the voices in its own ElevenLabs account. Use the returned ids with ai_agents.update. Each ElevenLabs voice carries live_call_safe: it is false for a voice the account CREATED itself (an instant or professional clone, a designed voice), because on a live call Twilio does the ElevenLabs synthesis from its own account and can only reach the shared ElevenLabs library — assigning one to an agent is refused. Those voices are still usable for voicemail drops and phone-menu prompts, where the audio is rendered up front with the account's own key.

Parameters

FieldTypeRequiredDescription
provider"amazon" | "google" | "elevenlabs" | "elevenlabs_own"optionalOnly voices from this provider.

Example

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

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

Create payment links

ai_agents.prepare_caller_paymentwriteconfirm

Create a published one-time Chirply invoice for the contact on an active AI call with payment-link permission. Uses the business's connected Stripe account, stores the exact agreement and returns its payment URL. Nothing is charged or sent; email/text delivery is a separate action. Repeating the same request key reuses the invoice.

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
session_idstring (uuid)requiredActive AI call session in this account. The server binds the contact and phone number from this session.
amountintegerrequiredAmount in smallest currency units, such as 12500 for USD 125.00.
currencystringrequiredThree-letter currency code.
descriptionstringrequiredAgreed purchase description.
request_keystringrequiredStable key for this agreement, reused on retries.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.prepare_caller_payment \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "amount": 1,
    "currency": "USD",
    "description": "example",
    "request_key": "example"
  }'
Test with your API key

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

Preview a voice

ai_agents.preview_voicewriteconfirm

Audition an ElevenLabs voice without placing a call: synthesizes a short fixed sample line in its OWN ElevenLabs account, which SPENDS ITS CREDITS the first time a given voice is previewed (every preview after that is served from cache, free). Amazon Polly and Google voices cannot be previewed — Twilio only exposes them at call time, and the platform holds no AWS or Google credentials — so a preview is never faked with a substitute voice. Returns a link to play the audio; the bytes themselves aren't inlined.

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
voice_idstringrequiredThe ElevenLabs voice id to audition.

Example

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

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

Read caller record

ai_agents.read_caller_recordread

Read one section of the contact matched to an active AI call, including full stored history and linked custom objects. Sensitive private data is limited to this account and the number on this call. Character and row paging retain long notes and transcripts. The active call's duplicate tool-response log is omitted to prevent recursive paging. Read-only; spends no AI credit and sends no messages.

Parameters

FieldTypeRequiredDescription
session_idstring (uuid)requiredActive AI call session in this account. The server binds the contact and phone number from this session.
section"profile" | "company" | "messages" | "conversations" | "calls" | "ai_calls" | … 65 morerequiredContact record section.
offsetintegeroptionalRow offset returned by the preceding section page. Default: 0
character_offsetintegeroptionalCharacter offset returned for a long section response. Default: 0

Example

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

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

Activate or pause an AI agent

ai_agents.set_activewriteconfirm

Turn an AI agent on or off. Activating it PUTS IT ON THE PHONE IMMEDIATELY: from that moment it answers every inbound call on the numbers routed to it and places the outbound calls its campaigns queue, talking to real people and billing the account's own Twilio and OpenRouter accounts for every minute (plus ConversationRelay usage on its Twilio, or gpt-live-1 audio on its own OpenAI account, depending on the voice engine), with no further approval. Pausing stops both; everything it's configured with is kept either way.

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 agent to toggle.
activebooleanoptionalfalse pauses the agent. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.set_active \
  -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 ai_agents_set_active at https://app.chirply.io/api/mcp, same bearer token, same input.

Place a test call

ai_agents.test_callwriteconfirm

Have an AI agent call a phone number right now so you can hear it — the agent page's 'Test call' button. THIS DIALS A REAL PHONE: it bills the account's own Twilio for the voice minutes and its OpenRouter account for the tokens the conversation uses (plus ConversationRelay usage on its Twilio, or gpt-live-1 audio on its own OpenAI account, depending on the agent's voice engine). The agent must be active and OpenRouter must be connected.

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
agent_idstring (uuid)requiredThe agent that should place the call.
to_e164stringrequiredNumber to call, e.g. +15551234567.
goalstringoptionalWhat this specific call should achieve, overriding the agent's standing goals.
from_number_idstring (uuid)optionalCaller-ID number. Defaults to the account's default outbound number.

Example

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

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

Edit an AI agent

ai_agents.updatewriteconfirm

Update any part of an AI agent — identity, persona and goals, greeting, voice and TTS provider, model, knowledge scope, what it's allowed to do on a call, transfer target, voicemail script and turn limit. Omitted fields are left alone. Everything is validated before anything is written. THIS SPENDS THE WORKSPACE'S MONEY AND CAN REACH REAL PEOPLE UNATTENDED, which is why it needs confirming: `use_relay=true` ADDS Twilio ConversationRelay usage, billed per minute to the account's own Twilio, to every call this agent ever takes; `voice_engine='live'` runs every call on OpenAI gpt-live-1, whose audio is billed per minute to the workspace's own connected OpenAI account, on top of Twilio voice; granting `abilities` such as 'send_text', 'send_email' or 'add_to_campaign' is standing authorization for the AI to message real customers mid-call, on the account's own number and domain, with nobody reading the wording first; and `is_active=true` puts it back on the phone immediately.

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 agent to edit.
namestringoptionalInternal label used to find the agent. Set agent_name for its spoken identity; older agents without it use this label.
agent_namestring (or null)optionalSpoken name used with customers. Null restores the existing label as the spoken name.
descriptionstring (or null)optionalInternal note about what this agent is for. Never spoken on a call.
is_activebooleanoptionalWhether the agent answers and places calls. true puts it live on every number and campaign pointed at it right away.
tts_provider"amazon" | "google" | "elevenlabs" | "elevenlabs_own"optionalWhich engine speaks. 'amazon' and 'google' are included and work on every call. The two ElevenLabs routes differ in capability, not quality: 'elevenlabs' is Twilio's built-in integration — no ElevenLabs account needed, nothing extra to pay, but it can only speak shared-library voices; 'elevenlabs_own' renders each line with the account's OWN ElevenLabs key, which spends that account's credits and adds roughly half a second before the agent starts talking, and is the ONLY route that can speak a voice the account cloned itself. Both need the real-time (relay) transport.
tts_voice_idstringoptionalProvider-native voice id (e.g. 'Joanna-Neural', 'en-US-Neural2-F', or an ElevenLabs voice id). See ai_agents.list_voices.
fallback_voicestringoptionalFor ElevenLabs agents: the curated Polly/Google <Say> voice callers hear when a call doesn't run on the relay.
language"en-US" | "en-GB" | "en-AU" | "es-US" | "fr-FR" | "de-DE"optionalSpeech-recognition locale for the call.
modelstring (or null)optionalOpenRouter model id. See ai_agents.list_models.
use_relaybooleanoptionalRun calls on ConversationRelay — faster with barge-in; adds ConversationRelay usage to the account's own Twilio bill.
voice_engine"auto" | "gather" | "relay" | "live"optionalWhich engine answers the phone. 'auto' keeps the `use_relay` behaviour above and is the default. 'gather' pins calls to the per-turn loop (most compatible, no extra per-minute charge). 'relay' pins them to ConversationRelay (adds ConversationRelay usage to the account's own Twilio bill). 'live' runs them on OpenAI's gpt-live-1, which listens and speaks at the same time so a caller can talk OVER the agent and still be understood — this SPENDS MONEY on the workspace's own connected OpenAI account (gpt-live-1 audio, billed per minute by OpenAI) on top of Twilio voice. 'live' needs that OpenAI connection; without it the setting is stored but every call quietly answers on another engine, so connect OpenAI under Settings → Integrations first. The agent's abilities, guardrails and transfer behaviour are identical on all four.
relay_speech_timeout_msinteger (or null)optionalWait before replying on new ConversationRelay calls, in whole milliseconds (600–5000). Longer waits give callers more time to pause between phrases. Caller interruption stays enabled. Null restores Automatic (the platform default); omit to keep the saved value. Standard fallback calls retain their own timing. This changes configuration without placing a call; longer calls consume more of the connected Twilio account's billed time.
greetingstring (or null)optionalWhat the agent says when it answers.
outbound_openingstring (or null)optionalOpening line on calls it places.
personastring (or null)optionalWho the agent is and how it should sound — role, tone, and anything it must never say. This is the agent's character, and it goes into the system prompt on every call it takes.
goalsstring (or null)optionalWhat the agent is trying to achieve on a call, in plain sentences — e.g. 'book a consultation; if they aren't ready, get an email address'. Steers what it asks for and when it wraps up.
brain_mode"all" | "topics" | "none"optionalKnowledge scope: all topics, selected topics, or none.
topic_idsarray of (string (uuid))optionalBrain topics this agent may answer from (used when brain_mode is 'topics'). Replaces the current selection.
can_update_contactbooleanoptionalAllow the agent to write contact fields mid-call.
can_take_messagebooleanoptionalAllow the agent to take a message.
message_assignee_idstring (uuid) (or null)optionalWorkspace member the tasks from 'Take messages' are assigned to. Null leaves them unassigned, which is the historical behaviour and still visible to the whole workspace. Assigning notifies nobody — the task simply appears in that person's list.
transfer_mode"none" | "number" | "team"optionalWhere a transfer goes: nowhere, a number, or the team.
transfer_e164string (or null)optionalTransfer destination when transfer_mode is 'number'.
ivr_mode"navigate" | "listen" | "end"optionalPhone menus: navigate with touch tones, listen while the human navigates, or end.
other_ai_mode"request_human" | "continue" | "end"optionalWhen an automated assistant answers: request a human, continue toward the call goal, or end.
ivr_instructionsstring (or null)optionalMenu routing guidance, such as choosing Sales. Applies to real calls and can select IVR actions.
ivr_max_stepsintegeroptionalMaximum AI touch-tone keys per outbound call; human keypad remains available.
voicemail_messagestring (or null)optionalScript left when the call reaches a machine.
max_turnsintegeroptionalConversation turn ceiling (2–100) before the agent wraps up.
abilitiesarray of ("send_email" | "send_text" | "add_tag" | "remove_tag" | "add_to_list" | "remove_from_list" | … 13 more)optionalWhat this agent may DO on a call, beyond talking — it composes the content itself (it writes the email, picks the tag, decides the moment). REPLACES the whole list; pass [] to take everything away. Some of these reach real people and spend the account's money the moment the agent decides to use them — 'send_email' and 'send_text' send real messages from the account's own domain and number, and 'add_to_campaign' starts a broadcast to them — so granting those is standing authorization for an AI to do that unsupervised, without a human seeing the wording first. See ai_agents.list_abilities.
ability_guardrailsmap of string → stringoptionalOptional owner-written when/why instructions keyed by ability. REPLACES the whole rule map; omit a key or pass an empty object to let the AI use its judgment. Rules only affect enabled abilities.
booking_event_type_idsarray of (string (uuid))optionalWhich appointment types this agent may offer, book, reschedule or cancel — booking_event_types ids, from booking.list_event_types. REPLACES the whole list; pass [] to go back to the default, which is every ACTIVE appointment type in the account. A non-empty list is a hard limit rather than an instruction: a type that is not on it is never put into the agent's tool options, so it cannot be named or booked on a call at all. An id that no longer exists, or names an inactive type, simply narrows the list further — it never widens it, so an agent whose only allowed type is archived loses its booking tools rather than regaining the whole calendar.

Example

curl -X POST https://app.chirply.io/api/v1/actions/ai_agents.update \
  -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 ai_agents_update at https://app.chirply.io/api/mcp, same bearer token, same input.

Ingest a document from a URL

brain.add_document_from_urlwriteconfirm

Fetch a document from a URL, extract its text, and store it as knowledge — the machine-surface equivalent of the Brain's upload button (binary uploads can't ride a tool call). TXT/MD/CSV/TSV/JSON are decoded in-process for free; PDF/DOCX/DOC/ODT/RTF/XLSX/XLS/HTML are read by Firecrawl, which SPENDS THE WORKSPACE'S FIRECRAWL CREDITS and needs Firecrawl connected. Pass item_id to REPLACE an existing item's content (its old source documents are removed). Files over 20 MB, and scans with no text layer, are refused with the reason.

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
urlstring (uri)requiredPublic URL of the document to fetch.
topic_idstring (uuid)optionalTopic for a NEW knowledge item. Required unless item_id is given.
item_idstring (uuid)optionalExisting knowledge item to replace the content of.
titlestringoptionalItem title. Defaults to the document's filename.
descriptionstringoptionalShort note about the document.
contentstringoptionalExtra text to keep alongside the extracted document text.

Example

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

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

Add a knowledge item

brain.add_knowledgewriteconfirm

Add a knowledge item to a topic by typing the text in. This is the same column an uploaded document or a crawled page lands in, so the agent reads it by the identical path. Content may be left empty as a stub.

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
topic_idstring (uuid)requiredTopic this knowledge belongs to.
titlestringrequiredWhat this item covers. Shown in the Brain list and how a person finds it again.
descriptionstringoptionalShort note about when this item applies. Internal, for whoever curates the topic.
contentstringoptionalThe knowledge itself, in the agent's own words — this is the text an agent reads and answers from on a live call. When editing, it REPLACES the whole body rather than appending to it. Default: ""

Example

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

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

Stop a website crawl

brain.cancel_crawlwriteconfirm

Stop a crawl that is still queued or running, so it stops spending Firecrawl credits. Pages already imported stay in the Brain, and a canceled crawl can't be resumed — start a new one instead.

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 crawl job to stop.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.cancel_crawl \
  -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 brain_cancel_crawl at https://app.chirply.io/api/mcp, same bearer token, same input.

Preview what the AI would read

brain.composeread

Compose the exact knowledge block an AI writer is handed for one scope — the whole Brain, chosen topics, chosen entries, or nothing — and report how many topics, entries and words it resolves to and whether it had to be cut to fit the prompt budget. Use it to check a scope before paying for a generation; it is read-only, generates nothing, and contacts no provider.

Parameters

FieldTypeRequiredDescription
scopeobjectrequiredThe slice of the Knowledge Brain to compose. The same object every AI writing capability accepts.
scope.mode"none" | "all" | "selection"requirednone = write from the brief alone; all = use the whole Knowledge Brain; selection = use only the topics and entries named below.
scope.topic_idsarray of (string (uuid))optionalKnowledge Brain topic ids to use in full, including every entry inside them. Ignored unless mode is 'selection'. Get ids from brain.list_topics. Default: []
scope.item_idsarray of (string (uuid))optionalIndividual knowledge-entry ids to use, for topics not taken in full. Combines with topic_ids. Ignored unless mode is 'selection'. Get ids from brain.list_knowledge. Default: []
max_charactersintegeroptionalCharacter ceiling to compose against, so you can see whether a scope fits a given prompt budget. Defaults to the ceiling AI writing surfaces use. Default: 20000
include_textbooleanoptionalReturn the composed text itself. Turn it off to get only the counts. Default: true

Example

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

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

Crawl a website into the Brain

brain.crawl_websitewriteconfirm

Crawl a website (or a single page) with Firecrawl and import each page as a knowledge item in a topic. THIS SPENDS THE WORKSPACE'S FIRECRAWL CREDITS — roughly one per page crawled — so keep page_limit tight. Firecrawl must be connected. The crawl runs in the background for minutes; poll brain.get_crawl for progress. Re-crawling the same URL UPDATES the items it produced before rather than duplicating them, which is also how you re-ingest a site that has changed.

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
urlstringrequiredWebsite or page address to crawl.
topic_idstring (uuid)requiredTopic the crawled pages become knowledge items in.
mode"single" | "site"optional'single' takes just that page; 'site' follows links. Default: "site"
page_limitintegeroptionalMax pages to crawl (1–250). Each page costs credits. Default: 25
max_depthintegeroptionalLink depth from the seed URL (0–5). Default: 2
include_pathsstring[]optionalRegex path patterns a URL must match to be crawled. Default: []
exclude_pathsstring[]optionalRegex path patterns that exclude a URL. Default: []
crawl_entire_domainbooleanoptionalFollow sibling/parent URLs, not just children of the seed path. Default: false
allow_subdomainsbooleanoptionalFollow links into subdomains. Default: false

Example

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

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

Create a knowledge topic

brain.create_topicwrite

Create a topic in the AI Brain. Topic names are unique per account and become merge-field slugs ({{brain.pricing_faq}}), so pick something an agent can be pointed at.

Parameters

FieldTypeRequiredDescription
namestringrequiredTopic name. Unique per account, and it becomes the merge-field slug ({{brain.pricing_faq}}), so pick something an agent can be pointed at.
descriptionstringoptionalWhat belongs in this topic. An internal note for whoever curates it; agents answer from the items inside, not from this line.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.create_topic \
  -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 brain_create_topic at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete a crawl from the history

brain.delete_crawlwriteconfirm

Remove a crawl job from the history panel. The knowledge items it imported are left in place — delete those separately if you want them gone.

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 crawl job to remove.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.delete_crawl \
  -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 brain_delete_crawl at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete a knowledge item

brain.delete_knowledgewriteconfirm

Permanently delete a knowledge item and any source documents stored behind it. Agents stop answering from it on their next call. 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 knowledge item to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.delete_knowledge \
  -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 brain_delete_knowledge at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete a knowledge topic

brain.delete_topicwriteconfirm

Permanently delete a knowledge topic AND every knowledge item inside it. Agents scoped to this topic lose that knowledge on their next call. 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 topic to delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.delete_topic \
  -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 brain_delete_topic at https://app.chirply.io/api/mcp, same bearer token, same input.

Check a crawl's progress

brain.get_crawlread

Fetch one website crawl job — where it is, how many pages have been crawled, imported and skipped, credits used, and the reason if it failed. Poll this after brain.crawl_website; a crawl runs for minutes.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe crawl job's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.get_crawl \
  -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 brain_get_crawl at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a knowledge item

brain.get_knowledgeread

Fetch one knowledge item with its full body text — exactly what an agent reads to a caller — plus where it came from and when it was last extracted.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe knowledge item's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.get_knowledge \
  -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 brain_get_knowledge at https://app.chirply.io/api/mcp, same bearer token, same input.

List website crawls

brain.list_crawlsread

List website crawl jobs with their ingestion status — queued, crawling, done, failed or canceled — plus pages found, imported and skipped, and the Firecrawl credits each one used.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
topic_idstring (uuid)optionalOnly crawls into this topic.
status"queued" | "running" | "completed" | "failed" | "canceled"optionalOnly crawls in this state.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.list_crawls \
  -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 brain_list_crawls at https://app.chirply.io/api/mcp, same bearer token, same input.

List source documents

brain.list_documentsread

List the original documents stored behind knowledge items — filename, size, which extractor read it and how much text came out. Each row links to a download of the original.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
item_idstring (uuid)optionalOnly documents behind this knowledge item.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.list_documents \
  -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 brain_list_documents at https://app.chirply.io/api/mcp, same bearer token, same input.

List knowledge items

brain.list_knowledgeread

List the AI Brain's knowledge items with their provenance — typed in by hand, extracted from an uploaded document, or crawled off a website — and how many words each holds. Body text is omitted unless you ask for it.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
topic_idstring (uuid)optionalOnly items in this topic.
source_type"manual" | "file" | "url"optionalOnly items that came from this source.
querystringoptionalText to match in the title or description.
include_contentbooleanoptionalInclude each item's full body text. Default: false

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.list_knowledge \
  -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 brain_list_knowledge at https://app.chirply.io/api/mcp, same bearer token, same input.

List knowledge topics

brain.list_topicsread

List the AI Brain's topics — the folders of knowledge agents answer from, and the unit an agent's knowledge scope is set in.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
querystringoptionalText to match in the topic name or description.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.list_topics \
  -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 brain_list_topics at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit a knowledge item

brain.update_knowledgewriteconfirm

Update a knowledge item's title, description or body text. Provenance is deliberately kept: a crawled page someone tidied up by hand is still that page, which is what lets a re-crawl update this item instead of duplicating it.

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 knowledge item to edit.
titlestringoptionalWhat this item covers. Shown in the Brain list and how a person finds it again.
descriptionstring (or null)optionalShort note about when this item applies. Internal, for whoever curates the topic.
contentstringoptionalThe knowledge itself, in the agent's own words — this is the text an agent reads and answers from on a live call. When editing, it REPLACES the whole body rather than appending to it.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.update_knowledge \
  -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 brain_update_knowledge at https://app.chirply.io/api/mcp, same bearer token, same input.

Rename a knowledge topic

brain.update_topicwrite

Change a knowledge topic's name or description. Its knowledge items are untouched.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe topic to edit.
namestringoptionalTopic name. Unique per account, and it becomes the merge-field slug ({{brain.pricing_faq}}), so pick something an agent can be pointed at.
descriptionstring (or null)optionalWhat belongs in this topic. An internal note for whoever curates it; agents answer from the items inside, not from this line.

Example

curl -X POST https://app.chirply.io/api/v1/actions/brain.update_topic \
  -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 brain_update_topic 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=ai-agents — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.