Can you provide a good example / code of a client tool with the embedded chatbot widget | ElevenLabs | Page 1

rigid groveBOT Sep 26, 2025, 10:29 PM

#

AI-generated Answer for renegonzaleztorres

Yes. Here’s the minimal, documented pattern: embed the widget and register a client tool that the agent can call.

Example (index.html)

Put this in your site’s <body>. Replace YOUR_AGENT_ID with your agent ID.
Create a client tool in the agent dashboard named redirectToExternalURL (case‑sensitive). Then the script below wires it up.

<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<title>ElevenLabs widget + client tool</title>
</head>
<body>
<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const widget = document.querySelector('elevenlabs-convai');

    if (widget) {
      // Register client-side tools when the widget initializes a call
      widget.addEventListener('elevenlabs-convai:call', (event) => {
        event.detail.config.clientTools = {
          // Must match the tool name you configured on the agent (case-sensitive)
          redirectToExternalURL: ({ url }) => {
            window.open(url, '_blank', 'noopener,noreferrer');
          },
        };
      });
    }
  });
</script>

</body>
</html>

Notes

Widgets currently require a public agent with authentication disabled; enable domain allowlisting for security. (elevenlabs.io)
The embed tag and loader script are the supported way to add the widget. (elevenlabs.io)
Client tool names and parameters are case‑sensitive and must match what you configured in the agent dashboard. (elevenlabs.io)

Sources:

Widget customization (embed, attributes, and client-tool example). (elevenlabs.io)
Client tools guide (how client tools work and naming requirements). (elevenlabs.io)

trim niche Sep 26, 2025, 10:36 PM

#

Is the SDK required for the client tool?

rigid groveBOT Sep 26, 2025, 10:36 PM

#

AI-generated Answer for renegonzaleztorres

Short answer: No.

With the embedded chatbot widget, you can register and handle client tools directly in the browser by listening for the widget’s call event and assigning functions to event.detail.config.clientTools—no SDK required. (elevenlabs.io)

SDKs are optional alternatives if you’re building outside the widget or in frameworks (e.g., React, JS, Python, Swift), where you register client tools in code via the respective SDKs. (elevenlabs.io)

Sources:
Widget customization | ElevenLabs Documentation
Client tools | ElevenLabs Documentation

trim niche Sep 26, 2025, 10:39 PM

#

Provide an example of listening for a tool that has no parameters. Let’s say the tool is called “helloTool”

rigid groveBOT Sep 26, 2025, 10:39 PM

#

AI-generated Answer for renegonzaleztorres

Here’s a minimal, docs-aligned example for a client tool named helloTool with no parameters, using the embedded widget. Create a Client tool called helloTool in your agent (no parameters), then register it at runtime via the widget’s call event:

widget.addEventListener('elevenlabs-convai:call', (event) => {
// Map client tool names to handlers (names are case-sensitive)
event.detail.config.clientTools = {
helloTool: () => {
// Your client-side action
console.log('Hello from helloTool');

    // If the tool is configured to "Wait for response", return data to the agent:
    // return { message: 'hello' };
  },
};

});
});
</script>

Notes:

The widget exposes the elevenlabs-convai:call event; attach clientTools on event.detail.config as shown in the official example.
Client tool names are case-sensitive and must match the tool name you configured in the dashboard. If you enable “Wait for response,” your function’s return value is appended to the conversation context.

If you prefer SDKs, the “Client tools” guide also shows zero-argument tools (e.g., getCustomerDetails) returning data to the agent, which is the same concept applied above for the widget.

trim niche Sep 26, 2025, 10:43 PM

#

Provide a system prompt that instructs the agent to call helloTool

rigid groveBOT Sep 26, 2025, 10:43 PM

#

AI-generated Answer for renegonzaleztorres

System prompt (Tools section)

You have access to a client tool named helloTool (case-sensitive). It takes no parameters.
When the user explicitly asks you to run it (e.g., “call helloTool”, “run the hello tool”), immediately call helloTool with an empty parameters object ({}), then continue the conversation.

Rationale and guidance for including tool-usage instructions in the system prompt are provided in:

Client tools (case sensitivity and prompting tips). (elevenlabs.io)
Prompting guide (include a Tools section with usage guidelines). (elevenlabs.io)

Sources:
Client tools | ElevenLabs Documentation
ElevenLabs Agents prompting guide | ElevenLabs Documentation

trim niche Sep 27, 2025, 12:31 PM

#

Provide the text to add to the “description” field in the dashboard when adding a client tool

