Built-in Tools Reference

transferCall Always Available

Transfer the current call to a human agent or an external phone number. Supports both warm (announced) and cold (blind) transfers.

Parameters

What It Does

1. Resolves the destination: if "default" or omitted, uses the agent's transfer_number from config.
2. Sets the call state to transferring.
3. Fires a status-update webhook event with { status: "transferring", destination, mode }.
4. Uses the Twilio REST API to redirect the call to the transfer webhook endpoint.
5. Disconnects STT and TTS — Twilio handles the rest of the call.
6. Transfer mode (warm or cold) is determined by the agent's transfer_mode setting (defaults to warm).

Agent Config Required

System Prompt Example

If the caller asks to speak with a manager or says they need
a real person, use the transferCall tool. Say something like
"Sure, let me connect you with someone who can help" as the
message. Use destination "default" unless the caller gives
you a specific number.

Common Use Case

A receptionist agent that handles simple questions but transfers to a human for complex issues, scheduling, or when explicitly requested.

endCall Always Available

End the current call. The agent should use this when the conversation reaches a natural conclusion.

Parameters

What It Does

1. Logs the end reason.
2. Waits 4 seconds to allow the agent's final spoken response to finish playing.
3. Calls cleanup() with the agent-hangup end reason, which disconnects STT/TTS, saves the call log, runs call analysis, and fires the end-of-call-report webhook.

System Prompt Example

When the caller says goodbye, thanks you, or indicates
they're done, use the endCall tool. Say a natural goodbye
like "Great talking with you, have a good one!" and set the
reason to describe why the call ended.

Common Use Case

Every agent should allow natural call endings. Without this tool, calls only end via customer hangup, max duration timeout, or idle timeout.

dtmfInput Always Available

Send DTMF touch-tone digits (keypad presses). Used when the agent needs to navigate phone menus or IVR systems during outbound calls.

Parameters

What It Does

1. Sends the digits via the Twilio REST API using TwiML <Play digits="...">.
2. Reconnects the media stream after digit playback so the conversation can continue.

System Prompt Example

You are calling a pharmacy's automated system. When you hear
"Press 1 for prescriptions, press 2 for store hours", use
the dtmfInput tool to press the appropriate key. Listen
carefully to the menu options before pressing.

Common Use Case

Outbound agents that call businesses and need to navigate automated phone trees (e.g., "Press 1 for sales, press 2 for support") before reaching a human.

sendSMS Always Available

Send an SMS text message during or after the call. Can text the current caller or any phone number.

Parameters

What It Does

1. Resolves the recipient: if "caller" or omitted, sends to the caller (inbound) or the called party (outbound).
2. Sends the SMS via Twilio from the agent's phone number.
3. Tracks SMS cost: base rate + carrier surcharge, calculated per 160-character segment.
4. Logs usage and deducts from the organization's credit balance.

System Prompt Example

After confirming an appointment, use the sendSMS tool to text
the caller a confirmation. Set "to" to "caller" and include
the date, time, and address in the message. Always tell the
caller "I'll text you the details" before sending.

Common Use Case

Sending appointment confirmations, links, addresses, reference numbers, or any information that is easier to read than hear over the phone.

pauseRecording Always Available

Pause the call recording. Use before collecting sensitive information (credit card numbers, SSNs, medical data) to maintain HIPAA, PCI-DSS, or general privacy compliance.

Parameters

What It Does

1. Checks that an active Twilio recording exists (recordingSid must be set).
2. Calls the Twilio REST API to set the recording status to paused.
3. Sets an internal recordingPaused flag to prevent double-pausing.
4. Returns an error if no recording is active or the recording is already paused.

Agent Config Required

System Prompt Example

Before asking for any credit card number, social security
number, or insurance ID, ALWAYS use pauseRecording first.
Tell the caller: "For your security, I'm pausing the
recording while you share that information."

Common Use Case

HIPAA-compliant healthcare agents, PCI-compliant payment collection, or any scenario where sensitive PII must not appear in call recordings.

resumeRecording Always Available

Resume the call recording after it was paused. Must be called after sensitive information collection is complete.

Parameters

None. This tool takes no input parameters.

What It Does

1. Checks that an active Twilio recording exists and is currently paused.
2. Calls the Twilio REST API to set the recording status back to in-progress.
3. Clears the internal recordingPaused flag.
4. Returns an error if no recording is active or the recording is not currently paused.

