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 webrtc-code, which is the agent code (starts with grtc-) obtained from the Guava dashboard.

index.html

<script
    src="https://app.goguava.ai/static/build/webrtc-widgets/guava-widget.js"
    webrtc-code="grtc-YOUR_AGENT_CODE_HERE"
  ></script>

Self-contained. The widget injects its own HTML and CSS with no global variables or style conflicts. Works on any page with a modern browser — just add the script tag and configure with attributes.

Customization

Attribute	Type	Default	Description
`gw-name`	string	`"Guava"`	Display name shown on the widget.
`gw-color`	string	`"#4ecb8d"`	Accent color as a 6-digit hex code (e.g. `"#4ecb8d"` or `"4ecb8d"`).
`enable-chat`	flag	off	Add this attribute to enable the chat panel with message transcript, text input, and mic toggle.

Try it

Configure the widget and copy the script tag for your site.

Chat panel

The chat panel adds a full conversation interface when the user clicks the orb:

Live message transcript (agent and caller speech)
Text input for sending messages during the call
Mic toggle to mute/unmute
Call timer and hang-up button
Draggable header to reposition the panel
Post-call “New conversation” button to start another session

Generating a WebRTC code via SDK

Python
TypeScript

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.

generate_code.py

from datetime import timedelta
import guava

client = guava.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
agent = guava.Agent(name="Hannah", purpose="You are a helpful voice agent.")
agent.listen_webrtc(webrtc_code)

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 agent.listen_webrtc() or used as the widget’s webrtc-code attribute.Raises an HTTP error if the API request fails.

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

generate_code.ts

import * as guava from "@guava-ai/guava-sdk";

const client = new guava.Client({ apiKey: "your-api-key" });

// Create a WebRTC code valid for 1 hour (3600 seconds)
const webrtcCode = await client.createWebrtcAgent(3600);
console.log(`WebRTC code: ${webrtcCode}`);

// Use the code to listen for inbound calls
const agent = new guava.Agent({ name: "Hannah", purpose: "You are a helpful voice agent." });
agent.listenWebrtc(webrtcCode);

Parameter	Type	Required	Description
`ttlSec`	`number`	No	How long the WebRTC code should remain valid, in seconds. If omitted, the server default TTL applies.

Returns: Promise<string> — a WebRTC code (e.g. grtc-...) that can be passed to agent.listenWebrtc() or used as the widget’s webrtc-code attribute.Throws an error if the API request fails.

Getting started

Agent SDK

CLI reference

WebRTC

SIP calling

Phone numbers

Deployments

Compliance

Release notes

Integration

Customization

Try it

Chat panel

Generating a WebRTC code via SDK

​Integration

​Customization

​Try it

​Chat panel

​Generating a WebRTC code via SDK

Integration

Customization

Try it

Chat panel

Generating a WebRTC code via SDK