# White-Label Voice for SaaS Products

Ship voice as a feature in your SaaS product. Per-customer persona, per-customer phone number, per-customer billing — Guava is invisible to the end user.

### Why this matters

Embed Guava in your AI stack. Your prompts, your data, our voice infrastructure. Sub-1s latency. WebRTC + SIP. Compliance you can hand to your enterprise buyer. This example shows you how to automate white-label voice for saas products calls end-to-end with Guava's SDK — no telephony plumbing, no prompt engineering, just Python.

## Installation

Install from Guava's private PyPI index. A public package is coming soon — the install command will simplify to `pip install guava`.

```terminal
# Step 1: Install Guava
pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com

# Public PyPI package coming soon — the install command will simplify to:
# pip install guava

# Step 2: Set your credentials
export GUAVA_API_KEY="..."
export GUAVA_AGENT_NUMBER="..."
```

## How it's built

Every Guava agent is a Python class. Walk through the key sections below, then grab the complete file at the end.

### Imports

Import the Guava SDK and any helpers you need. `guava.CallController` is the base class for every voice agent.

```example.py
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os
```

### Agent setup

`set_persona()` defines how the agent presents itself. `set_task()` gives it its mission in plain English. The checklist drives the conversation — Guava works through it top-to-bottom, collecting `Field` values and speaking `Say` items as it goes.

```example.py
class WhiteLabelAgent(guava.CallController):
    def __init__(self, customer_org: str, customer_voice: str, app_callback_url: str):
        super().__init__()
        self.app_callback_url = app_callback_url
        self.set_persona(
            organization_name=customer_org,
            agent_name="Sage",
            voice=customer_voice,
        )
        self.set_task(
            objective=f"Handle voice interactions on behalf of {customer_org}",
            checklist=[
                f"Greet the caller as a {customer_org} agent.",
                guava.Field(
                    key="caller_name",
                    field_type="text",
                    description="Caller's first name",
                ),
                guava.Field(
                    key="request",
                    field_type="text",
                    description="What the caller wants to accomplish",
                ),
                "Confirm what you've captured and let them know what happens next.",
            ],
            on_complete=self.notify_app,
        )

def notify_app(self, fields):
        """Post the structured call summary back to the SaaS customer's webhook."""
        import requests
        requests.post(
            self.app_callback_url,
            json={"call_summary": fields, "call_id": self.call_id},
            headers={"X-Guava-Signature": guava.sign(fields)},
            timeout=5,
        )

# A SaaS product spins up Guava for each customer on signup
def onboard_customer(org_name: str, voice_choice: str, webhook_url: str):
    guava.listen(
        controller=WhiteLabelAgent,
        controller_args={
            "customer_org": org_name,
            "customer_voice": voice_choice,
            "app_callback_url": webhook_url,
        },
        agent_number=guava.provision_number(area_code="415"),
        api_key=os.environ["GUAVA_API_KEY"],
    )

onboard_customer(
    org_name="Lakeside Veterinary Clinic",
    voice_choice="warm-female-en-us",
    webhook_url="https://app.your-saas.com/webhooks/lakeside/voice",
)
```

## Full example

The complete file — copy it, save it as `example.py`, and run it.

```example.py
# Install: pip install gridspace-guava --extra-index-url https://guava-pypi.gridspace.com
import guava
import os

class WhiteLabelAgent(guava.CallController):
    def __init__(self, customer_org: str, customer_voice: str, app_callback_url: str):
        super().__init__()
        self.app_callback_url = app_callback_url
        self.set_persona(
            organization_name=customer_org,
            agent_name="Sage",
            voice=customer_voice,
        )
        self.set_task(
            objective=f"Handle voice interactions on behalf of {customer_org}",
            checklist=[
                f"Greet the caller as a {customer_org} agent.",
                guava.Field(
                    key="caller_name",
                    field_type="text",
                    description="Caller's first name",
                ),
                guava.Field(
                    key="request",
                    field_type="text",
                    description="What the caller wants to accomplish",
                ),
                "Confirm what you've captured and let them know what happens next.",
            ],
            on_complete=self.notify_app,
        )

## Run it

Start the agent. It will connect to Guava's infrastructure and begin accepting calls on your assigned number.

```terminal
python example.py
```