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.
<script
src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js"
data-webrtc-code="grtc-YOUR_AGENT_CODE_HERE"
></script>Complete standalone page
If you don't have a page yet, here's a full HTML file you can use as a starting point:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>My Voice Agent</title>
</head>
<body>
<script
src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js"
data-webrtc-code="grtc-YOUR_AGENT_CODE_HERE"
></script>
</body>
</html>Script tag attributes
| Parameter | Type | Default | Description |
|---|---|---|---|
| src | URL | — | URL to the hosted widget JS file. |
| data-webrtc-code | string | — | 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.
from guava import Client
from datetime import timedelta
client = Client(api_key="your-api-key")
# Create a WebRTC code valid for 1 hour
webrtc_code = client.create_webrtc_agent(ttl=timedelta(hours=1))
print(f"WebRTC code: {webrtc_code}")
# Use the code to listen for inbound calls
client.listen_inbound(webrtc_code=webrtc_code, controller_class=MyCallController)| 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.
Ready to build?
Get started with Guava
Sign up, grab your API key, and ship your first voice agent in an afternoon.
Open Guava DashboardQuestions? hi@goguava.ai
<script
src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js"
data-webrtc-code="grtc-YOUR_AGENT_CODE_HERE"
></script><!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>My Voice Agent</title>
</head>
<body>
<script
src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget-audio-orb.js"
data-webrtc-code="grtc-YOUR_AGENT_CODE_HERE"
></script>
</body>
</html>from guava import Client
from datetime import timedelta
client = Client(api_key="your-api-key")
# Create a WebRTC code valid for 1 hour
webrtc_code = client.create_webrtc_agent(ttl=timedelta(hours=1))
print(f"WebRTC code: {webrtc_code}")
# Use the code to listen for inbound calls
client.listen_inbound(webrtc_code=webrtc_code, controller_class=MyCallController)