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