Skip to content

Commit 255306e

Browse files
AdiSaiAdiSai
authored
update assistant hooks and phone number hooks (#367)
1 parent 05961a2 commit 255306e

File tree

3 files changed

+177
-4
lines changed

3 files changed

+177
-4
lines changed

‎fern/assistants/assistant-hooks.mdx‎

Lines changed: 95 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@ slug: assistants/assistant-hooks
55

66
# Assistant Hooks
77

8-
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.
8+
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)
99

1010
## Usage
1111

1212
Hooks are defined in the `hooks` array of an assistant. Each hook consists of:
1313

14-
- `on`: The event that triggers the hook (currently only supports `call.ending`)
15-
- `do`: The actions to perform when the hook triggers (currently only supports `transfer`)
14+
- `on`: The event that triggers the hook (supports `call.ending`, `assistant.speech.interrupted`, and `customer.speech.interrupted`)
15+
- `do`: The actions to perform when the hook triggers (supports `transfer`, `function`, and `say`)
1616
- `filters`: Optional conditions that must be met for the hook to trigger
1717

1818
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/<id>" \
7272
}'
7373
```
7474

75+
## Example: Combined Actions on Pipeline Error
76+
77+
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:
78+
79+
```bash
80+
curl -X PATCH "https://api.vapi.ai/assistant/<id>" \
81+
-H "Authorization: Bearer <auth>" \
82+
-H "Content-Type: application/json" \
83+
-d '{
84+
"hooks": [{
85+
"on": "call.ending",
86+
"filters": [{
87+
"type": "oneOf",
88+
"key": "call.endedReason",
89+
"oneOf": ["pipeline-error"]
90+
}],
91+
"do": [
92+
{
93+
"type": "say",
94+
"exact": "I apologize for the technical difficulty. Let me transfer you to our support team."
95+
},
96+
{
97+
"type": "function",
98+
"function": {
99+
"name": "log_error",
100+
"parameters": {
101+
"type": "object",
102+
"properties": {
103+
"error_type": {
104+
"type": "string",
105+
"value": "pipeline_error"
106+
}
107+
}
108+
},
109+
"description": "Logs the error details for monitoring"
110+
},
111+
"async": true,
112+
"server": {
113+
"url": "https://your-server.com/api"
114+
}
115+
},
116+
{
117+
"type": "transfer",
118+
"destination": {
119+
"type": "number",
120+
"number": "+1234567890",
121+
"callerId": "+1987654321"
122+
}
123+
}
124+
]
125+
}]
126+
}'
127+
```
128+
129+
## Example: Handling Speech Interruptions
130+
131+
This example demonstrates how to handle when the assistant's speech is interrupted by the customer. The hook will respond with a polite acknowledgment:
132+
133+
```bash
134+
curl -X PATCH "https://api.vapi.ai/assistant/<id>" \
135+
-H "Authorization: Bearer <auth>" \
136+
-H "Content-Type: application/json" \
137+
-d '{
138+
"hooks": [{
139+
"on": "assistant.speech.interrupted",
140+
"do": [{
141+
"type": "say",
142+
"exact": ["Sorry about that", "Go ahead", "Please continue"]
143+
}]
144+
}]
145+
}'
146+
```
147+
148+
You can also handle customer speech interruptions in a similar way:
149+
150+
```bash
151+
curl -X PATCH "https://api.vapi.ai/assistant/<id>" \
152+
-H "Authorization: Bearer <auth>" \
153+
-H "Content-Type: application/json" \
154+
-d '{
155+
"hooks": [{
156+
"on": "customer.speech.interrupted",
157+
"do": [{
158+
"type": "say",
159+
"exact": "I apologize for interrupting. Please continue."
160+
}]
161+
}]
162+
}'
163+
```
164+
75165
Common use cases for hooks include:
76166
- Transferring to a human agent on errors
77167
- Routing to a fallback system if the assistant fails
78-
- Ensuring calls are handled gracefully in edge cases
168+
- Ensuring calls are handled gracefully in edge cases
169+
- Handling customer/assistant interruptions

‎fern/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,8 @@ navigation:
199199
path: advanced/sip/sip-zadarma.mdx
200200
- page: Plivo
201201
path: advanced/sip/sip-plivo.mdx
202+
- page: Phone Number Hooks
203+
path: phone-numbers/phone-number-hooks.mdx
202204

203205
- section: Tools
204206
path: tools/introduction.mdx

‎fern/phone-numbers/phone-number-hooks.mdx‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
title: Phone Number Hooks
3+
slug: phone-numbers/phone-number-hooks
4+
---
5+
6+
# Phone Number Hooks
7+
8+
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).
9+
10+
## Usage
11+
12+
Hooks are defined in the `hooks` array of a phone number. Each hook consists of:
13+
14+
- `on`: The event that triggers the hook (supports `call.ringing`)
15+
- `do`: The actions to perform when the hook triggers (supports `transfer` and `say`)
16+
17+
## Example: Say Message on Call Ringing
18+
19+
This example shows how to play a message when a call is ringing:
20+
21+
```bash
22+
curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
23+
-H "Authorization: Bearer <auth>" \
24+
-H "Content-Type: application/json" \
25+
-d '{
26+
"hooks": [{
27+
"on": "call.ringing",
28+
"do": [{
29+
"type": "say",
30+
"exact": "inbound calling is disabled."
31+
}]
32+
}]
33+
}'
34+
```
35+
36+
## Example: Transfer on Call Ringing
37+
38+
This example shows how to transfer a call when it starts ringing:
39+
40+
```bash
41+
curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
42+
-H "Authorization: Bearer <auth>" \
43+
-H "Content-Type: application/json" \
44+
-d '{
45+
"hooks": [{
46+
"on": "call.ringing",
47+
"do": [{
48+
"type": "transfer",
49+
"destination": {
50+
"type": "number",
51+
"number": "+1234567890",
52+
"callerId": "+1987654321"
53+
}
54+
}]
55+
}]
56+
}'
57+
```
58+
59+
You can also transfer to a SIP destination:
60+
61+
```bash
62+
curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
63+
-H "Authorization: Bearer <auth>" \
64+
-H "Content-Type: application/json" \
65+
-d '{
66+
"hooks": [{
67+
"on": "call.ringing",
68+
"do": [{
69+
"type": "transfer",
70+
"destination": {
71+
"type": "sip",
72+
"sipUri": "sip:[email protected]"
73+
}
74+
}]
75+
}]
76+
}'
77+
```
78+
79+
Common use cases for phone number hooks include:
80+
- Disabling inbound calling by playing a message or transferring

0 commit comments

Comments
 (0)