Duty Schedule — Voice Agent Tools

This reference covers the three duty schedule tools available to voice agents. All tools are enabled per campaign in the campaign's Tools tab and are available for both voice and other agent modalities (allowedModalities: ['all']).

duty-check

Look up who is currently on duty. Use this when you need to tell the caller who to expect a call from, or to decide whether to escalate.

When to use

Caller asks "who is on call right now?"
Agent needs to personalize the call (e.g. "I'll connect you with Jane who's on duty today")
Agent needs to decide whether to escalate based on whether anyone is available

Parameters

None required. The tool takes no input.

{}

Response

{
  "success": true,
  "onDuty": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+15551234567"
    }
  ],
  "schedules": [ /* full schedule objects */ ],
  "primary": { /* first/highest-priority schedule object */ },
  "usingDefault": false
}

Field	Description
`onDuty`	Array of all currently on-duty personnel. May contain multiple people if schedules overlap. Ordered by priority (lowest number first).
`primary`	The highest-priority schedule record. Use this when you only need one contact.
`usingDefault`	`true` if no one is scheduled and the response is falling back to the configured default contact.
`onDuty[]` (when `usingDefault: true`)	Contains the default contact's name, email, and phone from settings.

Empty case: When no one is on duty and no default is configured, onDuty is an empty array. Handle this gracefully — tell the caller no one is available and offer to leave a message or try again later.

Example LLM prompt guidance

When the caller asks who is on call, use duty-check to get the current on-duty person.
If onDuty is empty, tell the caller no one is currently available and offer to take a message.
If usingDefault is true, let the caller know they'll be reached by the backup contact.

duty-notify

Send an urgent notification to the person currently on duty. This is fire-and-forget — the agent does not track whether the notification was acknowledged.

When to use

Caller needs to reach on-call staff but confirmation is not required
Simpler workflows where tracking delivery is sufficient
When confirmation is disabled in Duty Schedule settings

Parameters

Parameter	Type	Required	Description
`subject`	string	Yes	Short subject line for the notification (used as email subject)
`message`	string	Yes	Full notification body. Be clear and concise.
`priority`	string	No	`low`, `normal`, `high`, or `urgent`. Defaults to `normal`.

{
  "subject": "Urgent: HVAC system alarm at Building A",
  "message": "The caller reports that the HVAC system in Building A is showing a fault alarm and the temperature is rising. Please investigate immediately.",
  "priority": "high"
}

Response

{
  "success": true,
  "message": "Notification sent to 2 on-duty personnel",
  "notifications": [
    {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "method": "email",
      "sent": true
    }
  ]
}

Note: The notification is sent via email and SMS (if the on-duty person has a phone number). The agent should tell the caller the notification has been sent and that someone will follow up, without making promises about response time.

duty-notify-confirm

Send a notification and require the on-duty person to confirm via SMS before the request is considered handled. The system escalates automatically to the next available person if no confirmation is received within the configured timeout.

This is an asynchronous background process. The agent fires the notification and immediately continues or ends the call. Confirmation tracking, escalation, and fail behavior all happen in the background via the tick processor.

When to use

Situations that require a guaranteed response (e.g. emergency maintenance, critical system failures)
When your organization needs an audit trail of who acknowledged an alert
When you have multiple on-call staff and want the system to escalate automatically

Parameters

Parameter	Type	Required	Description
`subject`	string	Yes	Short subject line (used in the SMS and email)
`message`	string	Yes	Full description of what needs attention
`priority`	string	No	`low`, `normal`, `high`, or `urgent`. Defaults to `normal`.
`specialty`	string	No	Requested skill/role (e.g. `"HVAC"`, `"Electrical"`, `"Network Security"`). When provided and the selection rule is `specialty_then_priority`, personnel with this specialty are contacted first.

{
  "subject": "Urgent: Boiler failure at Main Campus",
  "message": "A caller reports a complete boiler failure at the main campus. No heat in the building. Needs immediate attention.",
  "priority": "urgent",
  "specialty": "HVAC"
}

Response

