Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions fern/tools/client-side-websdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Use the Web SDK to handle tool-calls entirely on the client. This lets your assi
**In this guide, you'll learn to:**
- Define a client-side tool with the Web SDK
- Receive and handle `tool-calls` events on the client
- Inject extra context during a call with `addMessage`
- Inject extra context during a call with an `add-message` message

<Warning>
Client-side tools cannot send a tool "result" back to the model. If the model must use the output of a tool to continue reasoning, implement a server-based tool instead. See: <a href="https://docs.vapi.ai/tools/custom-tools" target="_blank">Server-based Function tools</a>.
Expand All @@ -32,7 +32,7 @@ npm install @vapi-ai/web

2. Start a call with your tool defined in the <code>model.tools</code> array and subscribe to <code>clientMessages: ['tool-calls']</code>.
3. Listen for <code>message.type === 'tool-calls'</code> and perform the desired UI update. No response is sent back to the model.
4. (Optional) Inject context mid-call using <code>vapi.addMessage(...)</code>.
4. (Optional) Inject context mid-call using `vapi.send({ type: 'add-message', ... })`.

## Complete example (React + Web SDK)

Expand Down Expand Up @@ -264,19 +264,25 @@ export default App;

## Inject data during the call

Use <code>addMessage</code> to provide extra context mid-call. This does not return results for a tool; it adds messages the model can see.
Send an <code>add-message</code> message with <code>vapi.send</code> to provide extra context mid-call. This does not return results for a tool; it adds messages the model can see. By default <code>triggerResponseEnabled</code> is set to <code>true</code> and the assistant should respond to the new message right away.

```ts
// Inject system-level context
vapi.addMessage({
role: 'system',
content: 'Context: userId=123, plan=premium, theme=dark',
vapi.send({
type: 'add-message',
message: {
role: 'system',
content: 'Context: userId=123, plan=premium, theme=dark',
},
});

// Inject a user message
vapi.addMessage({
role: 'user',
content: 'FYI: I switched to the settings tab.',
vapi.send({
type: 'add-message',
message: {
role: 'user',
content: 'FYI: I switched to the settings tab.',
},
});
```

Expand All @@ -289,7 +295,7 @@ If you need the model to <b>consume tool outputs</b> (e.g., fetch data and conti
- **Client-only execution**: Omit the server URL to run tools on the client.
- **One-way side effects**: Client tools do not send results back to the model.
- **Subscribe to events**: Use <code>clientMessages: ['tool-calls']</code> and handle <code>message.type === 'tool-calls'</code>.
- **Add context**: Use <code>vapi.addMessage</code> to inject data mid-call.
- **Add context**: Use <code>vapi.send</code> with an <code>add-message</code> message to inject data mid-call.

## Next steps

Expand Down
Loading