diff --git a/fern/assistants/assistant-hooks.mdx b/fern/assistants/assistant-hooks.mdx index 2a50c513..b7940ef9 100644 --- a/fern/assistants/assistant-hooks.mdx +++ b/fern/assistants/assistant-hooks.mdx @@ -5,14 +5,14 @@ slug: assistants/assistant-hooks # Assistant Hooks -Assistant hooks allow you to configure actions that will be performed when specific events occur during a call. Currently, hooks support the `call.ending` event, which triggers when a call is ending. +Assistant hooks allow you to configure actions that will be performed when specific events occur during a call. Currently, hooks support the `call.ending` event (which is triggered when a call is ending), `assistant.speech.interrupted` (when the assistant's speech is interrupted), and `customer.speech.interrupted` (when the customer's speech is interrupted) ## Usage Hooks are defined in the `hooks` array of an assistant. Each hook consists of: -- `on`: The event that triggers the hook (currently only supports `call.ending`) -- `do`: The actions to perform when the hook triggers (currently only supports `transfer`) +- `on`: The event that triggers the hook (supports `call.ending`, `assistant.speech.interrupted`, and `customer.speech.interrupted`) +- `do`: The actions to perform when the hook triggers (supports `transfer`, `function`, and `say`) - `filters`: Optional conditions that must be met for the hook to trigger The `call.endedReason` field in filters can be set to any of the [call ended reasons](https://docs.vapi.ai/api-reference/calls/get#response.body.endedReason). The transfer destination type follows the same schema as the [transfer call tool destinations](https://docs.vapi.ai/api-reference/tools/create#request.body.transferCall.destinations). @@ -72,7 +72,98 @@ curl -X PATCH "https://api.vapi.ai/assistant/" \ }' ``` +## Example: Combined Actions on Pipeline Error + +This example demonstrates how to combine multiple actions (say, function, and transfer) when a pipeline error occurs. The hook will first say a message, then call a function, and finally transfer the call: + +```bash +curl -X PATCH "https://api.vapi.ai/assistant/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "call.ending", + "filters": [{ + "type": "oneOf", + "key": "call.endedReason", + "oneOf": ["pipeline-error"] + }], + "do": [ + { + "type": "say", + "exact": "I apologize for the technical difficulty. Let me transfer you to our support team." + }, + { + "type": "function", + "function": { + "name": "log_error", + "parameters": { + "type": "object", + "properties": { + "error_type": { + "type": "string", + "value": "pipeline_error" + } + } + }, + "description": "Logs the error details for monitoring" + }, + "async": true, + "server": { + "url": "https://your-server.com/api" + } + }, + { + "type": "transfer", + "destination": { + "type": "number", + "number": "+1234567890", + "callerId": "+1987654321" + } + } + ] + }] +}' +``` + +## Example: Handling Speech Interruptions + +This example demonstrates how to handle when the assistant's speech is interrupted by the customer. The hook will respond with a polite acknowledgment: + +```bash +curl -X PATCH "https://api.vapi.ai/assistant/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "assistant.speech.interrupted", + "do": [{ + "type": "say", + "exact": ["Sorry about that", "Go ahead", "Please continue"] + }] + }] +}' +``` + +You can also handle customer speech interruptions in a similar way: + +```bash +curl -X PATCH "https://api.vapi.ai/assistant/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "customer.speech.interrupted", + "do": [{ + "type": "say", + "exact": "I apologize for interrupting. Please continue." + }] + }] +}' +``` + Common use cases for hooks include: - Transferring to a human agent on errors - Routing to a fallback system if the assistant fails -- Ensuring calls are handled gracefully in edge cases \ No newline at end of file +- Ensuring calls are handled gracefully in edge cases +- Handling customer/assistant interruptions \ No newline at end of file diff --git a/fern/docs.yml b/fern/docs.yml index cfa92da5..affeb78c 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -199,6 +199,8 @@ navigation: path: advanced/sip/sip-zadarma.mdx - page: Plivo path: advanced/sip/sip-plivo.mdx + - page: Phone Number Hooks + path: phone-numbers/phone-number-hooks.mdx - section: Tools path: tools/introduction.mdx diff --git a/fern/phone-numbers/phone-number-hooks.mdx b/fern/phone-numbers/phone-number-hooks.mdx new file mode 100644 index 00000000..ced84a57 --- /dev/null +++ b/fern/phone-numbers/phone-number-hooks.mdx @@ -0,0 +1,80 @@ +--- +title: Phone Number Hooks +slug: phone-numbers/phone-number-hooks +--- + +# Phone Number Hooks + +Phone number hooks allow you to configure actions that will be performed when specific events occur during a call. Currently, hooks support the `call.ringing` event (which is triggered when a call is ringing). + +## Usage + +Hooks are defined in the `hooks` array of a phone number. Each hook consists of: + +- `on`: The event that triggers the hook (supports `call.ringing`) +- `do`: The actions to perform when the hook triggers (supports `transfer` and `say`) + +## Example: Say Message on Call Ringing + +This example shows how to play a message when a call is ringing: + +```bash +curl -X PATCH "https://api.vapi.ai/phone-number/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "call.ringing", + "do": [{ + "type": "say", + "exact": "inbound calling is disabled." + }] + }] +}' +``` + +## Example: Transfer on Call Ringing + +This example shows how to transfer a call when it starts ringing: + +```bash +curl -X PATCH "https://api.vapi.ai/phone-number/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "call.ringing", + "do": [{ + "type": "transfer", + "destination": { + "type": "number", + "number": "+1234567890", + "callerId": "+1987654321" + } + }] + }] +}' +``` + +You can also transfer to a SIP destination: + +```bash +curl -X PATCH "https://api.vapi.ai/phone-number/" \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{ + "hooks": [{ + "on": "call.ringing", + "do": [{ + "type": "transfer", + "destination": { + "type": "sip", + "sipUri": "sip:user@domain.com" + } + }] + }] +}' +``` + +Common use cases for phone number hooks include: +- Disabling inbound calling by playing a message or transferring \ No newline at end of file