Leilani Documentation Open app
Reference Directory

Directory

directory.md

Leilani's Directory gives an agent a structured list of people, departments, queues, IVRs, and outside destinations it can route callers to.

At a high level, the Directory does two things:

  • gives Leilani names it can search during a call
  • maps those names to transfer destinations and fallback message behavior

Directory works best when your Instructions tell Leilani when it should search the directory, when it should confirm the destination with the caller, and when it should transfer immediately versus screen the handoff.

How directory behaves

In practice:

  • Leilani searches the directory by display_name
  • search returns the closest matching entries, rather than requiring an exact name match
  • each entry maps a caller-friendly name to a username, transfer_mode, and optional mailbox
  • manual edits, CSV uploads, and external sync treat the directory as a full list, not a patch
  • if an entry is omitted from the latest upload or sync payload, it is removed

This makes the Directory useful both for:

  • smaller hand-managed routing lists
  • larger synced directories managed by a PBX, HRIS, CRM, or internal directory source

Directory entry fields

Each entry has four fields.

Display Name

Display Name is the human-readable name Leilani uses when searching and reasoning about the directory.

This is the value that should match how callers naturally ask for a destination, such as:

  • Sales
  • Billing
  • John Doe
  • Customer Success
  • After Hours Support

Display names should be unique within an agent's directory. In practice, display_name is the identity of the entry.

Display name best practices

  • use names callers would actually say out loud
  • keep names distinct from one another
  • avoid internal-only abbreviations unless callers use them
  • prefer Support over SUP_Q_01

Username

Username is the actual transfer target Leilani uses when it sends the call.

Depending on your SIP environment, this may be:

  • an extension such as 100
  • a SIP username
  • a queue or IVR destination
  • an outside number

Leilani passes this value as the transfer destination, so it should match whatever your PBX, SBC, or SIP platform expects.

Examples:

  • 100
  • support-queue
  • 18005551212
  • +14155552671

Username best practices

  • use values that already work in your SIP environment
  • test new destinations after saving the directory
  • use stable targets for departments and queues rather than personal extensions when possible
  • use role-based entries like On-Call Engineer when the destination changes over time

Transfer Mode

Transfer Mode controls how Leilani handles the handoff once it has identified the right directory entry.

Available modes are:

  • Cold
  • Warm
  • Auto

Cold

Cold transfer sends the caller directly to the destination once Leilani has confirmed the handoff should happen.

Use Cold when:

  • the destination expects direct transfers
  • no screening or summary is needed
  • speed matters more than context handoff

Warm

Warm transfer adds an introduction and screening step before the caller is connected.

When an entry is set to Warm, Leilani:

  1. puts the caller on hold
  2. places a separate call to the transfer destination
  3. summarizes the original call and speaks with the recipient
  4. decides the next step based on that person's response

From there:

  • if the recipient accepts the handoff, Leilani transfers the caller to them
  • if the recipient does not want to take the call, is unavailable, or asks not to be connected, Leilani returns to the caller and asks them to leave a message
  • that message is delivered using the entry's mailbox setting

Use Warm when:

  • the destination needs context before taking the call
  • the recipient should be able to accept or decline the transfer
  • you want missed handoffs to fall back to structured message capture

Auto

Auto lets Leilani choose the most appropriate handoff behavior for the situation.

In Auto mode, Leilani can decide whether to:

  • transfer directly
  • perform a warm handoff first

If Leilani decides a warm handoff is appropriate, it uses the same flow as Warm:

  • caller is placed on hold
  • Leilani calls the destination
  • Leilani summarizes the call and speaks with the recipient
  • the caller is either connected or asked to leave a message based on the recipient's response

Use Auto when:

  • some calls should go through immediately, but others should be screened
  • the right behavior depends on urgency, caller intent, or the conversation context
  • you want Leilani to make a situational routing decision instead of enforcing one transfer style every time

Transfer mode best practices

  • use Cold for queues, IVRs, and destinations that always want direct transfer
  • use Warm for executives, clinicians, sales teams, or high-context handoffs
  • use Auto when the same destination sometimes needs screening and sometimes does not
  • configure a mailbox for any Warm or Auto entry where fallback message capture matters

Mailbox

Mailbox is an optional per-entry destination for follow-up messages.

