webrtc widgets.md

WebRTC Widget

Embed a Guava voice agent on your website so visitors can start a voice conversation directly from the browser. The WebRTC audio widget is a drop-in <script> tag that handles all WebRTC signaling, UI, and state management — no additional CSS, JS, or dependencies required.

Integration

Add a single <script> tag to your page. The only required attribute is data-webrtc-code, which is the agent code (starts with grtc-) obtained from the Guava dashboard.

<CodeBlock filename="index.html" language="html" code={`<script src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js" data-webrtc-code="grtc-YOUR_AGENT_CODE_HERE"

`} />

Complete standalone page

If you don't have a page yet, here's a full HTML file you can use as a starting point:

<CodeBlock filename="index.html" code={`

My Voice Agent `} />

Script tag attributes

<PropTable rows={[{ name: "src", type: "URL", desc: "URL to the hosted widget JS file." }, { name: "data-webrtc-code", type: "string", desc: "The WebRTC agent code (e.g. grtc-nB9oE4...). Obtained from the Guava dashboard." },]} />

Widget states

State Behavior User action
idle Ready to call — green indicator Click to call
connecting Pulsing animation, clicks disabled Wait
active Call in progress — audio-reactive visuals Click to hang up
error Red indicator — connection failed Click to retry
No configuration needed. The widget is entirely self-contained — it injects its own HTML and CSS (scoped under `[data-guava-widget]` so it won't conflict with your page styles), wrapped in an IIFE with no global variables. Works on any page with a modern browser.

Generating a WebRTC code via SDK

Instead of obtaining a WebRTC code from the Guava dashboard, you can generate one programmatically with client.create_webrtc_agent(). This is useful when you need to create codes on-the-fly or control their TTL.

<CodeTabs python={{ code: from guava import Client\nfrom datetime import timedelta\n\nclient = Client(api_key="your-api-key")\n\n# Create a WebRTC code valid for 1 hour\nwebrtc_code = client.create_webrtc_agent(ttl=timedelta(hours=1))\nprint(f"WebRTC code: {webrtc_code}")\n\n# Use the code to listen for inbound calls\nclient.listen_inbound(webrtc_code=webrtc_code, controller_class=MyCallController), filename: "generate_code.py" }} typescript={{ code: import * as guava from "@guava-ai/guava-sdk";\n\nconst client = new guava.Client({ apiKey: "your-api-key" });\n\n// Create a WebRTC code valid for 1 hour (3600 seconds)\nconst webrtcCode = await client.createWebrtcAgent({ ttlSec: 3600 });\nconsole.log(\WebRTC code: \${webrtcCode}`);\n\n// Use the code to listen for inbound calls\nclient.listenInbound(\n { webrtc_code: webrtcCode },\n (logger) => new MyCallController(logger),\n);`, filename: "generate_code.ts" }} />

Parameter Type Required Description
ttl datetime.timedelta | None No How long the WebRTC code should remain valid. If omitted, the server default TTL applies.

Returns: str — a WebRTC code (e.g. grtc-...) that can be passed to listen_inbound(webrtc_code=...) or used as a ?webrtc_code=<value> query parameter in the browser widget.

Raises an HTTP error (via check_response) if the API request fails.