🔒 This feature is currently in BETA and available by invite only. Functionality may change as we continue to develop it. If you have questions or feedback, please reach out to our team.
The Directory Tool extends your Voice AI auto attendant with a searchable database of destinations — departments, teams, or individuals — that callers can be routed to by name. When a caller asks to be transferred, the bot queries your directory, checks whether the destination is open, and returns the correct extension to dial.
How It Works
When the Voice Bot performs a lookup, it sends the caller's search phrase to your directory. The tool finds the best matching destination, checks its business hours (including any holiday overrides), and returns one of three outcomes:
- Matched — a destination was found and is currently open. The bot receives the extension details and can transfer the call.
- Outside Hours — a match was found, but that destination is currently closed. The bot receives the destination's opening hours so it can inform the caller.
- No Match — no destination matched the search phrase.
Step 1: Create Business Hours
Business hours define when a destination is available to accept calls. You must create at least one business hour preset before adding destinations.
Navigate to Business Hours in the sidebar and click Create Business Hour.
- Name — a label for this preset, e.g. "Standard Office Hours" or "24/7".
- Description — optional notes about when this preset is used.
- Timezone — select the timezone these hours apply in. All open/closed checks are calculated against this timezone, so make sure it matches the physical location of the destination.
- Shifts per day — for each day of the week, click Add Shift and set a start and end time. A day with no shifts is treated as closed. You can add multiple shifts to a day (e.g. morning and afternoon).
Click Save when done. You can create as many presets as you need — for example, separate presets for different office locations or departments with unusual hours.
Step 2: Create a Directory
A directory is the container that holds all your destinations. You can have multiple directories (e.g. one per site or product line), and each one gets its own unique lookup URL for use with the Voice Bot.
Navigate to Directories in the sidebar and click Create Directory.
- Name — a descriptive name for this directory, e.g. "Main Office".
- Description — optional context about what this directory covers.
Click Save. Your new directory will appear in the list.
Step 3: Add Destinations
Destinations are the individual entries in your directory — the extensions the bot can transfer callers to.
From the Directories list, click into your directory and then click Create Destination.
Required fields:
- Extension — the extension number or SIP address user part (e.g.
1001). For PSTN destinations, enter a valid E.164 number (e.g.+441234567890).
- Business Hour Preset — select the business hours schedule that governs when this destination is available.
- Description — this is the most important field for search accuracy. Write a natural description of who or what this destination reaches — e.g. "Sales Team", "Customer Support", or "Jane Smith". The bot matches the caller's spoken phrase against this description, so the clearer and more specific it is, the better the results.
Advanced fields (expand the Advanced section):
- Extension Prefix — usually
sip. Change tosipsonly if your PBX requires TLS.
- PBX Address — the hostname or IP address of your PBX. Defaults to
__ORIGINATOR__, which routes the call back to whichever PBX the call came from. Use a specific address if you need to direct the call to a different system.
- Inbound Number — if you have multiple destinations with the same name serving different locations, you can scope a destination to a specific inbound DID. When the bot sends the caller's inbound number with the lookup, only destinations matching that number (or those with no inbound number set) will be considered.
- Priority — when multiple destinations match the same search, the one with the lowest priority number is returned first.
- Location — an optional label for the physical location (e.g. "Newport"). Not used in matching, but helpful for your own reference.
Managing Holiday & Override Hours
Business hour overrides let you set custom hours for specific dates — bank holidays, seasonal closures, or special events — without changing your standard schedule.
From Business Hours, open the preset you want to modify and click Overrides (or navigate to the overrides list from the sidebar).
Click Create Business Hour Override and fill in:
- Date — the specific date this override applies to (format: YYYY-MM-DD). Each date can only have one override per preset.
- Description — a label for the override, e.g. "Christmas Day" or "Bank Holiday".
- Shifts — set the opening hours for this date. Add one or more time ranges. To mark the day as fully closed, remove all shifts using the X button (you must have at least one shift listed, so if you want the day closed, set shifts to cover a period that will never be reached, or contact support — this is a known limitation in the current BETA).
💡 Overrides take priority over the standard weekly schedule. On the override date, only the override shifts are used.
Using the Directory Tool with the Voice Bot
Each directory has a unique HTTP tool URL. To find it, open your directory from the Directories list — the tool URL is shown in the directory details.
The URL format is:
POST https://directory.talkative.com/api/v1/directory/{directory-uuid}/extension-lookupRequest Parameters
Parameter | Required | Description |
search | Yes | The search term — typically the department or person name the caller spoke. |
inbound_number | No | The DID the call arrived on. Used to scope results to location-specific destinations. |
Example Request
{
"search": "sales team",
"inbound_number": "+441234567890"
}Response: Successful Match
When a matching destination is found and currently open:
{
"description": "Sales Team",
"extension": "1001",
"dialable": "sip:1001@192.168.1.1",
"timezone": "Europe/London",
"current_time": "Thu Jun 11 2026 10:30:00 GMT+0100",
"line_business_hours": [
{ "start_time": "09:00", "end_time": "17:30" }
],
"override": null
}The dialable field is the full SIP address to transfer the caller to, formatted as {prefix}:{extension}@{pbx}. Pass this directly to your transfer action in the Voice Bot.
If a holiday override is active, the override object will contain the override date and description.
Response: Outside Hours
When a match is found but the destination is currently closed:
{
"message": "There are no matching destinations which are currently open and accepting calls. We've included a list of the closed extensions and their business hours for reference.",
"closed_extensions": [
{
"description": "Sales Team",
"business_hours": [
{ "start_time": "09:00", "end_time": "17:30" }
],
"timezone": "Europe/London",
"current_time": "Thu Jun 11 2026 20:00:00 GMT+0100",
"override": null
}
]
}Use the closed_extensions data to tell the caller when the team will next be available.
Response: No Match
When no destination matches the search phrase:
{
"message": "We could not find an extension which matches your search, please try again."
}Reviewing Logs
Every lookup the bot makes is recorded. Navigate to Logs in the sidebar to view the full history.
Each log entry shows:
- Date — when the lookup occurred.
- Directory — which directory was queried.
- Search Term — the phrase the bot sent.
- Inbound Number — the caller's inbound DID, if provided.
- Result — one of three outcomes:
- 🟢 Matched — a destination was found and open.
- 🟡 Outside Hours — a destination matched but was closed.
- ⚫ No Match — nothing matched the search term.
- Matched Extension — the extension that was returned, if any.
You can filter logs by result type using the status dropdown, and search by the original search term using the search box. Logs are paginated, showing the 50 most recent entries per page.
Reviewing logs regularly is a good way to identify gaps in your directory — repeated "No Match" results may indicate destinations that need better descriptions, or new entries that need to be added.
Dashboard & Statistics
The Dashboard gives a high-level view of how the Directory Tool is performing over the last 30 days.
Summary cards:
- Total Lookups — all lookup requests made across your directories.
- Successful — lookups that returned a matched, open destination.
- Outside Hours — lookups where a destination was found but closed.
- No Match — lookups where no destination matched.
- Success Rate — the percentage of lookups that resulted in a successful match.
Most Requested Extensions — the top 10 destinations by successful lookup count. Useful for understanding which departments receive the most transfer requests.
Departments Requested Outside Hours — the top 10 destinations that were closed when callers tried to reach them. If the same department appears frequently here, it may be worth reviewing its business hours or adding out-of-hours cover.
Lookup Distribution by Hour — a bar chart showing when lookups occur across the day (UTC). Helps identify peak call times.
Daily Lookup Trend — a 14-day view of total lookup volume per day, giving a quick sense of call traffic patterns.