Skip to main content

​
Platform-Specific Functions

Based supports different deployment platforms (chat, voice, email, SMS) and provides specialized functions for each platform. These functions allow you to take advantage of platform-specific capabilities.

​
Voice Deployment Functions

When your Based agent is deployed for voice conversations, you can use these special functions to control call flow:

​
transfer(phone_number, options?)

Transfers the current call to another phone number. Optionally supports dialing extensions after the call connects. Syntax: 
transfer(phone_number)
transfer(phone_number, extension)
transfer(phone_number, options)
Parameters:
  • phone_number (string): The destination phone number to transfer to (E.164 format recommended, e.g. +15551234567). When using sipDomain, this is treated as a SIP username (e.g. "frontdesk") routed through your Twilio SIP Domain.
  • extension (string, optional): Simple extension digits to dial after the call connects
  • options (dict, optional): Advanced transfer options with the following keys:
    • extension (string): Extension digits to route the call after it connects. In PSTN mode, sent as DTMF tones. In SIP mode, passed as a SIP header to the PBX.
    • pauseSeconds (number): Seconds to wait before sending digits (default: 1 second)
    • sipDomain (string): A Twilio SIP Domain (e.g. yourcompany.sip.twilio.com). When set, phone_number is treated as a SIP username (e.g. "frontdesk") and the call is routed via SIP instead of the PSTN.
    • message (string): A message to say to the caller before transferring. Works for all transfer types; when using sipDomain, prefer this over a standalone say() to ensure the message is delivered before the SIP leg is initiated.
Examples: 
# Basic transfer - transfer to customer support
if user_request["needs_human_support"]:
    say("I'll transfer you to our customer support team right away.", exact=True)
    transfer("+1-800-123-4567")

# Transfer with extension (simple string format)
# Waits 1 second (default), then dials extension 123
say("Let me transfer you to Julie in the Finance department.", exact=True)
transfer("5302321272", "271")

# Transfer with extension and custom pause time (dict format)
# Waits 2 seconds before dialing the extension (useful for slower phone systems)
say("Connecting you to the service department now.", exact=True)
transfer("5303195426", {"extension": "221", "pauseSeconds": 2})

# Transfer with no pause (immediate extension dialing)
transfer("5302323297", {"extension": "123", "pauseSeconds": 0})

# Transfer via SIP domain to a PBX extension
# Routes through your Twilio SIP Domain instead of the PSTN
transfer("101", {"sipDomain": "yourcompany.sip.twilio.com"})

# Transfer via SIP with a message to the caller first
# Use the `message` option to speak before transferring (preferred over a standalone say())
transfer("305", {"sipDomain": "yourcompany.sip.twilio.com", "message": "Please hold while I connect you."})

# Transfer via SIP domain with extension dialing after connect
transfer("frontdesk", {"sipDomain": "yourcompany.sip.twilio.com", "extension": "4673", "pauseSeconds": 2})
When transferring to extensions, the pauseSeconds parameter controls how long to wait after the call connects before dialing the extension digits. The default of 1 second works for most phone systems, but you may need to increase this for systems that have longer greeting messages or slower IVR responses.
When using sipDomain, the phone_number argument is treated as a SIP username (alphanumeric, e.g. "frontdesk") and the call is routed via sip:<username>@<domain> instead of over the PSTN. When extension is provided, it is included as a SIP header so the PBX can route the call to the correct internal extension; pauseSeconds controls the delay before the header is sent. Use message to speak to the caller before the transfer is initiated.

​
end_call()

Ends the current call immediately. Use this to gracefully terminate a voice conversation after completing the interaction. Syntax: 
end_call()
Examples: 
# End call after completing a transaction
say("Thank you for your order! Your confirmation number is ABC123. Have a great day!", exact=True)
end_call()

# End call when user requests to hang up
if user_request["wants_to_end_call"]:
    say("Thank you for calling. Goodbye!", exact=True)
    end_call()

# End call after transferring to voicemail or completing a task
say("I've sent the information to your email. Is there anything else I can help with?", exact=True)
loop:
    response = talk("", False)  # Wait for user response
until "User confirms they're done":
    done = response.ask(
        question="Is the user indicating they're done and want to end the call?",
        example={"is_done": true}
    )
    if done["is_done"]:
        say("Great, have a wonderful day!", exact=True)
        end_call()

​
click_ivr(digits)

Sends DTMF tones (keypad presses) during an active call. This is useful for navigating IVR (Interactive Voice Response) menus programmatically, such as pressing “1” for sales or entering an account number. Syntax: 
click_ivr(digits)
Parameters:
  • digits (string): The DTMF digits to send. Can include numbers 0-9, *, and #
Examples: 
# Navigate an IVR menu by pressing "1" for English
say("Let me select English for you.", exact=True)
click_ivr("1")

# Enter a multi-digit selection (e.g., "Press 2 for billing, then 3 for payment")
click_ivr("23")

# Enter an account number
account_number = "123456789"
say("I'm entering your account number now.", exact=True)
click_ivr(account_number)

# Navigate through a phone tree: press 1, then *, then 0 for operator
click_ivr("1*0")
The click_ivr function sends DTMF tones immediately. If you need to wait for an IVR prompt before sending tones, use a say statement or add appropriate delays in your flow logic.