Skip to main content

Phone & SMS

Let an agent place real outbound phone calls, control the call it's on (hang up, transfer, take a voicemail, press keys, pause the recording, look up the caller), and send text messages.

These tools ride on your company's phone numbers: every call originates from a phone configuration you own, referenced by phoneConfigId. The phone configuration also decides which agent answers the line, so a call placed by a tool becomes a live voice conversation with that agent. Calls are metered against your company's call-minute limit. Texts additionally need your company's Text Messaging registration and the recipient's consent.

Make Phone Call TOOLMAKE_PHONE_CALL​

Places an outbound call from the phone number in phoneConfigId to toPhoneNumber and returns as soon as the carrier accepts it — the conversation itself runs asynchronously through the voice pipeline. The opening line can be static (initialMessage) or generated live: when initialMessagePrompt is set, the phone configuration's agent runs the prompt before the call connects and speaks the generated response when the recipient answers. Setting initialMessagePrompt or voicemailAudioUrl implicitly enables answering-machine detection, so a voicemail can be left when no one picks up — voicemailAudioUrl accepts an audio URL, or plain text that is converted to speech with the agent's voice. conferenceParticipants dials additional numbers into the call as it starts, and skipInitialMessage keeps the AI silent for a human-to-human bridge.

The result confirms initiation, not outcome: {"success": true, "callSid": ..., "fromPhoneNumber": ..., "toPhoneNumber": ..., "status": ..., "amdEnabled": ...}, plus fields describing the generated message, voicemail, and conference setup when used. How the call actually went (answered, voicemail left, which key was pressed, the transcript) lands in your company's Phone calls table once the call ends.

Call modes​

mode decides what happens when the other person picks up. It defaults to AI_CONVERSATION.

ModeWhat happensFields it uses
AI_CONVERSATIONThe number's agent holds a live conversation, as described above.initialMessage, initialMessagePrompt, voicemailAudioUrl, and the rest
PLAY_MESSAGEA spoken message is played and no AI is involved. Use it for reminders, alerts, and confirmations.message, keypadOptions, repeatMessage
CONNECT_TO_PEOPLEOnce the other person answers, your staff are rung and joined to the call. No AI is involved.ring

Play a message. message is the text that's spoken. Add keypadOptions to ask for a key press, for example {"1": "Confirmed", "2": "Reschedule"}. The label of the key the person presses is saved in the call's keypad_response column in the Phone calls table, so a trigger can act on it. repeatMessage sets how many times the message repeats when no key is pressed (default 1). If an answering machine picks up, the voicemail settings work the same way as in an AI call.

Connect to people. ring lists who to ring once the call is answered, in the same shape as a number's ring settings: targets (a list of { "to": ..., "label": ..., "ringSeconds": ... }, where to is a phone number in E.164 format or client:<identity> for a teammate's browser phone), strategy (SIMULTANEOUS or SEQUENTIAL), ringSeconds, requireKeyPress, whisper, callerId, waitAudio, maxTotalSeconds, and noAnswer (what to do when nobody picks up). If nobody picks up and you didn't set noAnswer, the person you called hears a short apology and the call ends.

