Assistant hooks
Automate actions on call events and interruptions
Assistant hooks let you automate actions when specific events occur during a call. Use hooks to transfer calls, run functions, or send messages in response to events like call ending or speech interruptions.
Supported events include:
call.ending: When a call is endingcall.timeElapsed: When a specified number of seconds has elapsed from call startassistant.speech.interrupted: When the assistant’s speech is interruptedcustomer.speech.interrupted: When the customer’s speech is interruptedcustomer.speech.timeout: When the customer doesn’t speak within a specified timeassistant.transcriber.endpointedSpeechLowConfidence: When a final transcript has low confidence (below threshold but within configurable range)You can combine actions and add filters to control when hooks trigger. Multiple customer.speech.timeout hooks can be attached to an assistant with staggered trigger delay to support different actions at different timing in the conversation.
Hooks are defined in the hooks array of your assistant configuration. Each hook includes:
on: The event that triggers the hookdo: The actions to perform (supports tool and say)filters: (Optional) Conditions that must be met for the hook to triggeroptions: (Optional) Configuration options for certain hook types like call.timeElapsed, customer.speech.timeout, and assistant.transcriber.endpointedSpeechLowConfidencename: (Optional) Custom name to identify the hookAction Types:
say: Speak a message. Use exact for predetermined text or prompt for AI-generated responsestool: Execute a tool like transferCall, function, endCall, etc.The call.endedReason filter can be set to any of the call ended reasons.
The transfer destination type follows the transfer call tool destinations schema.
Transfer a call to a fallback number if a pipeline error occurs:
You can also transfer to a SIP destination:
Perform multiple actions—say a message, call a function, and transfer the call—when a pipeline error occurs:
Use "oneOf": ["pipeline-error"] as a catch-all filter for any pipeline-related error reason.
Respond when the assistant’s speech is interrupted by the customer:
Handle customer speech interruptions in a similar way:
Respond when the customer doesn’t speak within a specified time:
The customer.speech.timeout hook supports special options:
timeoutSeconds: How long to wait for customer speech (1-1000 seconds, default: 7.5)triggerMaxCount: Maximum times the hook triggers per call (1-10, default: 3)triggerResetMode: Whether to reset the trigger count when user speaks (default: “never”)The call.timeElapsed hook fires once when a specified number of seconds has elapsed from call start. Use it to enforce call duration limits, prompt wrap-up behavior, or trigger time-based actions.
Each call.timeElapsed hook fires once at the specified time. To trigger actions at multiple time points, add separate hooks with different seconds values.
Speak a message 5 minutes into the call:
Combine multiple call.timeElapsed hooks with maxDurationSeconds to enforce structured call discipline. This example begins wrapping up at 8 minutes, warns at 9 minutes, and hard-cuts at 10 minutes:
The call.timeElapsed hook supports one option:
seconds: Number of seconds from call start when the hook should trigger (1-3600)The hook fires once at the specified time. maxDurationSeconds (default: 600 seconds) acts as a hard cutoff that ends the call immediately. Use call.timeElapsed hooks before that limit to allow for a graceful close.
Instead of speaking a fixed message, you can inject a system message into the conversation to change the LLM’s behavior for the remainder of the call:
When a transcriber produces a final transcript with low confidence (below the set confidence threshold or default of 0.4), it’s normally discarded. The assistant.transcriber.endpointedSpeechLowConfidence hook allows you to handle these borderline cases by triggering actions like asking the user to repeat or logging the event.
This hook only triggers for final/endpointed transcripts that fall within a configurable confidence range. Transcripts with confidence at or above the threshold are processed normally, while those below the minimum range are still discarded.
Ask the user to repeat when a transcript has low confidence:
Configure a specific confidence range for when the hook should trigger:
You can use shorthand syntax similar to customer.speech.timeout hooks. The shorthand format is [confidence=min:max] where both min and max are optional:
Set both min and max:
Set only minimum (max defaults to transcriber’s confidence threshold):
Set only maximum (min defaults to max - 0.2):
When no options are specified, the hook uses these defaults:
confidenceMax: Uses the transcriber’s confidenceThreshold (typically 0.4)confidenceMin: confidenceMax - 0.2 (minimum 0)For example, if your transcriber has a confidenceThreshold of 0.4:
You can configure multiple hooks to handle different confidence ranges with different actions:
The assistant.transcriber.endpointedSpeechLowConfidence hook supports these options:
confidenceMin: Minimum confidence threshold (0-1, default: confidenceMax - 0.2)confidenceMax: Maximum confidence threshold (0-1, default: transcriber’s confidenceThreshold)This hook is supported for transcribers that have confidenceThreshold configuration: Deepgram, Gladia, and AssemblyAI.
Assistant checks with the user at the 10 and 20s mark from when the user is silent, and ends the call after 30s of silence.
You can set up automatic Slack notifications when calls fail by combining assistant hooks with Slack webhooks. This is useful for monitoring call quality and getting immediate alerts when issues occur.
Follow the Slack webhook documentation to create an incoming webhook:
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX)Set up a serverless function (using a service like val.town) to convert Vapi tool call requests into Slack messages:
Add this hook configuration to your assistant to trigger Slack notifications on call failures:
Replace <your-slack-webhook-url> with your actual Slack webhook URL and <your-serverless-function-url> with your serverless function endpoint.