{
  "success": true,
  "notificationId": "64f3a2b1c9e0d1234567890a",
  "status": "pending_confirmation",
  "notifiedPerson": "Mike Torres",
  "message": "Duty notification sent to Mike Torres. Awaiting confirmation."
}

Field	Description
`notificationId`	ID of the created DutyNotification record. Visible in the Notifications tab.
`status`	`pending_confirmation` (normal start), `failed` (no one on duty — fail behavior already applied)
`notifiedPerson`	Name of the first person contacted
`message`	Human-readable summary of what happened

What the agent should say to the caller:

"I've sent an urgent notification to our on-call technician. They'll receive an SMS shortly and are expected to respond within [timeout] minutes. If they're unavailable, our system will automatically reach the next available person."

Do not promise that someone has already responded. Do not say you will monitor progress. The confirmation happens entirely in the background after the call.

Confirmation SMS flow

The on-duty person receives an SMS formatted as:

[DUTY ALERT - URGENT]
Subject: Boiler failure at Main Campus
A caller reports a complete boiler failure at the main campus...
Reply YES to confirm you're handling this, or NO to pass.

The system accepts natural confirmation language: YES, Y, CONFIRM, OK, ON IT, ACK, and variants are treated as confirmed. NO, N, PASS, DECLINE are treated as declined. Ambiguous replies are evaluated by the AI to determine intent.

Escalation behavior

When someone declines or doesn't reply within the timeout:

Their attempt is recorded with outcome timed_out or declined
The next person in the queue receives the same SMS
This continues until someone confirms or the queue is exhausted
Queue ordering follows the configured selection rule:
- priority — all on-duty personnel sorted by priority (lowest number first)
- specialty_then_priority — personnel matching the requested specialty are placed first, then everyone else by priority

Fail behavior

When the queue is exhausted without a confirmation, the configured fail behavior runs:

Setting	What happens
`log_only`	The notification is marked `resolved` with `failBehaviorTriggered: true`. No further action.
`notify_default`	The default contact from settings receives an escalation SMS
`notify_fallback`	A custom fallback contact receives an escalation SMS

Configuration Required for duty-notify-confirm

Before using duty-notify-confirm, configure the following in Duty Schedule → Settings (Confirmation Settings card):

Setting	Description
Enable confirmation	Must be turned on for the confirmation flow to run
Twilio From Number	The phone number confirmation SMS are sent from. Staff replies to this number are intercepted and routed to the confirmation handler automatically.
Timeout (minutes)	How long each person has to reply before escalation. Default: 20 minutes.
Selection rule	How to order the queue when multiple people are on duty
Fail behavior	What happens when no one confirms

Enabling Tools on a Campaign

Go to your campaign in Voice Agents → (select campaign) → Tools tab
Enable the duty tools you want the agent to use:
- duty-check — query who is on duty
- duty-notify — send a basic notification
- duty-notify-confirm — send with confirmation tracking
Save the campaign

The agent will have access to the enabled tools on every call for that campaign.

Notification Log

All duty-notify-confirm dispatches are logged in Duty Schedule → Notifications. Each record shows:

When the notification was created
Subject, message, priority, and requested specialty
Current status (pending, confirmed, escalating, failed, resolved)
Who confirmed (if anyone)
How many attempts were made vs. how many people were in the queue

Prompt Engineering Tips

Deciding between duty-notify and duty-notify-confirm

Use duty-notify for standard alerts where you just need to reach someone.
Use duty-notify-confirm when the situation is critical and you need to guarantee a response is tracked.

Passing specialty context

The agent should extract the relevant skill from the caller's description and pass it as the specialty parameter. For example:

"The HVAC unit is down" → specialty: "HVAC"
"We have a network outage" → specialty: "Network Security" or "IT Support"
"There's an electrical fault" → specialty: "Electrical"

The specialty name should match one of the names configured in Duty Schedule → Specialties. Partial matches are not supported — the name must match exactly (case-insensitive).

Checking before notifying

For critical situations, consider calling duty-check first to confirm someone is actually available before using duty-notify-confirm. If onDuty is empty, you can tell the caller upfront that no one is scheduled and the notification will go to the default contact instead of creating a false expectation.