Leilani Documentation Open app
Reference Using Functions in Leilani

Using Functions in Leilani

functions.md

Functions let your Leilani agent take action during a call. Instead of only answering questions, your agent can send a request to an external service, send a message, or transfer the caller to another destination.

Common use cases include checking order status, looking up directory information, sending a follow-up email or text message, transferring a caller, or starting a downstream workflow.

How Functions work

Each Function includes:

  • a Name
  • Instructions that tell Leilani when to use it
  • a destination, such as an API endpoint, email address, SMS number, or transfer target
  • optional Properties that define the structured inputs Leilani should collect before calling the Function

When a caller requests something related to a Function, Leilani can:

  1. ask follow-up questions to collect required inputs
  2. call the Function
  3. use the result to continue the conversation, or transfer the caller if the Function uses tel

For tel Functions, Leilani does not collect Properties. The transfer target is defined directly in the URI.

You can also assign a DTMF sequence so callers can trigger a Function by pressing keys on their phone.

Create a Function

In the Leilani console, open your agent and select Functions.

Configure the following fields for each Function.

Name

Use a short, descriptive name that reflects the Function’s purpose.

Examples:

  • lookup_order
  • create_callback
  • send_intake_email

Use a consistent naming convention, such as lowercase with underscores. Each Function name must be unique within an agent.

DTMF sequence

This field is optional.

If you assign a DTMF sequence, callers can trigger the Function by entering digits on their keypad. Leilani then collects any required details before calling the Function.

Each DTMF sequence must be unique within the agent.

Instructions

Instructions tell Leilani when to use the Function.

Effective Instructions explain:

  • when the Function applies
  • what information Leilani should collect first
  • what outcome the Function supports

Example:

Use this Function when the caller wants to check an order status. Ask for the order number before calling the Function.

Scheme, operation, and URI

These fields define where the Function sends its request or transfer.

  • Scheme identifies the destination type, such as HTTPS, email, SMS, or telephone transfer.
  • Operation is the HTTP method. It applies only to HTTP and HTTPS Functions.
  • URI is the destination value entered without the scheme, because the scheme is selected separately in the UI.

For HTTP and HTTPS Functions, enter only the portion after the scheme.

Example:

  • full URL: https://example.com
  • scheme: https
  • URI: //example.com

Additional examples:

  • HTTP or HTTPS: //api.example.com/orders/status
  • mailto: ops@example.com
  • sms: +15551234567
  • tel: +15551234567
  • tel with local number and phone-context: 101;phone-context=pbx.example.com

Supported HTTP methods:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Headers

Headers are optional and are typically used with HTTP and HTTPS Functions.

Common examples include authorization headers, environment identifiers, and custom routing headers required by your service.

Headers do not apply to mailto, sms, or tel Functions.

Properties

Properties define the structured inputs Leilani can collect and send to a Function.

For HTTP and HTTPS Functions, each Property includes:

  • a name
  • a data type
  • whether it is required
  • a short description

Supported property types:

  • String
  • Number
  • Integer
  • Boolean

Create a Property for each value the Function requires.

Examples:

  • order_id
  • email
  • appointment_date
  • phone_number

Some Function types use a fixed set of supported Properties:

  • mailto requires subject and body
  • mailto optionally supports cc and bcc
  • sms requires body
  • tel does not use Properties

No other Properties are used for mailto, sms, or tel Functions.

Supported Function types

Leilani supports the following Function types:

  • HTTP and HTTPS
  • email using mailto
  • SMS using sms
  • telephone transfer using tel

HTTP and HTTPS

Use HTTP and HTTPS Functions for APIs, webhooks, and internal services.

General guidance:

  • use GET for lookups
  • use POST, PUT, or PATCH when sending structured data
  • return concise responses that Leilani can summarize clearly in conversation

Whenever possible, use compact JSON with clear field names.

Email

Use mailto when the Function should send an email.

Common use cases include sending a message to a shared inbox, delivering an intake summary, or notifying staff about a caller request.

For mailto Functions:

  • subject is required
  • body is required
  • cc is optional
  • bcc is optional

No other Properties are used.

In the UI, set the Scheme to mailto and enter only the email portion in the URI field. You can also include cc and bcc as URI query parameters to provide default values.

Examples:

  • scheme: mailto

  • URI: ops@example.com

  • scheme: mailto

  • URI: john.doe@example.com?bcc=jane.doe@example.com

  • scheme: mailto

  • URI: john.doe@example.com?cc=sales@example.com&bcc=jane.doe@example.com

When cc or bcc values are included in the URI, they act as defaults for that Function.

SMS

Use sms when the Function should send a text message.

Common use cases include follow-up confirmations, links or instructions after a call, and short status updates.

For sms Functions:

  • body is required

No other Properties are used.

In the UI, set the Scheme to sms and enter only the destination number in the URI field.

Example:

  • scheme: sms
  • URI: +15551234567

Telephone transfer

Use tel when the Function should transfer the active call to another destination.

Common use cases include sending the caller to a sales or support line, transferring to a specific team member or queue, or handing off to an external phone number.

When Leilani calls a tel Function:

  • the active call is transferred to the destination defined in the URI
  • no headers are sent
  • no Properties are collected or sent
  • the destination is fixed for that Function

Create a separate tel Function for each transfer destination you want Leilani to use.

For tel Functions, the URI can contain either:

  • a global E.164 number
  • a local number, such as an extension, with phone-context

Examples:

  • scheme: tel

  • URI: +15551234567

  • scheme: tel

  • URI: 101;phone-context=pbx.example.com

Requirements:

  • E.164 global numbers must start with + and use digits only after the +
  • local numbers, including extensions, must include phone-context

Best practices

Well-designed Functions are specific, easy to trigger correctly, and limited to a single clear outcome.

Recommended practices:

  • define one clear outcome per Function
  • write Instructions that clearly describe when the Function should be used
  • keep Property names short and easy to understand
  • mark only truly necessary Properties as required
  • keep responses brief enough for a voice conversation
  • split multi-step workflows into multiple Functions
  • for transfers, create one tel Function per destination and make the handoff condition explicit in the Instructions

Before you publish

Before enabling a Function in production, confirm that:

  • the Function name is clear
  • the Instructions describe exactly when Leilani should use it
  • the required Properties match the selected Scheme
  • the destination service or transfer target is valid and reachable
  • the response is short enough for Leilani to summarize clearly
  • tel Functions use either an E.164 global number or a local number with phone-context
  • the URI is entered without a scheme, because the Scheme is selected separately in the UI

Start with a small, well-defined Function. It is easier to test, validate, and refine over time.