Ringing, retries, and calling hours​

  • ringTimeoutSeconds: how long to let the phone ring before the call counts as not answered, from 5 to 120 (default 30). Keep it under about 25 seconds if you'd rather not reach voicemail, or raise it to give people time to get to the phone.
  • retry: try again when the call doesn't go through. onBusy, onNoAnswer, and onFailed choose which outcomes to retry, maxAttempts is the total number of tries including the first, from 1 to 5 (default 1, meaning no retries), and delayMinutes is the wait between tries, from 1 to 1440 (default 10).
  • callingHours: only call during these hours, in the time zone you give (usually the recipient's). timezone (for example America/Chicago), weekly (a list of { "day": "MONDAY", "open": "09:00", "close": "17:00" }, in the same format as business hours), and outsideHours: WAIT (default) places the call as soon as the next window opens, and FAIL doesn't place it and returns an error instead. Retries that land outside the hours wait for the next window too.

Waiting calls and retries aren't hidden. Each one is a one-time scheduled job that runs this same tool with the same settings, so you can see when the next try will happen, and cancel it, on the Scheduled Jobs page.

Retry a reminder call, weekdays 9 to 6 only
{
  "ringTimeoutSeconds": 25,
  "retry": { "onBusy": true, "onNoAnswer": true, "maxAttempts": 3, "delayMinutes": 60 },
  "callingHours": {
    "timezone": "America/Chicago",
    "weekly": [
      { "day": "MONDAY", "open": "09:00", "close": "18:00" },
      { "day": "TUESDAY", "open": "09:00", "close": "18:00" },
      { "day": "WEDNESDAY", "open": "09:00", "close": "18:00" },
      { "day": "THURSDAY", "open": "09:00", "close": "18:00" },
      { "day": "FRIDAY", "open": "09:00", "close": "18:00" }
    ],
    "outsideHours": "WAIT"
  }
}

Settings for this call​

Every call follows the call settings of the number it's placed from: transcript, recording, Call Redaction, call limits, caller info, voice and language, AI call behavior, and answering machine detection. Set callSettings to override them for this call only. Each section you include (transcript, recording, redaction, limits, callerInfo, speech, ai, answeringMachine) replaces that whole section of the number's settings, and sections you leave out keep the number's values. The sections are described in the call settings object.

Record this call and stop it after 10 minutes
{
  "callSettings": {
    "recording": { "save": true, "announcement": "This call may be recorded." },
    "limits": { "maxDurationMinutes": 10 }
  }
}

Example​

Tool config
{
  "toolType": "MAKE_PHONE_CALL",
  "phoneConfigId": "V1StGXR8Z5",
  "toPhoneNumber": "@@{TO_PHONE_NUMBER}",
  "initialMessage": "",
  "initialMessagePrompt": "Greet @@{CUSTOMER_NAME} and say you are calling about their open support ticket.",
  "environmentVariables": {},
  "promptTemplateVariables": {},
  "voicemailAudioUrl": "Hi, this is Acme Support calling about your ticket. We'll try again tomorrow.",
  "conferenceParticipants": [],
  "skipInitialMessage": false,
  "clientDisplayMessage": ""
}
Tool config: appointment reminder with a key press
{
  "toolType": "MAKE_PHONE_CALL",
  "phoneConfigId": "V1StGXR8Z5",
  "toPhoneNumber": "@@{TO_PHONE_NUMBER}",
  "mode": "PLAY_MESSAGE",
  "message": "Hi, this is Acme Dental reminding you of your appointment tomorrow at 10 AM. Press 1 to confirm, or 2 if you need to reschedule.",
  "keypadOptions": { "1": "Confirmed", "2": "Reschedule" },
  "repeatMessage": 2
}

Configuration fields

  • Name
    phoneConfigId
    Type
    string (ID)
    Description
    Which phone number to call from — the only true config-level field (persisted on the tool). References a phone configuration by ID.
  • Name
    toPhoneNumber
    Type
    string
    Description
    Required string value.
  • Name
    initialMessage
    Type
    string
    Description
    Required string value.
  • Name
    initialMessagePrompt
    Type
    string
    Description
    Prompt sent to the LLM to dynamically generate the initial message before the call connects. When provided, the agent conversation starts before the call is placed, the LLM generates a response to this prompt, and that response is spoken when the recipient answers. AMD (Answering Machine Detection) is automatically enabled when this is set, allowing the message to be left as voicemail if no one answers.
  • Name
    environmentVariables
    Type
    object
    Description
    Prompt sent to the LLM to dynamically generate the initial message before the call connects. When provided, the agent conversation starts before the call is placed, the LLM generates a response to this prompt, and that response is spoken when the recipient answers. AMD (Answering Machine Detection) is automatically enabled when this is set, allowing the message to be left as voicemail if no one answers.
  • Name
    promptTemplateVariables
    Type
    object
    Description
    Prompt sent to the LLM to dynamically generate the initial message before the call connects. When provided, the agent conversation starts before the call is placed, the LLM generates a response to this prompt, and that response is spoken when the recipient answers. AMD (Answering Machine Detection) is automatically enabled when this is set, allowing the message to be left as voicemail if no one answers.
  • Name
    voicemailAudioUrl
    Type
    string
    Description
    URL to a WAV/MP3 audio file to play as voicemail when AMD detects an answering machine. When set, AMD is automatically enabled. If a machine answers, this audio is played and the call hangs up.
  • Name
    voicemailBehavior
    Type
    string
    Description
    What to do when an answering machine answers instead of a person: `LEAVE_MESSAGE` (default), `HANG_UP`, or `STAY_ON`. With `LEAVE_MESSAGE` the call ends as soon as Twilio confirms the message finished playing. `HANG_UP` ends the call without saying anything, for calls that are only worth making if a person picks up.
  • Name
    conferenceParticipants
    Type
    array<string>
    Description
    Additional phone numbers to dial into the conference when the call starts. Each participant will be called and joined to the conference when they answer.
  • Name
    skipInitialMessage
    Type
    boolean
    Description
    When true, the AI agent will not speak an initial message when the call connects. Useful when conference participants are set and the call should be a direct human-to-human connection with the AI silently listening.
  • Name
    clientDisplayMessage
    Type
    string
    Description
    Custom message passed to all browser client participants via connection.customParameters. Applied to all client: participants in the conference when they are dialed.
  • Name
    mode
    Type
    string · optional
    Description
    `AI_CONVERSATION` (default): the number's AI talks with the callee. `PLAY_MESSAGE`: play `#message` (optionally asking for a key from `#keypadOptions`). `CONNECT_TO_PEOPLE`: once the callee answers, ring the people in `#ring` into the call. Optional.
  • Name
    message
    Type
    string · optional
    Description
    PLAY_MESSAGE: what is said, in the number's AI voice. Optional for other modes.
  • Name
    keypadOptions
    Type
    object · optional
    Description
    PLAY_MESSAGE: digit to label, e.g. {"1": "Confirmed"}; the chosen label lands in the call log's keypad_response. Optional.
  • Name
    repeatMessage
    Type
    integer · optional
    Description
    PLAY_MESSAGE: how many times the message plays when no valid key is pressed. Optional; default 1.
  • Name
    ring
    Type
    object · optional
    Description
    CONNECT_TO_PEOPLE: who to ring and how; noAnswer defaults to a short apology and hang-up. Optional for other modes.
  • Name
    callSettings
    Type
    object · optional
    Description
    Per-call override of the from-number's call settings; each section given replaces that whole section. Optional.
  • Name
    ringTimeoutSeconds
    Type
    integer · optional
    Description
    How long the callee's phone rings before the call counts as not answered: 5..120 seconds. Optional; default 30.
  • Name
    retry
    Type
    object · optional
    Description
    Call again when the call doesn't connect (busy, no answer, failed), up to maxAttempts calls in all, delayMinutes apart. Each retry is a scheduled event you can see and cancel. Optional; default no retry.
  • Name
    callingHours
    Type
    object · optional
    Description
    Only place the call inside these hours (in their own time zone). Outside them the call waits for the next opening (outsideHours WAIT, the default, as a scheduled event) or fails (FAIL). Optional.

Add Conference Participant TOOLPHONE_ADD_CONFERENCE_PARTICIPANT​

Dials another participant into the conference of the phone call the agent is currently on — give this tool to an agent that answers or places calls so it can loop in a human on request. phoneNumber accepts a regular phone number or client:{identity} for a browser-based client, and the participant joins asynchronously when they answer. Once a participant is added, the AI switches to listen-only mode so the humans can talk directly. Outside an active call the tool is a graceful no-op: it returns success with a note that the person will be looped in, without dialing anyone.

During a call the result is {"success": true, "message": ..., "phoneNumber": ..., "conferenceRoom": ..., "participantCallSid": ...}.

Example​

Tool config
{
  "toolType": "PHONE_ADD_CONFERENCE_PARTICIPANT",
  "phoneNumber": "@@{PARTICIPANT_PHONE_NUMBER}",
  "displayMessage": "Connecting you with the caller now."
}

Configuration fields

  • Name
    phoneNumber
    Type
    string
    Description
    Required string value.
  • Name
    displayMessage
    Type
    string
    Description
    Custom message passed to browser clients via connection.customParameters

Call controls​

These tools let an agent that is on a phone call act on the call itself: hang up, transfer, take a message, press keys, pause the recording, or look up who it's talking to. Give them to any agent or multi-agent that answers or places calls. From the number's detail page, the Call tools card shows which ones the answering agent already has and adds the rest in one click.

They work on the call the agent is currently on, so none of them takes a phone number or call ID for "this call". When the agent isn't on a call (for example, in a chat or a test run in the builder), each one does nothing and returns {"success": true, "onCall": false, "message": ...}, so it's safe to give them to an agent that also handles chat and text messages.

Every result has the shape {"success": ..., "onCall": ..., "message": ...}, plus the extra fields listed for each tool. message is plain language, so the agent can repeat it to the caller if it needs to. All fields accept @@{VAR_NAME} placeholders.

Hang Up Call TOOLPHONE_HANG_UP​

Ends the call when the agent decides the conversation is over. The agent finishes what it's saying first, so the caller hears the goodbye before the line goes quiet. The call is logged with ended_by set to AGENT.

  • reason: kept for your records.
  • goodbyeMessage: a fixed goodbye spoken just before hanging up, such as "Thanks for calling Acme. Goodbye!" Use it when you want every call to end with the same words, whatever the agent last said.
  • delaySeconds: wait this long before hanging up, from 0 to 10, so a caller who's still saying goodbye isn't cut off mid-word.

Tell the agent when to use it in its instructions, for example: "When the caller says they have everything they need, say goodbye and then hang up." For calls that should end whenever the agent says a particular phrase, the number's hang-up phrases do the same job without a tool.

Example​

Tool config
{
  "toolType": "PHONE_HANG_UP",
  "reason": "Caller's question was answered",
  "goodbyeMessage": "Thanks for calling Acme. Have a great day!",
  "delaySeconds": 1
}

Configuration fields

  • Name
    reason
    Type
    string · optional
    Description
    Why the agent is ending the call, kept with the call record. Optional.
  • Name
    goodbyeMessage
    Type
    string · optional
    Description
    Said to the caller just before hanging up, after the agent's own reply, e.g. "Thanks for calling, goodbye." Optional.
  • Name
    delaySeconds
    Type
    integer · optional
    Description
    Extra seconds to wait after the last words before hanging up, 0 to 10. Optional; defaults to no wait.

Transfer Call TOOLPHONE_TRANSFER_CALL​

Hands the caller to a person. to is a phone number in E.164 format (for example +14155550100), client:<identity> to ring a teammate's browser phone, or the name of an entry in the tool's directory.

  • mode: COLD (default) connects the caller and the agent leaves the call as soon as the person answers. WARM keeps the agent on the line in listen-only mode, so it can hear the handoff without speaking.
  • announcement: what the agent says to the caller before transferring, such as "Let me connect you with our billing team."
  • ringSeconds: how long to ring the person before giving up (default 25).
  • onNoAnswer: what happens if the person doesn't pick up. RESUME_AI (default) brings the agent back so it can keep helping the caller, TAKE_VOICEMAIL lets the caller leave a message, and HANG_UP ends the call.
  • whisper: a short message only the person answering hears before they're connected, such as "Transfer from the AI receptionist: caller needs a refund." The caller doesn't hear it.
  • requireKeyPress: the person who answers must press 1 to accept the call. Turn it on when you transfer to cell phones, so the person's own voicemail can't pick up the caller. If they don't press 1, the onNoAnswer step runs.
  • clientDisplayMessage: shown on the teammate's screen when to is a browser phone, for example "Caller needs help with a refund."

The caller never sits in silence: if the person is busy, doesn't answer, or hangs up, the onNoAnswer step runs. The person the call was transferred to is saved in the call's transferred_to column.

Add Conference Participant is the older way to bring someone in. It works like a warm transfer with no fallback, so use Transfer Call for new agents.

Transfer directory​

Give the tool a directory and the agent can choose who to transfer to by name, without seeing or typing phone numbers. Each entry has a name, a to (a phone number or client:<identity>), and an optional description that tells the agent when to pick it. The names and descriptions are listed in the tool's description, so the agent knows its choices, and it passes the entry's name as to. Leave to as a placeholder such as @@{TRANSFER_TO} so the agent fills it in.

allowAnyNumber controls whether the agent can also transfer to a number that isn't in the directory. It defaults to false when the tool has a directory, so the agent can only reach the people you listed, and true when it doesn't, so to can be any number.

Examples​

Tool config: one fixed number
{
  "toolType": "PHONE_TRANSFER_CALL",
  "to": "@@{BILLING_TEAM_PHONE}",
  "mode": "COLD",
  "announcement": "I'll connect you with our billing team now. One moment.",
  "ringSeconds": 25,
  "onNoAnswer": "TAKE_VOICEMAIL"
}
Tool config: a directory the agent picks from
{
  "toolType": "PHONE_TRANSFER_CALL",
  "to": "@@{TRANSFER_TO}",
  "directory": [
    { "name": "Billing", "to": "+14155550100", "description": "Refunds, invoices, and payment problems." },
    { "name": "Scheduling", "to": "+14155550101", "description": "Booking, moving, or canceling appointments." },
    { "name": "Office manager", "to": "client:<identity>", "description": "Complaints, or when the caller asks for a manager." }
  ],
  "allowAnyNumber": false,
  "announcement": "Let me connect you now. One moment.",
  "whisper": "Call transferred by the Acme receptionist.",
  "requireKeyPress": true,
  "onNoAnswer": "RESUME_AI"
}

Configuration fields

  • Name
    to
    Type
    string
    Description
    Who to bring on: a phone number like +15551234567, `client:` for an Autessa browser phone, or, when a `#directory` is set, the name of one of its entries.
  • Name
    mode
    Type
    string · optional
    Description
    `COLD` (default): the agent drops off once they pick up. `WARM`: the agent stays on, listening only. Optional.
  • Name
    announcement
    Type
    string · optional
    Description
    Said to the caller before dialling, e.g. "Let me connect you with our billing team." Optional.
  • Name
    ringSeconds
    Type
    integer · optional
    Description
    How many seconds to ring before giving up. Optional; defaults to 25.
  • Name
    onNoAnswer
    Type
    string · optional
    Description
    What happens when nobody picks up: `RESUME_AI` (default), `TAKE_VOICEMAIL` or `HANG_UP`. Optional.
  • Name
    clientDisplayMessage
    Type
    string · optional
    Description
    Shown on the browser phone being rung, when `to` is a browser phone. Optional.
  • Name
    whisper
    Type
    string · optional
    Description
    Said only to the person being brought on, before they are connected, e.g. "Transfer from the front desk: a caller asking about a refund." The caller doesn't hear it. Optional.
  • Name
    requireKeyPress
    Type
    boolean · optional
    Description
    The person must press 1 to accept the call, so their own voicemail can't pick it up and leave the caller talking to a recording. Optional; defaults to false.
  • Name
    directory
    Type
    array<object> · optional
    Description
    The people this tool can transfer to, each with a name the agent uses as `to`. When set, the agent passes a name ("Billing") and the tool dials that entry's number. Optional.
  • Name
    allowAnyNumber
    Type
    boolean · optional
    Description
    Whether `to` may be a number or browser phone that is not in the `#directory`. Optional; defaults to true without a directory and false with one, so an agent given a directory can only reach the people in it.
  • Name
    name
    Type
    string
    Description
    What the agent calls them, e.g. "Billing" or "Dr. Lee". Matched without regard to case.
  • Name
    to
    Type
    string
    Description
    Their phone number like +15551234567, or `client:` for an Autessa browser phone.
  • Name
    description
    Type
    string · optional
    Description
    When to transfer to them, e.g. "Refunds and invoice questions". Optional.

Take a Voicemail TOOLPHONE_TAKE_VOICEMAIL​

Lets the caller leave a message, for example when they ask for someone who isn't available. The agent stops talking, the greeting is played, there's a beep, and the caller's message is recorded. The recording and its transcript are saved in the call's voicemail_recording and voicemail_transcript columns, and the call's status becomes VOICEMAIL_RECEIVED. The call ends when the caller finishes, so this is the agent's last step on the call. That's what the Email me new voicemails automation listens for.

  • greeting: played before the beep. Leave it empty for a standard greeting.
  • greetingAudio: a recording to play instead of greeting, as an https:// link or an audio file you uploaded for the number.
  • maxSeconds: the longest message the caller can leave (default 120).
  • finishOnKey: the key the caller presses to finish the message (default #). Set it to "" so no key ends the message.
  • transcribe: set to false to keep only the audio (default true).
  • notifyEmails: up to 5 email addresses that get the voicemail as soon as it's saved, with its transcript and a link to the call. Use it when this agent's voicemails should go to different people than the number's Email me new voicemails list.

If the number has Call Redaction turned on, the voicemail goes through it too.

Example​

Tool config
{
  "toolType": "PHONE_TAKE_VOICEMAIL",
  "greeting": "Please leave your name, number, and a short message after the beep, and we'll call you back today.",
  "maxSeconds": 120,
  "finishOnKey": "#",
  "transcribe": true,
  "notifyEmails": ["frontdesk@example.com"]
}

Configuration fields

  • Name
    greeting
    Type
    string · optional
    Description
    What the caller hears before the tone, e.g. "Please leave your name and number." Optional.
  • Name
    greetingAudio
    Type
    string · optional
    Description
    A recording played instead of `#greeting`: an https link to an mp3 or wav file, or an `s3://` audio URI from the phone number's audio upload link. Optional.
  • Name
    maxSeconds
    Type
    integer · optional
    Description
    The longest message the caller can leave, in seconds (1 to 600). Optional; defaults to 120.
  • Name
    finishOnKey
    Type
    string · optional
    Description
    The key the caller presses to finish their message early: one of 0-9, `*` or `#`. An empty value means no key ends it. Optional; defaults to `#`.
  • Name
    transcribe
    Type
    boolean · optional
    Description
    Whether to transcribe the message into the Phone calls table. Optional; defaults to true.
  • Name
    notifyEmails
    Type
    array<string> · optional
    Description
    Email addresses (at most 5) told about each new message, with its transcript. Optional.

Press Phone Keys TOOLPHONE_PRESS_KEYS​

Presses keys on the phone keypad, the way a person would, so an agent placing a call can get through another company's phone menu ("press 2 for billing") or enter an extension. digits can contain 0–9, *, and #. Add w for a half-second pause between keys, for example 1ww4421#.

Leave digits as a placeholder the agent fills in when it hears the menu, or fix it for a menu that never changes.

Some phone systems miss key presses that are too short or too close together. If presses aren't recognized, slow them down:

  • toneMs: how long each key is held, from 40 to 1000 milliseconds (default 160).
  • gapMs: the pause between keys, from 40 to 2000 milliseconds (default 100).

Example​

Tool config
{
  "toolType": "PHONE_PRESS_KEYS",
  "digits": "@@{DIGITS}",
  "toneMs": 250,
  "gapMs": 200
}

Configuration fields

  • Name
    digits
    Type
    string
    Description
    The keys to press, in order: 0-9, `*` and `#`. Use `w` for a half-second pause.
  • Name
    toneMs
    Type
    integer · optional
    Description
    How long each key's tone plays, in milliseconds (40 to 1000). Optional; defaults to 160.
  • Name
    gapMs
    Type
    integer · optional
    Description
    Silence between keys, in milliseconds (40 to 2000). Optional; defaults to 100.

Pause or Resume Call Recording TOOLPHONE_PAUSE_RECORDING​

Pauses the call recording, or resumes it. action is PAUSE or RESUME. Use it around anything you don't want in the recording, such as a card number read out loud: tell the agent to pause before asking for the number and resume once it's been collected. When the number isn't recording the call, the tool does nothing and says so in message.

Set autoResumeSeconds on a PAUSE to resume the recording by itself after that many seconds, from 5 to 600. It's a safety net: if the agent forgets to resume, the rest of the call is still recorded.

Pausing only affects the recording. The agent still hears everything, and what was said stays in the agent's conversation history. To remove personal info from recordings and transcripts automatically, use Call Redaction.

Example​

Tool config
{
  "toolType": "PHONE_PAUSE_RECORDING",
  "action": "PAUSE",
  "autoResumeSeconds": 90
}

Configuration fields

  • Name
    action
    Type
    string
    Description
    `PAUSE` or `RESUME`.
  • Name
    autoResumeSeconds
    Type
    integer · optional
    Description
    When pausing, start recording again on its own after this many seconds (5 to 600), so a forgotten RESUME never loses the rest of the call. Ignored when resuming. Optional; by default the recording stays paused until resumed.

Get Caller Info TOOLPHONE_GET_CALLER_INFO​

Tells the agent who it's talking to and whether they've called before. During a call the result adds:

FieldWhat it holds
phoneNumberThe other person's number.
nameTheir name from the carrier's caller-ID records, when the number has caller-name lookup turned on and a name was found.
city, state, countryWhere the number is registered, as reported by the carrier.
forwardedFromThe number the call was forwarded from, if it was forwarded and the carrier reports it.
directionINBOUND or OUTBOUND.
recentCallsEarlier calls with this number from your Phone calls table, newest first, each with startedAt, direction, durationSeconds, status, and transcriptExcerpt (the first 500 characters of the transcript).

Fields the carrier didn't provide are empty. The same caller details are also available without a tool call, as built-in variables like @@{callerName}.

All settings are optional:

  • fields: which of the fields above to return, for example ["name", "recentCalls"]. Leave it out to get them all. Returning less keeps the agent focused and its context short.
  • historyCount: how many earlier calls to include in recentCalls, from 0 to 20 (default 5).
  • includeTranscripts: set to false to leave transcriptExcerpt out of recentCalls (default true), for example when past calls may contain details this agent shouldn't see.
  • lookupName: look up the caller's name from carrier caller-ID records right now, even if the number doesn't have caller-name lookup turned on (default false). The carrier charges a small fee for each lookup, which is added to the call's price.

Example​

Tool config
{
  "toolType": "PHONE_GET_CALLER_INFO",
  "fields": ["name", "city", "state", "recentCalls"],
  "historyCount": 3,
  "includeTranscripts": true,
  "lookupName": false
}

Configuration fields

  • Name
    fields
    Type
    array<string> · optional
    Description
    Which details to return, from: phoneNumber, name, city, state, country, forwardedFrom, direction, recentCalls. Optional; by default all of them.
  • Name
    historyCount
    Type
    integer · optional
    Description
    How many earlier calls with this person to include (0 to 20). Optional; defaults to 5.
  • Name
    includeTranscripts
    Type
    boolean · optional
    Description
    Whether each earlier call includes the start of its transcript. Optional; defaults to true.
  • Name
    lookupName
    Type
    boolean · optional
    Description
    Look up the caller's name with their phone carrier right now, when it isn't already known. Each lookup is a paid Twilio caller-name lookup. Optional; defaults to false.

Send SMS TOOLSEND_SMS​

Sends one text message from the phone number in phoneConfigId to toPhoneNumber. Only US recipients are supported; formats like (415) 555-0100 and +14155550100 are both accepted. message is at most 1600 characters — the carrier splits longer texts into segments, and the result reports how many were used. clientDisplayMessage is never sent to the recipient; it's echoed back in the result so the calling app can show it next to the outcome.

Every send is checked before anything goes out:

  • the phone number belongs to your company and is active;
  • your company has finished Text Messaging registration, or the number comes from your own connected Twilio account;
  • the recipient has an approved consent record, or texted your company within the last year;
  • the recipient hasn't opted out by replying STOP.

On success the result is {"success": true, "messageId": ..., "twilioMessageSid": ..., "status": ..., "from": ..., "to": ..., "segments": ...}. The status is the carrier's acceptance (QUEUED, ACCEPTED, SENDING, or SENT); delivery is tracked afterwards and shows in the number's message history.

When a text isn't sent​

A refused or failed text returns {"success": false, "errorCode": ..., "errorMessage": ...}. The errorMessage is written for people and says what to do, so an agent can pass it on as-is.

Error codeWhy
SMS_NOT_REGISTEREDYour company hasn't registered for texting yet.
REGISTRATION_PENDINGThe registration is still in carrier review.
REGISTRATION_ACTION_REQUIREDThe registration was rejected and needs a fix.
REGISTRATION_SUSPENDEDCarriers suspended the registration.
NUMBER_NOT_ATTACHEDTexting isn't set up for this number yet.
CONSENT_REQUIREDThe recipient hasn't consented and hasn't texted you in the last year.
OPTED_OUTThe recipient replied STOP. They're texted again only after they reply START.
INVALID_NUMBERThe recipient isn't a valid US phone number.
NUMBER_INACTIVEThe phone number was released or is no longer active.
PHONE_CONFIG_NOT_FOUNDNo phone number matches phoneConfigId.
ACCESS_DENIEDThe phone number belongs to another company, or you don't have access to it.
BYO_CREDENTIALS_INVALID, BYO_ACCOUNT_SUSPENDED, BYO_ACCOUNT_DISCONNECTEDThe number comes from your own Twilio account, and that account needs attention.
INVALID_CONFIGphoneConfigId, toPhoneNumber, or message is missing.
SEND_FAILEDThe carrier didn't accept the text. Try again later.

Send SMS example​

Tool config
{
  "toolType": "SEND_SMS",
  "phoneConfigId": "V1StGXR8Z5",
  "toPhoneNumber": "@@{TO_PHONE_NUMBER}",
  "message": "Hi @@{CUSTOMER_NAME}, your appointment with Acme is confirmed for tomorrow at 10am. Reply STOP to opt out.",
  "clientDisplayMessage": ""
}

Configuration fields

  • Name
    phoneConfigId
    Type
    string (ID)
    Description
    Which phone number to text from — the only true config-level field (persisted on the tool). References a phone configuration by ID.
  • Name
    toPhoneNumber
    Type
    string
    Description
    Recipient; a US number, normalized to E.164 (+1 and 10 digits) before sending.
  • Name
    message
    Type
    string
    Description
    Message text, at most 1600 characters (Twilio's limit; long texts are split into segments).
  • Name
    clientDisplayMessage
    Type
    string · optional
    Description
    Optional note for the calling app/UI. Never sent to the recipient; echoed back in the tool result (as `clientDisplayMessage`) so a caller can show it next to the send outcome.