System Prompt Example

After the caller finishes providing their credit card or SSN,
use resumeRecording immediately. Say "Thank you, the
recording is back on" so the caller knows.

Common Use Case

Always used as the counterpart to pauseRecording. The pair creates a "recording gap" around sensitive data collection.

leaveVoicemail Always Available

Leave a voicemail message when the agent detects it has reached a voicemail system. The agent uses contextual clues (hearing "leave a message", "after the beep", etc.) to decide when to trigger this tool.

Parameters

What It Does

The handler attempts three methods in priority order:

1. Pre-generated audio: If a pre-generated voicemail audio file exists for the agent (at voicemail-audio/{agentId}.mp3), it redirects the Twilio call to a voicemail webhook that plays the MP3.
2. Live TTS: If no pre-generated audio exists but voicemail_message is configured on the agent, the message is spoken via the live TTS engine, then the call ends after 5 seconds.
3. Generic fallback: If neither is available, a generic message is spoken: "Hey [name], just giving you a call. Give me a ring back when you get a chance."

After the voicemail plays, the call ends with the voicemail-left end reason.

Agent Config Required

System Prompt Example

If you detect that you have reached a voicemail system --
for example you hear "please leave a message", "not
available", "after the beep", or a long silence followed by
a beep -- immediately use the leaveVoicemail tool. Set
detected_reason to describe what you heard.

Common Use Case

Outbound sales or appointment reminder agents that call contacts who may not answer. The agent detects voicemail and leaves a consistent, professional message every time.

addCallTag Always Available

Tag the current call with a label for categorization and analytics. Multiple tags can be added to a single call. Tags are persisted to the call_logs table immediately.

Parameters

What It Does

1. Normalizes the tag: lowercases, trims whitespace, replaces spaces with hyphens.
2. Checks for duplicates — if the tag already exists on this call, returns early.
3. Appends to the in-memory callTags array.
4. Immediately persists to the database by updating call_logs.tags (stored as JSON).
5. Tags are indexed with a GIN index for fast querying and filtering in analytics.

System Prompt Example

Tag every call based on the outcome:
- "appointment-booked" if an appointment is scheduled
- "callback-requested" if the caller wants a callback
- "sales-qualified" if the caller is a potential customer
- "not-interested" if they decline
- "wrong-number" if they say you have the wrong number
Add tags silently. Never tell the caller you are tagging.

Common Use Case

Categorizing calls for reporting dashboards: filter by tag to see how many calls were sales-qualified, how many appointments were booked, etc.

switchLanguage Always Available

Change the conversation language mid-call. Switches both the STT (speech-to-text) language model and the agent's response language.

Parameters

Supported Languages

What It Does

1. Maps the language code to the appropriate Deepgram STT model code (e.g., pt maps to pt-BR).
2. Switches the STT provider's language via stt.switchLanguage().
3. Updates config.language and config.sttLanguage for subsequent TTS calls.
4. Speaks the provided confirmation message in the new language.

System Prompt Example

If the caller begins speaking Spanish or asks "habla
espanol?", use the switchLanguage tool with language "es" and
a confirmation message in Spanish like "Claro, continuamos
en espanol. Como le puedo ayudar?" Then continue the
conversation entirely in Spanish.

Common Use Case

Multilingual support lines where a single agent handles callers in different languages. The agent detects the caller's language and seamlessly switches.

setDisposition Conditional

Set the call's disposition (outcome code). This tool is only available when the agent has a dispositions array configured. The disposition is validated against that list.

Parameters

What It Does

1. Validates the disposition against the agent's configured dispositions array. Returns an error listing valid options if invalid.
2. Sets this.disposition on the call session.
3. Immediately persists to the call_logs.disposition column in the database.
4. Only one disposition can be set per call (last one wins if called multiple times).

Agent Config Required

System Prompt Example

Before ending the call, use setDisposition to record the
outcome. Choose the most appropriate option:
- "sale-completed" if a purchase was made
- "appointment-set" if an appointment was booked
- "not-interested" if the caller declined
- "callback" if they want to be called back
Set the disposition silently. Do NOT ask the caller what
the disposition should be.

Common Use Case

Sales teams that need structured outcome tracking. Dispositions feed into CRM integrations and reporting dashboards to track conversion rates, callback queues, and agent performance.