rigid groveBOT Sep 27, 2025, 12:31 PM

#

AI-generated Answer for renegonzaleztorres

"Use this client-side tool to log a message to the user’s client." (elevenlabs.io)

Sources:
Client tools | ElevenLabs Documentation

trim niche Sep 27, 2025, 12:42 PM

#

Can you confirm the embed code for the chat widget aligned with the code you provided for the client side tool

rigid groveBOT Sep 27, 2025, 12:42 PM

#

AI-generated Answer for renegonzaleztorres

Yes. The officially supported embed for the web chat/widget is:

<elevenlabs-convai agent-id="YOUR_AGENT_ID"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

Place this in your site’s body. This is the same widget element your client-side tool code will attach to. Widgets currently require the agent to be public with authentication disabled; use your agent’s allowlist to restrict domains. (elevenlabs.io)

To wire client-side tools to the widget, listen for the widget call event and assign your clientTools on event.detail.config, for example:

document.addEventListener('DOMContentLoaded', () => {
const widget = document.querySelector('elevenlabs-convai');
if (!widget) return;

widget.addEventListener('elevenlabs-convai:call', (event) => {
event.detail.config.clientTools = {
// Example from docs:
redirectToExternalURL: ({ url }) => window.open(url, '_blank', 'noopener,noreferrer'),
};
});
});

This is the documented pattern for aligning the embed with client tools registered on the client. (elevenlabs.io)

If you want the widget to behave as a text-only chat (no audio), enable Chat Mode in the dashboard; the embed code stays the same. (elevenlabs.io)

Sources:
Widget customization | ElevenLabs Documentation
Widget customization | ElevenLabs Documentation
Widget customization | ElevenLabs Documentation

trim niche Sep 27, 2025, 12:49 PM

#

I get an error: Client tool with the name helloTool is not defined on client

rigid groveBOT Sep 27, 2025, 12:49 PM

#

AI-generated Answer for renegonzaleztorres

That error means the agent tried to invoke a client tool that isn’t registered in your client runtime, or its name doesn’t exactly match the tool defined in the dashboard. Client tools must be registered on the client and names are case‑sensitive. (elevenlabs.io)

Fix checklist:

In the dashboard, ensure the tool exists and Tool Type = Client, and the Name is exactly helloTool (case‑sensitive). (elevenlabs.io)
Register the tool in your client code:
- React SDK: initialize with clientTools containing a helloTool function, for example: clientTools: { helloTool: () => 'ok' }. Tool names in this object must match the dashboard. Also consider using onUnhandledClientToolCall to log unexpected tool calls. (elevenlabs.io)
- Web widget: add an event listener for "elevenlabs-convai:call" and assign event.detail.config.clientTools = { helloTool: () => 'ok' } before the call proceeds. The widget example notes the tool name is case‑sensitive. (elevenlabs.io)
If you want the agent to wait for a return value from helloTool, enable “Wait for response” in the tool’s config; otherwise the agent won’t block on the result. (elevenlabs.io)

If you’ve done the above and still see the error, verify at runtime which tool name is being requested (e.g., via onUnhandledClientToolCall in React or by logging inside your widget event handler) to catch any name mismatches. (elevenlabs.io)

trim niche Sep 27, 2025, 12:53 PM

#

Do I need the SDK for this to work?

rigid groveBOT Sep 27, 2025, 12:53 PM

#

AI-generated Answer for renegonzaleztorres

Short answer: No.

The chat widget can be embedded with a simple HTML + script snippet; no SDK installation is required. (elevenlabs.io)
If you want client tools in the widget, you can register them in plain JavaScript by listening for the elevenlabs-convai:call event and setting event.detail.config.clientTools—again, no SDK needed. (elevenlabs.io)
SDKs (React/JS/Python/Swift) are optional for type-safe overrides and deeper control; the widget can be customized via UI or SDKs. (elevenlabs.io)

For platform-specific embeds (e.g., Webflow/Wix), the docs also show the same no-SDK embed approach. (elevenlabs.io)

Sources:
Widget customization | ElevenLabs Documentation
Widget customization | ElevenLabs Documentation
Widget customization | ElevenLabs Documentation
Conversational AI in Webflow | ElevenLabs Documentation

trim niche Sep 27, 2025, 1:06 PM

#

Ok it worked, next let’s enhance it to pass the parameter message to helloTool, message will contain the agent’s response

#Can you provide a good example / code of a client tool with the embedded chatbot widget