Documentation | Guava

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.

index.html

Copy

<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:

index.html

Copy

<!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.

PythonTypeScript

generate_code.py

Copy

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	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 and ship your first voice agent in an afternoon.