Mailbox must be one of:

  • a valid email address
  • a valid E.164 phone number such as +14155552671

Mailbox is most useful for Warm and Auto entries.

If a warm-style handoff does not complete, Leilani can ask the caller to leave a message and deliver it based on the mailbox type:

  • if mailbox is an email address, Leilani emails the message
  • if mailbox is an E.164 phone number, Leilani sends the message by text

If mailbox is empty, that entry does not have a per-destination message delivery target.

Mailbox best practices

  • use email for shared team inboxes and monitored role accounts
  • use SMS mailboxes for individuals or mobile-first operational teams
  • populate mailbox for high-value warm handoffs so missed transfers do not become dead ends
  • use shared addresses or shared numbers when multiple people need visibility

Managing the directory

Leilani supports three ways to manage directory data:

  • manual editing in the console
  • CSV upload
  • external sync URL

Manual editing

Manual editing is best for smaller routing lists or agents with highly custom callflows.

Use manual management when:

  • the list is short
  • entries change infrequently
  • the directory is specific to one agent or workflow

Manual edits are appropriate for:

  • named departments
  • escalation paths
  • front desk options
  • curated VIP or executive routing lists

CSV upload

CSV upload is a fast way to create or replace a directory in bulk.

The required columns are:

  • display_name
  • username

Optional columns are:

  • transfer_mode
  • mailbox

Example:

display_name,username,transfer_mode,mailbox
John Doe,100,Cold,john.doe@example.com
Support Queue,300,Warm,
Jane Doe,9999999999,Auto,+14155552671

CSV upload should be treated as a source-of-truth update. Entries missing from the uploaded file are removed from the saved directory.

CSV best practices

  • keep display_name unique
  • clean up spelling and naming before upload
  • validate mailbox values before import
  • use CSV when the directory changes in batches rather than one entry at a time

Sync URL

Sync URL lets Leilani pull directory data from an external system.

Current sync behavior expects:

  • an http or https URL
  • a GET request
  • a 200 OK response
  • a JSON array of directory entries

Each object in the response must include:

  • display_name
  • username

It may also include:

  • transfer_mode
  • mailbox

Example payload:

[
  {
    "display_name": "Sales",
    "username": "200",
    "transfer_mode": "Cold"
  },
  {
    "display_name": "John Doe",
    "username": "4512",
    "transfer_mode": "Warm",
    "mailbox": "john.doe@example.com"
  },
  {
    "display_name": "After Hours Support",
    "username": "+14155552671",
    "transfer_mode": "Auto",
    "mailbox": "+14155550199"
  }
]

If credentials are included in the sync URL, Leilani uses them for HTTP Basic authentication.

Sync is one-way and destructive:

  • synced entries overwrite matching manual entries
  • entries not present in the latest sync payload are removed

You can:

  • trigger sync manually from the console
  • let Leilani re-sync automatically every 15 minutes when a sync URL is configured

Sync best practices

  • use sync when another system already owns the directory
  • make the sync payload complete, not partial
  • keep naming stable so callers hear consistent destination names
  • test sync output in a non-production agent before pointing production traffic at it

How customers can leverage the directory

Common patterns include:

  • routing callers to named departments like Billing, Sales, or Scheduling
  • transferring to specific staff by name
  • routing to queues, IVRs, or on-call roles
  • screening high-value handoffs with Warm transfers
  • letting Leilani decide between direct and screened transfer with Auto
  • collecting fallback messages when a screened handoff is not accepted

This is especially useful for organizations that want to:

  • modernize front desk and receptionist workflows
  • reduce operator burden
  • preserve human handoff quality for important calls
  • keep routing logic modular instead of hardcoding it in the PBX alone

Directory best practices

  • treat display_name as the caller-facing routing vocabulary
  • make entries easy to pronounce and easy to disambiguate
  • keep username aligned with real, tested SIP destinations
  • use Warm or Auto where context-setting matters
  • configure mailbox anywhere a missed transfer should produce a follow-up
  • tell Leilani in Instructions when to search the directory, when to confirm a match, and when to transfer

Final guidance

The Directory is not just a contact list. It is a routing layer.

Used well, it gives Leilani enough structure to:

  • understand who the caller is asking for
  • transfer intelligently
  • screen important handoffs
  • capture the next best action when a live transfer does not happen