PATH (e.g. ~/.local/bin/).on_question callback receives a plain string and expects a plain string back — you can plug in any knowledge base, vector store, or model you prefer.
on_call_received, Guava accepts all calls by default. Implement it only when you need to screen callers or look up information based off the incoming phone number.
Field objects (typed, named values the agent extracts) with plain strings (freeform instructions the agent follows). Fields are retrievable later via get_field().
guava.Say step is spoken verbatim — use it sparingly when exact wording matters.
send_sms.
TypeError.
on_question or on_task_complete. It is most useful for implementing call surveillance or real-time transcription logging.
on_question or on_task_complete. It is most useful for implementing call surveillance or real-time transcription logging.
reach_person() and set_voicemail_action() both handle voicemail and cannot be used together. If you set voicemail_message or voicemail_hangup on reach_person(), do not call set_voicemail_action() — and vice versa. Using both raises an error.
set_voicemail_action() and reach_person() both handle voicemail and cannot be used together. If you are using reach_person(), set voicemail behavior there via its voicemail_message or voicemail_hangup parameters instead. Using both raises an error.
hangup or message — passing both or neither raises an error.
| 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 |
Base44 for building your web app
an AI coding platform with terminal access (such as Claude Code or Cursor) for setting up and managing your Guava agent. (The AI coding platform will handle all command-line steps that would otherwise require you to use the terminal.)
Already have a deployed agent and a grtc- code?
Skip to the Quick Start.
New to Guava?
Start with the Full Guide.
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
1. In your Guava account, go to the API Keys page.
2. Click + Create API Key at the top right.
3. Name your key something related to your app or voice widget.
{'__main__.py'} or main.py) that defines your agent's behavior and goals. You don't need to know Python: once you have the project folder, you can use your preferred AI coding platform to make changes in plain language.
my-agent with starter code that defines a basic voice agent. This starter agent can hold a spoken conversation, but it hasn't been given a specific task, role, or use case. You'll customize that in Step 7.
my-agent. Feel free to rename it to something more personalized, for example: first-webapp-concierge. You'll develop and customize your agent soon. For now, proceed to Step 5.
examples → healthcare → appointment_scheduling). Identify the example agent you'd like to use.
examples/healthcare/appointment_scheduling/) to a location where you keep your projects. Feel free to rename it to something more personalized, for example: first-webapp-concierge. This copy is your working agent project, the one you'll customize, test, and deploy through the rest of this guide.
grtc-YOUR_CODE_HERE with the code you created in Step 5:
guava deploy down ./my-agent. You can redeploy at any time with guava deploy up ./my-agent. Replace my-agent with your project folder name if you renamed it.
grtc-YOUR_CODE_HERE with the WebRTC code you created in Step 5:
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
Troubleshooting
**I don't see the voice orb.**
index.html and confirm the script tag appears just before </body>. Also check that the grtc- code in the script tag matches the code you created in Step 5.
Lovable for building your web app
an AI coding platform with terminal access (such as Claude Code or Cursor) for setting up and managing your Guava agent. (The AI coding platform will handle all command-line steps that would otherwise require you to use the terminal.)
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
grtc-YOUR_CODE_HERE with the WebRTC code you created in Step 5:
grtc-YOUR_CODE_HERE with your actual WebRTC code before pasting:
Troubleshooting
**I don't see the voice orb.**
index.html and confirm the script tag appears just before </body>. Also check that the grtc- code in the script tag matches the code you created in Step 5.
agent.call_local() to place a test call using your local audio device, or agent.chat() to interact with your agent via text in the terminal.pytest or Python's built-in unittest module. This lets you test your Agent end-to-end alongside your Expert's code, using patterns you're already familiar with.agent.callLocal() to place a test call using your local audio device, or agent.chat() to interact with your agent via text in the terminal.on_action_request or on_question. You can do so by constructing a guava.testing.MockCall object and passing it in directly to the handler.onActionRequest or onQuestion. You can do so by constructing a MockCall object and passing it in directly to the handler via agent.handlers.agent.roleplay(prompt="...") runs your agent against a separate LLM that improvises a conversation based on a prompt. The session runs to completion and returns a TestSession object you can assert against. As in a real call, your registered handlers will be invoked by the Agent.session.evaluate function that evaluates the conversation against a rubric.agent.roleplay(prompt) runs your agent against a separate LLM that improvises a conversation based on a prompt. The session runs to completion and returns a TestSession object you can assert against. As in a real call, your registered handlers will be invoked by the Agent.session.evaluate() function that evaluates the conversation against a rubric.agent.callPhone("+1...")} /> to place singular outbound calls, we recommend using Campaigns when calling multiple contacts.
Campaigns automatically manage missed-call retries, enforce calling windows, and control call concurrency.
Since they are persistent resources, you should create one Campaign for each distinct use case and continue adding contacts to it as needed.
While Campaigns are responsible for dispatching calls - you will still need to "attach" an Agent to handle the call itself - this is done using a unique "code" created for each Campaign.
## Before you start
You'll need:
- **A Guava account** — sign up at [app.goguava.ai](https://app.goguava.ai)
- **A phone number** — from the [Phone Numbers](https://app.goguava.ai/dashboard/phone-numbers) page
- **Outbound permission** — outbound dialing requires approval. Fill out the **Outbound Dialing Permissions Request** form on the [Compliance](https://app.goguava.ai/dashboard/compliance) page.
## Create a campaign in the dashboard
Open the [Campaigns](https://app.goguava.ai/dashboard/campaigns) page and click **Create Campaign**. Configure your campaign name, origin phone numbers, calling windows, and retry settings.
Once created, take note of the campaign code — it starts with `gcmp-...`.
## Upload contacts
From the campaign's detail page in the dashboard, upload your contact list. Each contact needs a phone number and any per-call data variables your agent will use (such as a patient name or appointment time).
These variables will be accessible inside your agent callbacks via call.getVariable()} />.
## Write your agent
Define an `Agent` and attach callbacks for each stage of the call.
export const AGENT_PY = `import guava
from guava import Agent, Field
agent = Agent(
name="Sarah",
organization="Valley Dental",
purpose="Remind patients about their upcoming dental appointments.",
)
# Fires at the start of every call. We'll start by using reach_person()
# to confirm we're talking to the right person.
@agent.on_call_start
def on_call_start(call: guava.Call):
call.reach_person(
contact_full_name=call.get_variable("patient_name"),
)
# Fires once reach_person() resolves. outcome="available" means the contact answered.
@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str):
if outcome == "available":
# Appointment details are only loaded into the context after the
# caller's identity has been confirmed.
call.add_info("appointment_details", {
"patient_name": call.get_variable("patient_name"),
"appointment_date": call.get_variable("appointment_date"),
"appointment_time": call.get_variable("appointment_time")
})
call.set_task(
"confirm_appointment",
objective="Confirm the appointment date and time.",
checklist=[
Field(
key="appointment_response",
description="Whether the patient confirms, reschedules, or cancels",
field_type="multiple_choice",
choices=["confirmed", "reschedule", "cancel"],
),
],
)
else:
call.hangup()
# Fires when all checklist items are resolved.
@agent.on_task_complete("confirm_appointment")
def on_confirmed(call: guava.Call):
call.hangup("Thank them and end the call.")`;
export const AGENT_TS = `import * as guava from "@guava-ai/guava-sdk";
const agent = new guava.Agent({
name: "Sarah",
organization: "Valley Dental",
purpose: "Remind patients about their upcoming dental appointments.",
});
// Fires at the start of every call. We'll start by using reachPerson()
// to confirm we're talking to the right person.
agent.onCallStart(async (call: guava.Call) => {
await call.reachPerson(await call.getVariable("patient_name"));
});
// Fires once reachPerson() resolves. outcome="available" means the contact answered.
agent.onReachPerson(async (call: guava.Call, outcome: string) => {
if (outcome === "available") {
// Appointment details are only loaded into the context after the
// caller's identity has been confirmed.
await call.addInfo("appointment_details", {
patient_name: await call.getVariable("patient_name"),
appointment_date: await call.getVariable("appointment_date"),
appointment_time: await call.getVariable("appointment_time"),
});
await call.setTask({
taskId: "confirm_appointment",
objective: "Confirm the appointment date and time.",
checklist: [
guava.Field({
key: "appointment_response",
description: "Whether the patient confirms, reschedules, or cancels",
fieldType: "multiple_choice",
choices: ["confirmed", "reschedule", "cancel"],
}),
],
});
} else {
await call.hangup();
}
});
// Fires when all checklist items are resolved.
agent.onTaskComplete("confirm_appointment", async (call) => {
await call.hangup("Thank them and end the call.");
});`;
agent.call_local() or agent.chat(). Pass a variables dict to simulate per-contact data:agent.callLocal() or agent.chat(). Pass a variables object to simulate per-contact data:agent.attach_campaign("gcmp-..."). This "attaches" your agent to the Campaign that we previously created.await agent.attachCampaign("gcmp-..."). This "attaches" your agent to the Campaign that we previously created.- Isolated environments — Each deployment runs in its own private sandbox, completely separated from other users' workloads.
- Network protection — Your sandbox can make outbound requests to the internet (e.g. calling APIs), but no one can connect into your sandbox from the outside.
- Secure credentials — Your API key and phone number are injected securely at runtime and never appear in logs.
- Dedicated resources — CPU and memory are reserved for your deployment, so performance is consistent.
/tmp. Note that /tmp is ephemeral: contents are lost when the sandbox restarts.
` | Campaign details and status counts |
| `guava campaigns pause ` / `resume ` / `delete ` | Lifecycle controls |
| `guava campaigns add-contacts [flags…]` | Upload contacts |
| `guava widget [--ttl SEC]` | Mint a WebRTC widget code |
### Command reference
#### `guava login`
Authenticates the CLI against Guava via OAuth. Opens your default browser to a sign-in page and stores the resulting credentials locally so subsequent commands can call the API on your behalf.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| --no-launch-browser | flag | No | Print the login URL instead of opening a browser. |
#### `guava logout`
Clears stored credentials. No parameters.
#### `guava create`
Scaffolds a new Guava project on disk — generates `main.py`, `pyproject.toml`, `PRD.md`, `README.md`, and the `guava.toml` config — and (unless `--skip-deps` is set) runs `uv sync` to install dependencies. For outbound projects it also creates the matching campaign on the server.
`guava create` runs in **interactive mode** by default — the CLI prompts for anything you don't pass. In **non-interactive mode** (when stdin is not a TTY, or when you pass `--no-prompt`), there are no prompts: required flags must be supplied or the command errors, and optional flags fall back to documented defaults.
**Positional argument**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| name | string | No | Project path or name. Defaults to current directory. |
**Non-interactive mode flags** — in interactive mode you can omit any of these and the CLI will prompt; in non-interactive mode they behave as noted under "Required".
| Name | Type | Required (non-interactive) | Description |
|------|------|----------------------------|-------------|
| --no-prompt | flag | No | Force non-interactive mode. Auto-enabled when stdin is not a TTY. |
| --direction | inbound \| outbound | Yes | Call direction for the project. The only flag that has no default. |
| --base-image | string | No | Sandbox base image. Default `python-sandbox:3.14`. |
| --tier | seed \| fruit \| tree | No | Instance tier. Default `seed`. |
| --replicas | integer | No | Number of pod replicas. Default 1. |
Inbound-only (`--direction inbound`):
| Name | Type | Required (non-interactive) | Description |
|------|------|----------------------------|-------------|
| --phone | string | No | Phone source: E.164 number, `any` (first owned number), or `buy` (provision a new one). |
Outbound-only (`--direction outbound`):
| Name | Type | Required (non-interactive) | Description |
|------|------|----------------------------|-------------|
| --calling-windows | JSON | Yes | E.g. `[{"day":"monday","start":"09:00","end":"17:00"}]`. No default — must be supplied. |
| --campaign-name | string | No | Campaign name. Defaults to the project name. |
| --timezone | IANA TZ | No | Default detected from system. |
| --origin-number | string (repeatable) | No | E.164, `any`, or `buy`. Repeat for multiple. |
| --max-concurrency | integer | No | Max concurrent calls. Default 1. |
| --max-attempts | integer | No | Max attempts per recipient. Default 1. |
| --start-date | YYYY-MM-DD | No | Campaign start date. Default today. |
| --description | string | No | Free-form description used as outreach context. |
| --test-phone | E.164 | No | Number that will receive a test call. |
Passing an inbound-only flag with `--direction outbound` (or vice-versa) will result in an error.
#### `guava run`
Runs the agent locally on your machine. Anything after `--` is forwarded straight to `main.py`, which is useful for one-off flags your agent reads from `argv`.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Project directory. Defaults to current directory. |
| -- args… | passthrough | No | Anything after `--` is forwarded verbatim to `uv run main.py`. |
#### `guava update`
Edits the fields in `guava.toml` — project name, base image, and instance tier — without re-scaffolding the project. Use this whenever you want to bump the Python sandbox version or move between tiers.
Like `create`, `guava update` runs in **interactive mode** by default and prompts for each field, showing the current value as the default. In **non-interactive mode** (`--no-prompt` or no TTY), no prompts run and any field you don't pass simply keeps its current value — nothing is required.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Project directory. Defaults to current directory. |
**Non-interactive mode flags** — in interactive mode the CLI prompts for each of these; in non-interactive mode, any flag you omit leaves the existing value unchanged.
| Name | Type | Required (non-interactive) | Description |
|------|------|----------------------------|-------------|
| --no-prompt | flag | No | Force non-interactive mode. Auto-enabled when stdin is not a TTY. |
| --name | string | No | New project name. |
| --base-image | string | No | New base image. |
| --tier | seed \| fruit \| tree | No | New instance tier. |
`guava deploy update` has been removed. Running it will display a message directing you to use `guava update` instead.
#### `guava self-upgrade`
Updates the `guava` binary itself to the latest released version. No parameters.
#### `guava deploy up`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| dir | string | No | Optional path to the project directory. Defaults to the current directory. |
| --rebuild | flag | No | Force a fresh build even if code has not changed. |
#### `guava deploy down`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| --id | string | No | Optional task ID to stop directly. |
#### `guava deploy scale`
Scales an already-running deployment up or down by setting the desired pod-replica count. Use this to handle traffic spikes or scale back when idle without redeploying.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| replicas | integer | Yes | Number of pod replicas. |
| dir | string | No | Project directory. Defaults to current directory. |
#### `guava deploy status`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. If omitted, behaves like `deploy list`. |
#### `guava deploy logs`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| -n, --tail | integer | No | Number of log lines to retrieve (default 200, max 1000). |
#### `guava deploy build-logs`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
| --id | string | No | Optional Cloud Build ID to look up directly. |
#### `guava deploy list`
Lists all deployments for the authenticated user as a table (NAME, NUMBER, ACTIVE, ID). `ls` is an alias for `list`.
#### `guava deploy changed`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| target | string | No | Optional project name or directory path. Defaults to the current directory. |
Checks whether project files have changed since the last deploy.
#### `guava numbers list`
Lists every phone number your active org owns. `ls` is an alias for `list`. No parameters.
#### `guava numbers buy`
| Name | Type | Required | Description |
|------|------|----------|-------------|
| dir | string | No | Optional path to the project directory. Defaults to the current directory. |
Purchases a phone number and stores it in `guava.toml`. On the next deploy, the number is available to your code via the `GUAVA_AGENT_NUMBER` environment variable.
#### `guava conversations list`
Lists past conversations (calls) for your active org, newest first. All filters are optional and can be combined; results are paginated via `--after`.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| --direction | inbound \| outbound | No | Filter by call direction. |
| --from | E.164 | No | Filter by from-number. |
| --to | E.164 | No | Filter by to-number. |
| --date-from | ISO 8601 date | No | Earliest start date (e.g. `2026-06-01`). |
| --date-to | ISO 8601 date | No | Latest start date. |
| -n, --limit | integer | No | Page size (1–100). Default 50. |
| --after | string | No | Pagination cursor (`next_cursor` from previous page). |
#### `guava conversations get` | `transcript` | `recording`
Inspect a single past call by ID — `get` returns the metadata and outcome, `transcript` returns the speaker-by-speaker text, and `recording` downloads the raw audio.
All take a positional `call_id`. `recording` also accepts `-o, --output ` (default `.wav`).
#### `guava org`
Lists the orgs you belong to and lets you switch which one the CLI acts on. The active org determines which numbers, deployments, conversations, and campaigns the other commands see.
| Subcommand | Description |
|------------|-------------|
| `list` (alias `ls`) | List the orgs you belong to. Also the default when no subcommand is given (`guava org`). |
| `use [org_id]` | Switch the active org. Omit `org_id` to pick interactively from the list. |
#### `guava campaigns`
Manage outbound campaigns from the CLI: inspect their state, pause/resume/delete them, and upload contact lists. Each campaign is referenced by its `code`, a `gcmp-`-prefixed identifier (e.g. `gcmp-xxxxxxxxxxxxxxxxxxxx`) shown by `guava campaigns list` or on the dashboard.
| Subcommand | Description |
|------------|-------------|
| `list` (alias `ls`) | List outbound campaigns. |
| `show ` | Show campaign details and per-status contact counts. |
| `pause ` | Pause an in-flight campaign. |
| `resume ` | Resume a paused campaign. |
| `delete ` | Delete a campaign. |
| `add-contacts [flags…]` | Upload contacts to a campaign from a file (see below). |
**`add-contacts` arguments**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| code | string | Yes | Campaign code (e.g. `gcmp-...`). |
| file | path | Yes | Contacts file. Format dispatched by extension: `.csv` (header row with `phone_number`; other columns become string entries in each contact's `data`), `.json` (array of objects), `.jsonl` / `.ndjson` (one object per line). |
| --allow-duplicates | flag | No | Upload contacts that are already on the campaign. |
| --accept-tos | flag | No | Confirm the contacts comply with the [Terms of Service](https://goguava.ai/terms). Required in non-interactive mode; otherwise prompted. |
Every contact must include a `phone_number` field in E.164 format (e.g. `+15555550100`).
#### `guava widget`
Mints a short code that lets a browser-based WebRTC widget connect to your deployed agent. Use `--ttl` for a code that auto-expires; omit it for one that stays valid indefinitely.
| Name | Type | Required | Description |
|------|------|----------|-------------|
| --ttl | integer (seconds) | No | TTL for the WebRTC code. Omit for a permanent code. |
### The `guava.toml` file
Every Guava project has a `guava.toml` file in its root directory, created by `guava create` or `guava deploy up`. It stores the project's configuration and deployment state. The CLI reads it to identify the project and track deployments.
Projects created with CLI versions 0.29.0 and lower will have a JSON `.guava` file. The CLI will automatically migrate to the new `guava.toml` on the next save.
Do not edit this file manually. Use `guava update` to change settings. Manually editing `guava.toml` can put your project into an inconsistent state and cause deploy failures.
Commit this file to git. If you delete it or leave it out of version control, the CLI won't be able to find your project or resume previous deployments.
-o call.wav
# Tear down
guava deploy down`}
/>
Using Twilio? See the [Twilio Programmable Voice guide](/docs/twilio-programmable-voice) or the [Twilio Elastic SIP guide](/docs/twilio-elastic-sip) for step-by-step walkthroughs.
### Contact us for peer whitelisting
Currently, we are whitelisting SIP peers at our firewall level. Contact us at [hi@goguava.ai](mailto:hi@goguava.ai) to get your source IPs whitelisted.
### Check connectivity
Once whitelisted, try to make an `OPTIONS` ping to our SIP trunk at `sip.goguava.ai`. If the check fails, see our guide below on firewall configuration.
### Create a SIP code
Every SIP integration requires a `guavasip` code, which you can create in the Guava dashboard. `guavasip` codes work just like registered phone numbers — agents can listen to them and peers can dial them.
1. Open the [SIP page in the dashboard](https://app.goguava.ai/dashboard/sip).
2. Click **Create SIP Code**.
3. Take note of both the SIP code and the termination URI.
To connect an agent to both a phone number and a SIP code simultaneously, see the documentation for [guava.Runner](./runner).
### Dial your agent
The last step is to dial your agent using the termination URI (e.g. `sip:guavasip-xxx@sip.goguava.ai`). If you're having trouble connecting to your agent, please contact us at [hi@goguava.ai](mailto:hi@goguava.ai).
### Firewall configuration
To dial our SIP trunk from your network, you may need to whitelist us in your firewall.
| | |
| -------- | ------- |
| **FQDN** | The FQDN for the Guava SIP trunk is `sip.goguava.ai`. |
| **Trunk IP** | The IP address for the Guava SIP trunk is `136.118.29.109`. This IP is used for both media and signaling. |
| **TCP Ports** | `5060`, `5061` (TLS) |
| **UDP Ports** | `5060`, `10000-65535` (Media) |
| **ICMP** | Whitelist ICMP to allow connectivity checks (e.g. `ping`). |
| **Supported Codecs** | `PCMU` (G.711 μ-law), `PCMA` (G.711 a-law) |
---
import { CodeBlock } from '../views/docs/CodeBlock';
import { Callout, NextLink, Prose, PropTable } from '../views/docs/prose';
## Twilio Programmable Voice (TwiML)
Looking for Twilio Elastic SIP? Check out our [guide here](./twilio-elastic-sip).
If you already use Twilio Programmable Voice / TwiML, you can transfer to a Guava agent at any time during your call.
1. Create a Guava SIP code "guavasip-xxx" [on the Guava dashboard](https://app.goguava.ai/dashboard/sip).
2. Attach an agent to the SIP code.
3. Use the following TwiML template to transfer to your agent.
sip:guavasip-xxx@sip.goguava.ai
`}
/>
Below is a more detailed guide.
### Create a Guava SIP code
Every SIP integration in Guava requires a `guavasip` code. `guavasip` codes are used to route inbound calls to agents — agents can listen to codes and peers dial them.
Open the [SIP page in the Guava dashboard](https://app.goguava.ai/dashboard/sip) and click **Create SIP Code**.
Take note of the SIP code and the termination URI.
### Start an agent
Next, start an agent using `agent.listen_sip("guavasip-xxx")` — Guava forwards every call addressed to that code to your agent.
Looking for TwiML examples? Check out our [Twilio Programmable Voice / TwiML guide](./twilio-programmable-voice).
If you already own a phone number in Twilio and want to connect it to a Guava agent, you can do so using Twilio Elastic SIP Trunking.
### Create a Guava SIP code
Every SIP integration in Guava requires a `guavasip` code. `guavasip` codes are used to route inbound calls to agents — agents can listen to them and peers can dial them.
Open the [SIP page in the Guava dashboard](https://app.goguava.ai/dashboard/sip) and click **Create SIP Code**.
Take note of the SIP code and the termination URI.
### Create a Twilio Elastic SIP trunk
Navigate to the "Elastic SIP Trunks" page on your Twilio Console. You can find it using the search bar in the top right.
Click **Create new SIP Trunk** and provide the trunk with a name.
### Set the Origination URI
On the trunk's settings page, click **Origination** on the left hand side. Then click **Add new Origination URI** and enter your Guava termination URI (e.g. `sip:guavasip-xxx@sip.goguava.ai`). Then click **Add**.
### Assign a number to the Trunk
Assuming you already have a number in your Twilio account, under the **Develop** tab, go to **Phone Numbers** > **Manage** > **Active Numbers** and select that number. Select **Configure with** and change that setting to **SIP Trunk**. Then select the **SIP Trunk** dropdown and select the SIP trunk you created earlier.
Finally, scroll down and click **Save Configuration**.
### Start an agent
B["Amazon Connect contact flow\n(greeting, optional IVR routing)"]
B -->|Transfer to GUAVA_AGENT_NUMBER| C["Riley — Guava AI
Greets caller · Answers questions · Collects details"]
KB([knowledge base]) -.->|on_question| C
C --> D{Outcome}
D -->|Resolved on call| E[Wrap up call]
D -->|Needs follow-up| F[Create Connect task]
D -->|Needs live agent| G[Transfer back to Connect queue]
`} />
### Prerequisites
- Python 3.10 or later
- A **Guava account** with an API key and a phone number — sign up at [app.goguava.ai](https://app.goguava.ai)
- An **AWS account** with an Amazon Connect instance
### Step 1: Install Guava
Choose whichever package manager you prefer:
```bash
pip install guava-sdk # Install using pip
uv add guava-sdk # Install using uv
poetry add guava-sdk # Install using poetry
```
Also install `boto3` for the Amazon Connect task API:
```bash
pip install boto3
```
### Step 2: Set Up Amazon Connect
#### 2a. Create or locate your Connect instance
1. Open the [Amazon Connect console](https://console.aws.amazon.com/connect/).
2. Create an instance if you don't have one, or select an existing one.
3. Note the **Instance ID** — it's the UUID at the end of the instance ARN:
```
arn:aws:connect:us-east-1:123456789012:instance/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
└─────────────── Instance ID ──────┘
```
#### 2b. Create a task contact flow
Riley creates Amazon Connect tasks for cases requiring follow-up. Tasks need a dedicated contact flow — the default queue flow doesn't support them.
1. In your Connect instance, go to **Routing → Contact flows → Create contact flow**.
2. Name it `Guava Task Flow` (or similar).
3. Add a **Set working queue** block and point it to your support queue.
4. Connect it to a **Transfer to queue** block, then a **Disconnect** block.
5. **Save and publish** the flow.
6. Open the flow, click **Show additional flow information**, and copy the **Contact flow ID** (UUID at the end of the ARN).
#### 2c. Note your support queue phone number
This is the number Riley will transfer escalations to — your live agent queue's direct dial number in Amazon Connect.
1. Go to **Routing → Phone numbers** in your Connect instance.
2. Use any number claimed to your instance that routes to your support queue, or claim a new one.
3. Copy the number in E.164 format (e.g., `+15551234567`).
#### 2d. Create the contact flow that routes to Riley
This is the contact flow your customers actually call into. It transfers them to Riley's Guava number.
1. Go to **Routing → Contact flows → Create contact flow** (type: Inbound contact flow).
2. Name it `AI Customer Service`.
3. Build the flow:
```
Entry ──▶ Play prompt ──▶ Transfer to phone number ──▶ Disconnect
"Thanks for (GUAVA_AGENT_NUMBER)
calling Pinnacle Gear.
Please hold."
```
- Add a **Play prompt** block: set the text to a brief hold message (or skip it).
- Add a **Transfer to phone number** block:
- Set **Phone number** to your Guava agent number (the value of `GUAVA_AGENT_NUMBER`).
- Set **Transfer type** to `Softphone transfer` or `PSTN`.
- Add a **Disconnect** block on the error branch.
4. **Save and publish** the flow.
5. Assign this flow to an inbound phone number: go to **Channels → Phone numbers**, select a number, and set its contact flow to `AI Customer Service`.
**Adding routing logic**: If you want Connect to handle an IVR before routing to Riley, add a **Get customer input** block before the transfer. You can route product questions to Guava and billing escalations to a human queue based on the customer's menu selection.
### Step 3: Configure AWS Credentials
```bash
export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_DEFAULT_REGION="us-east-1" # Match your Connect instance region
```
The IAM user or role needs:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["connect:StartTaskContact"],
"Resource": "arn:aws:connect:*:*:instance/YOUR_INSTANCE_ID/*"
}
]
}
```
### Step 4: Set Environment Variables
```bash
# Guava
export GUAVA_API_KEY="your-guava-api-key"
export GUAVA_AGENT_NUMBER="+15551000000" # Your Guava phone number (Riley's number)
# Amazon Connect
export CONNECT_INSTANCE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_CONTACT_FLOW_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Task flow from Step 2b
export CONNECT_SUPPORT_QUEUE_NUMBER="+15551234567" # Live agent queue from Step 2c
```
### Step 5: Run Riley
```bash
python -m examples.integrations.ccaas.amazon_connect.ai_customer_service
```
You should see:
```
INFO:ai_customer_service:Riley is ready — listening for inbound calls on +15551000000
```
Riley is now live. Call your Amazon Connect number (the one you assigned the `AI Customer Service` flow to in Step 2d) — Connect will transfer the call to Riley automatically.
---
### How the Code Works
#### Defining the agent
```python
agent = Agent(
name="Riley",
organization="Pinnacle Gear Co.",
purpose="to help Pinnacle Gear customers with product questions, orders, returns, and warranty support",
)
```
The `Agent` is a top-level handle for your AI persona. You attach behavior to it with decorators (`@agent.on_call_start`, `@agent.on_question`, `@agent.on_task_complete(...)`) — each decorator registers a handler that runs when the corresponding event fires on a live call.
#### Accepting inbound calls
```python
agent.inbound_phone(os.environ["GUAVA_AGENT_NUMBER"]).run()
```
`inbound_phone` opens a persistent WebSocket to the Guava server and waits for calls. Each time a call arrives on Riley's number — whether from a customer dialing directly or transferred from Amazon Connect — the agent's registered handlers run on a fresh `Call` object that represents that conversation.
#### Kicking off the conversation
```python
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.set_task(
"intake",
objective="...",
checklist=[
guava.Say("Thanks for calling Pinnacle Gear. I'm Riley, and I'm here to help. ..."),
guava.Field(key="customer_name", ...),
guava.Field(key="inquiry", ...),
],
)
```
`on_call_start` runs as soon as the call connects. We use it to set the first task — a named intake step the agent works through, greeting the caller and collecting the fields we need before deciding what to do next.
#### Answering questions with a knowledge base
```python
@agent.on_question
def on_question(call: guava.Call, question: str) -> str:
return document_qa.ask(question)
```
Whenever a caller asks something Riley can't answer from context alone — "What's your return policy?", "Is this jacket machine washable?" — Guava invokes `on_question` with the question in natural language. `DocumentQA` retrieves the most relevant chunks from `SUPPORT_DOCS` and generates an accurate answer. Riley speaks the answer back and continues the conversation without any perceivable delay.
`DocumentQA()` with no `store` argument runs in **server mode** — your documents are uploaded to the Guava server and searched there. The `namespace` parameter scopes the uploaded documents to this agent so they don't collide with documents from other `DocumentQA` instances in the same account.
#### Routing after the conversation
```python
intent_recognizer = IntentRecognizer(
{
"live_agent": "Caller wants to speak with a human, agent, manager, or supervisor, or has a complaint, legal threat, or sensitive escalation",
"follow_up_task": "Caller needs a return, refund, exchange, warranty claim, or has a damaged or wrong item that requires team follow-up",
"resolved": "Caller's question was answered and no further action is needed",
}
)
@agent.on_task_complete("intake")
def handle_inquiry(call: guava.Call) -> None:
inquiry = call.get_field("inquiry", "")
intent = intent_recognizer.classify(inquiry)
if intent == "live_agent":
escalate_to_human(call)
elif intent == "follow_up_task":
collect_followup_details(call)
else:
call.hangup(...)
```
After the `intake` task finishes collecting details, the registered `@agent.on_task_complete("intake")` handler classifies the outcome using `IntentRecognizer` and routes accordingly. Using an LLM-based classifier handles natural phrasing correctly — "the zipper broke on the first use" maps to `follow_up_task` even without explicitly matching "broken". The recognizer is instantiated once at module level and reused across calls.
| Outcome | Example signals | Action |
|---|---|---|
| Resolved | Question answered, no action needed | Wrap up and end call |
| Follow-up | Return request, warranty claim | Collect email, create Connect task |
| Live agent | "I want to speak to someone", complaint | Transfer back to Connect |
#### Transferring back to Amazon Connect
```python
def escalate_to_human(call: guava.Call) -> None:
call.transfer(
os.environ["CONNECT_SUPPORT_QUEUE_NUMBER"],
"Let the customer know you're connecting them with a specialist. "
"Then transfer the call.",
)
```
The second argument to `call.transfer` gives Riley natural language guidance on what to say before transferring — she'll let the customer know what's happening and transfer when it feels right in the conversation. The customer lands in the Connect support queue as a normal inbound call, which agents handle in the Contact Control Panel (CCP).
#### Creating a Connect task for follow-up
```python
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"Follow-up Required — {call.get_field('customer_name')}"[:512],
Description=f"Customer: ...\nEmail: ...\nOrder: ...\nIssue: ..."[:4096],
Attributes={...},
)
```
When a caller needs follow-up but doesn't need a live agent right now, Riley collects their email and order number in a second task (`follow_up`). The `@agent.on_task_complete("follow_up")` handler then creates a task in Amazon Connect via `StartTaskContact`. Agents see it in the CCP like any other contact — with the customer's name, issue summary, and email for follow-up.
---
### Customization Ideas
**Use your own knowledge base**
Replace `SUPPORT_DOCS` with your actual product documentation, policy pages, or FAQs. `DocumentQA` handles chunking and retrieval automatically — paste in as much text as you need.
**Add IVR routing in Connect before transferring**
Instead of routing all calls to Riley, add a **Get customer input** block in your Connect flow. Route product questions to Riley's number and billing escalations to a human queue. Riley only handles the calls she's best suited for.
**Pass context from Connect to Riley via SIP**
For more advanced setups, Amazon Connect can transfer calls over a SIP trunk to a Guava SIP endpoint. This lets Connect pass the original Contact ID and other attributes as SIP headers, which the agent can read from the call info. You can then link Riley's Connect task back to the original call using `PreviousContactId` for full call chain reporting.
**Route different inquiry types to different agents**
Run multiple Guava agents on different agent numbers — one for product support, one for returns, one for technical help. Have Connect's IVR route to the right one based on the customer's menu selection.
**Use call info to customize behavior per call**
The `@agent.on_call_received` decorator lets you inspect the inbound `CallInfo` (caller number, SIP headers, etc.) before the call is accepted. Use this to accept or decline calls, or to set per-call variables in `on_call_start` that change Riley's behavior — for example, routing region-specific callers to region-specific transfer numbers.
### Complete Example
```python
import guava
import os
import logging
import json
import boto3
from datetime import datetime
from guava import Agent, logging_utils
from guava.helpers.openai import IntentRecognizer
from guava.helpers.rag import DocumentQA
logger = logging.getLogger("ai_customer_service")
# ---------------------------------------------------------------------------
# Knowledge base
# Guava answers caller questions from these documents in real time.
# Replace with your own product docs, policies, or FAQs.
# ---------------------------------------------------------------------------
SUPPORT_DOCS = """
Pinnacle Gear Co. — Customer Support Reference
RETURNS & REFUNDS
- We accept returns within 30 days of purchase for unused items in original packaging.
- Items showing signs of use may be exchanged for store credit at our discretion.
- Refunds are processed within 5–7 business days of receiving the returned item.
- Sale items are final sale and cannot be returned or exchanged.
- Start a return at pinnaclegear.com/returns or by calling our support line.
SHIPPING
- Standard shipping (5–7 business days): free on orders over $75, otherwise $7.99.
- Expedited shipping (2–3 business days): $14.99 flat rate.
- Overnight shipping: $29.99. Orders placed before 2 PM ET ship the same day.
- We ship to all 50 US states and Canada. International shipping is not available.
WARRANTY
- All products carry a 1-year limited warranty against manufacturing defects.
- Summit Series backpacks and Trail Pro footwear carry a lifetime warranty.
- Warranty claims require proof of purchase. Email support@pinnaclegear.com.
- Damage from misuse, normal wear, or accidents is not covered.
SIZING
- Apparel follows standard US sizing. See pinnaclegear.com/size-guide.
- Footwear runs true to size; for wide feet, size up by half a size.
- When between sizes, size up for layering or down for an athletic fit.
ORDERS & ACCOUNT
- Track orders at pinnaclegear.com/track using your order number and email.
- To modify or cancel an order, contact us within 1 hour of placing it.
- We accept Visa, Mastercard, Amex, Discover, PayPal, and Pinnacle gift cards.
- Pinnacle Rewards: 1 point per dollar spent; 100 points = $5 reward credit.
PRODUCT CARE
- Machine wash apparel on cold, gentle cycle. Tumble dry on low heat.
- Do not use fabric softener on moisture-wicking or DWR-coated gear.
- Re-apply DWR treatment after 10–15 wash cycles.
- Store sleeping bags loosely in a large cotton sack, never compressed long-term.
"""
document_qa = DocumentQA(documents=SUPPORT_DOCS, namespace="pinnacle-gear-customer-service")
connect_client = boto3.client("connect")
intent_recognizer = IntentRecognizer(
{
"live_agent": "Caller wants to speak with a human, agent, manager, or supervisor, or has a complaint, legal threat, or sensitive escalation",
"follow_up_task": "Caller needs a return, refund, exchange, warranty claim, or has a damaged or wrong item that requires team follow-up",
"resolved": "Caller's question was answered and no further action is needed",
}
)
agent = Agent(
name="Riley",
organization="Pinnacle Gear Co.",
purpose=(
"to help Pinnacle Gear customers with product questions, orders, "
"returns, and warranty support"
),
)
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.set_task(
"intake",
objective=(
"Help the customer with their inquiry. Answer questions accurately using "
"the knowledge base. If their issue needs a human specialist or involves "
"a complaint or legal matter, let them know you'll connect them with someone."
),
checklist=[
guava.Say(
"Thanks for calling Pinnacle Gear. I'm Riley, and I'm here to help."
),
guava.Field(
key="customer_name",
description="Ask for the customer's name.",
field_type="text",
required=True,
),
guava.Field(
key="inquiry",
description=(
"Understand what the customer needs. Answer their question if you can "
"using the knowledge base. If you cannot resolve it — they want a "
"return, refund, complaint resolution, or to speak with a person — "
"capture what they need in detail."
),
field_type="text",
required=True,
),
],
)
@agent.on_question
def on_question(call: guava.Call, question: str) -> str:
"""Answer caller questions from the knowledge base in real time."""
return document_qa.ask(question)
if intent == "live_agent":
escalate_to_human(call)
elif intent == "follow_up_task":
collect_followup_details(call)
else:
call.hangup(
"Thank the customer for calling Pinnacle Gear. Ask if there's "
"anything else you can help with, then wish them a great day."
)
def escalate_to_human(call: guava.Call) -> None:
"""Transfer the caller to the Amazon Connect support queue."""
call.transfer(
os.environ["CONNECT_SUPPORT_QUEUE_NUMBER"],
"Let the customer know you're connecting them with a Pinnacle Gear "
"specialist who can take care of them. Then transfer the call.",
)
def collect_followup_details(call: guava.Call) -> None:
"""Collect contact info so a specialist can follow up via a Connect task."""
call.set_task(
"follow_up",
objective=(
"Collect the customer's contact details so our team can follow up "
"and resolve their issue."
),
checklist=[
guava.Say(
"I'll have our support team reach out to you directly to sort this out."
),
guava.Field(
key="email",
description="Ask for their email address for our team to reach them.",
field_type="text",
required=True,
),
guava.Field(
key="order_number",
description=(
"Ask for their order number if they have one. It's fine if they don't."
),
field_type="text",
required=False,
),
],
)
@agent.on_task_complete("follow_up")
def create_followup_task(call: guava.Call) -> None:
results = {
"timestamp": datetime.utcnow().isoformat() + "Z",
"agent": "Riley",
"organization": "Pinnacle Gear Co.",
"use_case": "connect_inbound_ai_customer_service",
"fields": {
"customer_name": call.get_field("customer_name"),
"inquiry": call.get_field("inquiry"),
"email": call.get_field("email"),
"order_number": call.get_field("order_number"),
},
}
print(json.dumps(results, indent=2))
logger.info("Follow-up details captured.")
try:
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"Follow-up Required — {call.get_field('customer_name', 'Customer')}"[:512],
Description=(
f"Customer: {call.get_field('customer_name')}\n"
f"Email: {call.get_field('email')}\n"
f"Order: {call.get_field('order_number', 'N/A')}\n"
f"Issue: {call.get_field('inquiry')}"
)[:4096],
References={
"source": {"Value": "guava_ai_customer_service", "Type": "STRING"},
},
Attributes={
"customer_name": call.get_field("customer_name", ""),
"email": call.get_field("email", ""),
"order_number": call.get_field("order_number", ""),
},
)
logger.info("Amazon Connect follow-up task created successfully.")
except Exception as e:
logger.error("Failed to create Amazon Connect task: %s", e)
call.hangup(
"Let the customer know our support team will reach out by email within "
"one business day. Thank them for their patience and wish them a great day."
)
if __name__ == "__main__":
logging_utils.configure_logging()
logger.info(
"Riley is ready — listening for inbound calls on %s",
os.environ.get("GUAVA_AGENT_NUMBER", "(GUAVA_AGENT_NUMBER not set)"),
)
agent.inbound_phone(os.environ["GUAVA_AGENT_NUMBER"]).run()
```
---
import { Callout } from '../views/docs/prose';
import MermaidDiagram from '../components/MermaidDiagram';
## Appointment Reminder
This example shows how to use Guava to call patients and remind them of upcoming appointments. If a patient needs to reschedule, the agent checks your Amazon Connect queue in real time — and either transfers them directly to a live scheduling agent (if one is free) or captures their callback preference and creates a Connect task (if the queue is busy).
### What Happens on the Call
B{Reach the right person?}
B -->|No| C[Leave voicemail, end call]
B -->|Yes| D{Can they make the appointment?}
D -->|Yes| E[Send SMS confirmation]
D -->|No| F{Check Connect queue}
F -->|Agent free| G[Transfer live call]
F -->|Queue busy| H[Collect callback preference]
H --> I[Create Connect task for scheduler callback]
`} />
### Prerequisites
### Step 1: Install Guava
Choose whichever package manager you prefer:
```bash
pip install guava-sdk # Install using pip
uv add guava-sdk # Install using uv
poetry add guava-sdk # Install using poetry
```
You also need `boto3` for the Amazon Connect API:
```bash
pip install boto3
```
### Step 2: Set Up Amazon Connect
If you already have a Connect instance configured, skip to the parts you haven't done yet.
#### 2a. Create a Connect Instance
1. Open the [Amazon Connect console](https://console.aws.amazon.com/connect/).
2. Click **Create instance** and follow the setup wizard.
3. Once the instance is created, open it and copy the **Instance ID** from the ARN shown in the overview — it's the UUID at the end:
```
arn:aws:connect:us-east-1:123456789012:instance/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This is your CONNECT_INSTANCE_ID
```
#### 2b. Create a Contact Flow for Task Routing
Amazon Connect tasks need a dedicated contact flow — the default queue flow does not support tasks.
1. In your Connect instance, go to **Routing → Contact flows → Create contact flow**.
2. Name it something like `Guava Task Routing Flow`.
3. Add a **Set working queue** block and connect it to your scheduling queue.
4. Add a **Transfer to queue** block after that.
5. Add a **Disconnect / hang up** block at the end of the error branch.
6. Save and publish the flow.
7. Open the flow, click **Show additional flow information**, and copy the **Contact flow ID** (the UUID at the end of the ARN).
**Tip:** For a minimal test flow, you can also use any existing inbound contact flow — tasks will be routed to whatever queue the flow sets.
#### 2c. Set Up a Scheduling Queue
1. Go to **Routing → Queues → Add new queue**.
2. Name it (e.g., `Scheduling`) and assign it to the hours of operation and outbound caller ID of your choice.
3. Copy the **Queue ID** from the queue's ARN (the UUID at the end).
#### 2d. Get a Transfer Number
This is the phone number Guava will transfer rescheduling patients to — typically your scheduling desk or the Amazon Connect direct dial number for your scheduling queue.
- In Connect, go to **Channels → Phone numbers** to see claimed numbers.
- Or use any external scheduling desk number in E.164 format (e.g., `+15551234567`).
### Step 3: Configure AWS Credentials
The example uses `boto3`, which reads credentials from the standard AWS credential chain. The easiest way for local development:
The IAM user or role you use needs the following permissions:
- `connect:GetCurrentMetricData` — to check queue availability
- `connect:StartTaskContact` — to create callback tasks
A minimal IAM policy:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"connect:GetCurrentMetricData",
"connect:StartTaskContact"
],
"Resource": "arn:aws:connect:*:*:instance/YOUR_INSTANCE_ID/*"
}
]
}
```
### Step 4: Set Environment Variables
```bash
# Guava
export GUAVA_API_KEY="your-guava-api-key"
export GUAVA_AGENT_NUMBER="+15551000000" # Your Guava phone number
# Amazon Connect
export CONNECT_INSTANCE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_CONTACT_FLOW_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_QUEUE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_TRANSFER_NUMBER="+15551234567" # Scheduling desk number
```
### Step 5: Run the Example
```bash
python -m examples.integrations.ccaas.amazon_connect.appointment_reminder \
+15559876543 \
--name "Jane Doe" \
--appointment "Thursday, April 17 at 10:30 AM"
```
Replace `+15559876543` with the phone number to call and adjust `--name` and `--appointment` as needed.
**What to expect:**
- Guava calls the patient and verifies they're the right person
- If they confirm: you'll see a confirmation logged and an SMS is sent
- If they need to reschedule: the example checks your Connect queue in real time
- If agents are free: Guava transfers the patient to `CONNECT_TRANSFER_NUMBER`
- If the queue is busy: Guava collects a callback preference and creates a task in your Connect instance — visible to agents in the Contact Control Panel (CCP)
- If no one picks up: Guava leaves a voicemail
---
### How It Works
#### 1. Defining the Agent and Kicking Off the Call
```python
agent = Agent(
name="Alex",
organization="Bright Valley Medical Center",
purpose="to remind patients of their upcoming appointments and assist with rescheduling when needed",
)
agent.outbound_phone(
from_number=os.environ["GUAVA_AGENT_NUMBER"],
to_number=args.phone,
variables={"patient_name": args.name, "appointment": args.appointment},
).run()
```
`Agent` is the top-level handle for the AI persona. `outbound_phone` places the call and binds the agent to that single conversation. The `variables` dict is passed into the call and made available throughout — handlers can read each value with `call.get_variable(key)`.
#### 2. Reaching the Right Person (`reach_person`)
```python
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.reach_person(contact_full_name=call.get_variable("patient_name"))
```
`reach_person` handles the gatekeeper problem — it has the agent confirm they're speaking with the intended patient before proceeding. If a family member answers, the agent politely asks for the patient by name. The reach result is delivered to the handler registered with `@agent.on_reach_person`.
```python
@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str) -> None:
if outcome == "unavailable":
call.hangup("Leave a brief voicemail ...")
return
# otherwise, set up the reminder task
```
#### 3. Collecting the Appointment Response
```python
call.set_task(
"remind",
objective=...,
checklist=[
guava.Say(f"Hi {patient_name}, this is Alex calling from ..."),
guava.Field(
key="response",
description="Ask if they can make the appointment or need to reschedule.",
field_type="text",
required=True,
),
],
)
```
`set_task` gives the agent a named objective and a checklist of items to work through. `guava.Field` tells the agent what information to collect — the patient might say "Yes, I'll be there" or "Actually, I have a conflict that day" — and the agent normalizes that into a structured value you can inspect via `call.get_field(...)`.
#### 4. Classifying the Patient's Response
```python
from guava.helpers.openai import IntentRecognizer
intent_recognizer = IntentRecognizer(["confirmed", "needs to reschedule"])
@agent.on_task_complete("remind")
def handle_response(call: guava.Call) -> None:
response = call.get_field("response", "")
if intent_recognizer.classify(response) == "needs to reschedule":
handle_reschedule(call)
else:
...
```
When the `remind` task completes, the registered `@agent.on_task_complete("remind")` handler runs. Rather than matching against a list of keywords, `IntentRecognizer` uses an LLM to classify what the patient actually meant — natural phrasing like "I actually have a conflict that day" or "Can we move it?" still maps to `needs to reschedule` without enumerating every variant. The recognizer is instantiated once at module level and reused across calls.
#### 5. Checking the Connect Queue in Real Time
```python
def check_queue_availability() -> dict:
response = connect_client.get_current_metric_data(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
Filters={"Queues": [os.environ["CONNECT_QUEUE_ID"]], "Channels": ["VOICE"]},
CurrentMetrics=[
{"Name": "AGENTS_AVAILABLE", "Unit": "COUNT"},
{"Name": "CONTACTS_IN_QUEUE", "Unit": "COUNT"},
],
)
...
```
`GetCurrentMetricData` returns a real-time snapshot of the queue — how many agents are available and how many contacts are already waiting. This snapshot updates every ~15 seconds.
#### 6. Routing Decision: Transfer vs. Task
```python
queue = check_queue_availability()
if queue["agents_available"] > 0:
call.transfer(os.environ["CONNECT_TRANSFER_NUMBER"], "...")
else:
# collect callback preference, then create a task
call.set_task("callback", ...)
```
If a scheduler is free, Guava transfers the call live. If not, the agent collects the patient's preferred callback time in a follow-up `callback` task; its completion handler creates a Connect task via `StartTaskContact` — complete with the patient's name, original appointment, and preferred callback window. The task appears in your agents' Contact Control Panel (CCP) just like any other contact.
#### 7. SMS Confirmation
```python
call_state = {"appointment_confirmed": False}
# ... inside the "remind" handler, when the patient confirms:
call_state["appointment_confirmed"] = True
# ... after agent.run() returns:
if call_state["appointment_confirmed"]:
guava.Client().send_sms(...)
```
After `agent.run()` returns, if the patient confirmed, we send an SMS reminder via the Guava client. This runs after the call ends, so it never blocks the voice interaction.
---
### Customization Ideas
**Pull patient data from a database or CRM**
Replace the hardcoded `--name` and `--appointment` CLI args with a database query or CRM API call, and call patients in a loop:
```python
for patient in get_todays_appointments():
agent.outbound_phone(
from_number=os.environ["GUAVA_AGENT_NUMBER"],
to_number=patient["phone"],
variables={"patient_name": patient["name"], "appointment": patient["appointment"]},
).run()
```
**Set a queue depth threshold**
Instead of transferring whenever any agent is free, add a threshold — e.g., only transfer if fewer than 3 contacts are already waiting:
```python
if queue["agents_available"] > 0 and queue["contacts_in_queue"] < 3:
call.transfer(...)
```
**Route by appointment type**
Different appointment types may need different queues or transfer numbers. Pass the appointment type into the call as a variable and route accordingly:
```python
transfer_number = SPECIALIST_LINE if call.get_variable("type") == "specialist" else GENERAL_LINE
call.transfer(transfer_number, "...")
```
**Add multi-language support**
Guava supports English, Spanish, French, German, and Italian. The agent's voice can be set per call using the persona configuration on the underlying `Call` object.
### Complete Example
```python
import guava
import os
import logging
import json
import argparse
import boto3
from datetime import datetime
from guava import Agent, logging_utils
from guava.helpers.openai import IntentRecognizer
logger = logging.getLogger("appointment_reminder")
connect_client = boto3.client("connect")
intent_recognizer = IntentRecognizer(["confirmed", "needs to reschedule"])
# State the SMS step needs after the call ends.
call_state: dict = {"appointment_confirmed": False}
agent = Agent(
name="Alex",
organization="Bright Valley Medical Center",
purpose=(
"to remind patients of their upcoming appointments and assist "
"with rescheduling when needed"
),
)
def check_queue_availability() -> dict:
"""Query Amazon Connect for real-time agent availability in the scheduling queue."""
try:
response = connect_client.get_current_metric_data(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
Filters={
"Queues": [os.environ["CONNECT_QUEUE_ID"]],
"Channels": ["VOICE"],
},
CurrentMetrics=[
{"Name": "AGENTS_AVAILABLE", "Unit": "COUNT"},
{"Name": "CONTACTS_IN_QUEUE", "Unit": "COUNT"},
],
)
agents_available = 0
contacts_in_queue = 0
for result in response.get("MetricResults", []):
for collection in result.get("Collections", []):
name = collection["Metric"]["Name"]
value = collection.get("Value") or 0
if name == "AGENTS_AVAILABLE":
agents_available = int(value)
elif name == "CONTACTS_IN_QUEUE":
contacts_in_queue = int(value)
logger.info(
"Queue check — agents available: %d, contacts in queue: %d",
agents_available,
contacts_in_queue,
)
return {"agents_available": agents_available, "contacts_in_queue": contacts_in_queue}
except Exception as e:
logger.error("Failed to fetch queue metrics: %s", e)
return {"agents_available": 0, "contacts_in_queue": 0}
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.reach_person(contact_full_name=call.get_variable("patient_name"))
@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str) -> None:
if outcome == "unavailable":
appointment = call.get_variable("appointment")
call.hangup(
"We were unable to reach the patient. Leave a brief, friendly voicemail from "
"Bright Valley Medical Center reminding them of their appointment on "
f"{appointment} and asking them to call back to confirm or reschedule."
)
return
patient_name = call.get_variable("patient_name")
appointment = call.get_variable("appointment")
call.set_task(
"remind",
objective=(
f"Remind {patient_name} of their appointment at Bright Valley Medical "
f"Center on {appointment}. Ask if they can attend or need to reschedule."
),
checklist=[
guava.Say(
f"Hi {patient_name}, this is Alex calling from Bright Valley "
f"Medical Center with a reminder about your appointment on {appointment}."
),
guava.Field(
key="response",
description=(
"Ask if they can make the appointment or need to reschedule. "
"Capture their answer as 'confirmed' or 'reschedule'."
),
field_type="text",
required=True,
),
],
)
@agent.on_task_complete("remind")
def handle_response(call: guava.Call) -> None:
response = call.get_field("response", "")
if intent_recognizer.classify(response) == "needs to reschedule":
handle_reschedule(call)
else:
call_state["appointment_confirmed"] = True
call.hangup(
"Thank the patient for confirming. Remind them to arrive 15 minutes "
"early and bring their insurance card and a photo ID. Wish them well."
)
def handle_reschedule(call: guava.Call) -> None:
queue = check_queue_availability()
if queue["agents_available"] > 0:
# Scheduling agents are free — transfer directly.
call.transfer(
os.environ["CONNECT_TRANSFER_NUMBER"],
"Let the patient know you're connecting them with a scheduling specialist "
"who will help find a new appointment time. Then transfer the call.",
)
else:
# Queue is busy — collect callback preference and create a task.
call.set_task(
"callback",
objective=(
"Our scheduling team is currently busy. Collect the patient's preferred "
"callback window so a scheduler can call them back."
),
checklist=[
guava.Say(
"Our scheduling team is with other patients right now. "
"I'll arrange for a scheduler to call you back."
),
guava.Field(
key="preferred_callback",
description=(
"Ask when would be a good time for our scheduling team to call "
"them back. Capture their preferred day and time of day."
),
field_type="text",
required=True,
),
],
)
@agent.on_task_complete("callback")
def create_reschedule_task(call: guava.Call) -> None:
patient_name = call.get_variable("patient_name")
appointment = call.get_variable("appointment")
preferred_callback = call.get_field("preferred_callback")
results = {
"timestamp": datetime.utcnow().isoformat() + "Z",
"agent": "Alex",
"organization": "Bright Valley Medical Center",
"use_case": "appointment_reminder_reschedule",
"fields": {
"patient_name": patient_name,
"original_appointment": appointment,
"preferred_callback": preferred_callback,
},
}
print(json.dumps(results, indent=2))
logger.info("Reschedule details captured.")
try:
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"Reschedule Needed — {patient_name}"[:512],
Description=(
f"Patient: {patient_name}\n"
f"Original appointment: {appointment}\n"
f"Preferred callback: {preferred_callback}\n"
"Action: Call patient back to reschedule their appointment."
)[:4096],
References={
"source": {"Value": "guava_appointment_reminder", "Type": "STRING"},
},
Attributes={
"patient_name": patient_name,
"original_appointment": appointment,
"preferred_callback": preferred_callback or "",
},
)
logger.info("Amazon Connect reschedule task created successfully.")
except Exception as e:
logger.error("Failed to create Amazon Connect task: %s", e)
call.hangup(
"Let the patient know a scheduling specialist will call them back at their "
"preferred time. Thank them for their patience and wish them a great day."
)
if __name__ == "__main__":
logging_utils.configure_logging()
parser = argparse.ArgumentParser(
description=(
"Outbound appointment reminder with smart escalation for Bright Valley Medical Center. "
"Confirms the appointment, transfers to a live scheduler if one is available, or "
"creates an Amazon Connect callback task if the queue is busy."
)
)
parser.add_argument("phone", help="Patient phone number in E.164 format (e.g. +15551234567)")
parser.add_argument("--name", required=True, help="Full name of the patient")
parser.add_argument(
"--appointment",
default="tomorrow at 9:00 AM",
help="Appointment date and time string (default: 'tomorrow at 9:00 AM')",
)
args = parser.parse_args()
logger.info(
"Calling %s (%s) — appointment: %s",
args.name,
args.phone,
args.appointment,
)
agent.outbound_phone(
from_number=os.environ["GUAVA_AGENT_NUMBER"],
to_number=args.phone,
variables={"patient_name": args.name, "appointment": args.appointment},
).run()
# Send an SMS confirmation if the patient confirmed their appointment.
if call_state["appointment_confirmed"]:
try:
guava.Client().send_sms(
from_number=os.environ["GUAVA_AGENT_NUMBER"],
to_number=args.phone,
message=(
f"Hi {args.name}, this is Bright Valley Medical Center confirming "
f"your appointment on {args.appointment}. Please arrive 15 minutes early "
"and bring your insurance card and photo ID. Reply STOP to opt out."
),
)
logger.info("SMS confirmation sent to %s.", args.phone)
except Exception as e:
logger.error("Failed to send SMS confirmation: %s", e)
```
---
import { Callout } from '../views/docs/prose';
import MermaidDiagram from '../components/MermaidDiagram';
## CSAT Survey
This example shows how to use Guava to call customers after a support interaction and collect a brief satisfaction survey — NPS score, resolution status, and open feedback. The results are written to your logs and posted back into Amazon Connect as a task linked to the original support contact, so the survey responses live alongside the conversation they're about.
The Guava agent (**Jamie**) can:
- Reach the right customer using `reach_person` (handles voicemail and the gatekeeper problem)
- Politely decline if the customer doesn't want to participate, without forcing them through the survey
- Collect an NPS score, resolution status, and open-ended feedback in a single conversational task
- Create an Amazon Connect task linked to the original `ContactId` via `RelatedContactId`, so the survey is reportable in Connect's contact search and historical metrics
### How It Works
B{Reach the right person?}
B -->|No| C[End call politely]
B -->|Yes| D{Willing to participate?}
D -->|No| E[Thank them, hang up]
D -->|Yes| F[Collect NPS, resolution, feedback]
F --> G[Derive NPS category]
G --> H[Create linked Connect task]
H --> I[Thank customer, end call]
`} />
### Prerequisites
- Python 3.10 or later
- A **Guava account** with an API key and a phone number — sign up at [app.goguava.ai](https://app.goguava.ai)
- An **AWS account** with an Amazon Connect instance
- The **ContactId** of the original support call you want to survey about (Amazon Connect surfaces this in the Contact Control Panel and contact search)
### Step 1: Install Guava
Choose whichever package manager you prefer:
```bash
pip install guava-sdk # Install using pip
uv add guava-sdk # Install using uv
poetry add guava-sdk # Install using poetry
```
You also need `boto3` for the Amazon Connect API:
```bash
pip install boto3
```
### Step 2: Set Up Amazon Connect
If you already have a Connect instance configured, skip to the parts you haven't done yet.
#### 2a. Create or locate your Connect instance
#### 2b. Create a contact flow for survey tasks
Amazon Connect tasks need a dedicated contact flow — the default queue flow does not support tasks.
1. In your Connect instance, go to **Routing → Contact flows → Create contact flow**.
2. Name it something like `Guava CSAT Task Flow`.
3. Add a **Set working queue** block and point it at the queue you'd like surveys to be reviewed in (a CX or QA queue is a natural fit).
4. Add a **Transfer to queue** block, then a **Disconnect** block.
5. **Save and publish** the flow.
6. Open the flow, click **Show additional flow information**, and copy the **Contact flow ID** (the UUID at the end of the ARN).
**Tip:** If you only want surveys to land somewhere queryable rather than being worked by a live agent, point the flow at a low-priority "review" queue — the task will still appear in Connect's historical reports and contact search.
### Step 3: Configure AWS Credentials
The example uses `boto3`, which reads credentials from the standard AWS credential chain. The easiest way for local development:
A minimal IAM policy:
### Step 4: Set Environment Variables
```bash
# Guava
export GUAVA_API_KEY="your-guava-api-key"
export GUAVA_AGENT_NUMBER="+15551000000" # Your Guava phone number (Jamie's number)
# Amazon Connect
export CONNECT_INSTANCE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_CONTACT_FLOW_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Survey task flow from Step 2b
```
### Step 5: Run the Example
```bash
python -m examples.integrations.ccaas.amazon_connect.csat_survey \
+15559876543 \
--name "Jane Doe" \
--contact-id "11111111-2222-3333-4444-555555555555"
```
Replace `+15559876543` with the customer's phone number, set `--name` to their full name, and set `--contact-id` to the Amazon Connect `ContactId` of the original support call you're following up on.
**What to expect:**
- Guava calls the customer and verifies they're the right person
- Jamie asks if they have a minute for a quick survey
- If they decline, Jamie thanks them and ends the call gracefully — no pressure
- If they agree, Jamie collects an NPS score, asks whether the issue was resolved, and invites open-ended feedback
- The full survey result is printed as JSON to stdout and a Connect task is created **linked to the original support contact** via `RelatedContactId` — so the response shows up in contact search and historical reports tied to the conversation it's about
- If no one picks up, Guava ends the call politely
---
### How the Code Works
#### Defining the agent and starting the call
```python
agent = Agent(
name="Jamie",
organization="Pinnacle Gear Co.",
purpose=(
"to conduct a brief customer satisfaction survey about a recent "
"support experience"
),
)
agent.outbound_phone(
from_number=os.environ["GUAVA_AGENT_NUMBER"],
to_number=args.phone,
variables={
"customer_name": args.name,
"original_contact_id": args.contact_id,
},
).run()
```
`Agent` is the top-level handle for the AI persona. `outbound_phone` places the call and binds the agent to that single conversation. The `variables` dict is passed into the call and made available to all handlers via `call.get_variable(key)` — here we pass the customer's name (so Jamie can address them) and the original Connect `ContactId` (so the resulting survey task can be linked back to the support call it's about).
#### Reaching the right person
```python
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.reach_person(contact_full_name=call.get_variable("customer_name"))
@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str) -> None:
if outcome == "unavailable":
call.hangup("We were unable to reach the customer. End the call politely.")
return
# otherwise, set up the survey task
```
`reach_person` handles the gatekeeper problem — Jamie confirms she's speaking with the intended customer before starting the survey. If a family member or colleague answers, she politely asks for the right person. If the customer truly can't be reached, `outcome == "unavailable"` and we end the call without leaving a long voicemail (post-hoc surveys are easy to skip; we don't push them).
#### Asking permission, then collecting the survey
```python
call.set_task(
"survey",
objective=(
"Conduct a short, friendly customer satisfaction survey about the customer's "
"recent support call with Pinnacle Gear. Keep it conversational and brief."
),
checklist=[
guava.Say(f"Hi {customer_name}, this is Jamie from Pinnacle Gear. ..."),
guava.Field(key="willing_to_participate", ..., required=True),
guava.Field(key="nps_score", ..., field_type="integer", required=False),
guava.Field(key="issue_resolved", ..., required=False),
guava.Field(key="feedback", ..., required=False),
],
)
```
`set_task` gives Jamie a named objective and an ordered checklist. The first `Field` — `willing_to_participate` — is the gate. The remaining fields are marked `required=False` and the descriptions explicitly say *"Only ask this if they agreed to participate"* — so if the customer declines, Jamie doesn't push them through the rest of the survey. The agent reads the prompts as guidance and adapts its phrasing rather than reciting them verbatim, so the conversation stays natural even though the schema is structured.
#### Honoring the customer's choice
```python
participation_recognizer = IntentRecognizer(["willing to participate", "not willing to participate"])
@agent.on_task_complete("survey")
def save_survey(call: guava.Call) -> None:
willing = call.get_field("willing_to_participate", "")
if participation_recognizer.classify(willing) == "not willing to participate":
call.hangup(
"Respect their time and thank them for taking the call. "
"Wish them a great day."
)
return
# otherwise, save the survey
```
When the `survey` task completes, the `@agent.on_task_complete("survey")` handler runs. Customers respond with all kinds of phrasing — *"sure"*, *"now's not a great time"*, *"I'm driving"*, *"yeah I guess so"* — so we use `IntentRecognizer` to map the free-text answer to a clean `willing` / `not willing` decision. If they declined, we end the call with a thank-you. The recognizer is instantiated once at module level and reused across calls.
#### Deriving the NPS category
```python
try:
nps_int = int(nps_raw) if nps_raw else 0
except (ValueError, TypeError):
nps_int = 0
if nps_int >= 9:
nps_category = "promoter"
elif nps_int >= 7:
nps_category = "passive"
else:
nps_category = "detractor"
```
NPS uses three buckets — promoters (9–10), passives (7–8), and detractors (0–6). We compute the category server-side rather than asking the agent to do it, so the categorization is consistent across every call and shows up in the Connect task title and attributes in a form you can filter on.
#### Linking the survey back to the original contact
```python
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"CSAT Survey — {customer_name} ({nps_category})"[:512],
Description=f"Customer: ...\nNPS Score: ...\nIssue Resolved: ...\nFeedback: ..."[:4096],
RelatedContactId=original_contact_id,
Attributes={
"customer_name": customer_name,
"nps_score": str(nps_raw or ""),
"nps_category": nps_category,
"issue_resolved": issue_resolved,
},
)
```
The key field here is `RelatedContactId` — passing the original support call's `ContactId` tells Amazon Connect to link the new survey task to that conversation. In Connect's contact search, you can pivot from the support call to its survey task (and back) without joining tables yourself, and historical metrics that group by `RelatedContactId` will see them as a single customer interaction with a follow-up survey attached.
The `Attributes` dict is searchable in Connect's contact search — putting `nps_score`, `nps_category`, and `issue_resolved` here means CX leaders can filter and report on surveys directly inside the Connect console.
---
### Customization Ideas
**Trigger surveys automatically after every support call**
Instead of running this script manually, hook it into your support flow: after a Connect contact ends, fire a Lambda (via EventBridge on `Amazon Connect Contact Events`) that pulls the customer's name and phone from your CRM and invokes this example with the original `ContactId`. Surveys go out within minutes of the call ending, while the experience is fresh.
**Sample only a fraction of calls**
Calling every customer is overkill — most teams sample 10–20% of contacts. Add a random gate before invoking this script:
```python
import random
if random.random() < 0.15:
run_csat_survey(...)
```
**Skip detractors of detractors**
If the customer was already escalated or marked dissatisfied during the original call (visible in Connect attributes on the original contact), skip the survey or route them to a manager call instead — surveying angry customers can make things worse.
**Push results to a data warehouse**
Replace the `print(json.dumps(results, indent=2))` line with a write to your warehouse of choice (BigQuery, Snowflake, Redshift) or push to S3 in JSON Lines for downstream analytics — the Connect task gives you the operational view, the warehouse gives you the analytical view.
**Customize the survey per product line**
Pass a `product_line` variable into the call and conditionally include extra fields in the checklist — e.g., apparel customers get asked about fit and sizing, footwear customers get asked about comfort and durability. The same agent persona can run very different surveys depending on what the customer just bought.
---
### Complete Example
```python
import guava
import os
import logging
import json
import argparse
import boto3
from datetime import datetime
from guava import Agent, logging_utils
from guava.helpers.openai import IntentRecognizer
logger = logging.getLogger("csat_survey")
connect_client = boto3.client("connect")
participation_recognizer = IntentRecognizer(["willing to participate", "not willing to participate"])
agent = Agent(
name="Jamie",
organization="Pinnacle Gear Co.",
purpose=(
"to conduct a brief customer satisfaction survey about a recent "
"support experience"
),
)
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.reach_person(contact_full_name=call.get_variable("customer_name"))
@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str) -> None:
if outcome == "unavailable":
call.hangup("We were unable to reach the customer. End the call politely.")
return
customer_name = call.get_variable("customer_name")
call.set_task(
"survey",
objective=(
"Conduct a short, friendly customer satisfaction survey about the customer's "
"recent support call with Pinnacle Gear. Keep it conversational and brief."
),
checklist=[
guava.Say(
f"Hi {customer_name}, this is Jamie from Pinnacle Gear. "
"We noticed you recently contacted our support team, and I was hoping "
"to grab one minute of your time for a quick feedback survey. "
"Your input really helps us improve."
),
guava.Field(
key="willing_to_participate",
description=(
"Ask if they have about a minute to share some feedback. "
"Capture 'yes' or 'no'."
),
field_type="text",
required=True,
),
guava.Field(
key="nps_score",
description=(
"On a scale of 1 to 10, how likely are they to recommend Pinnacle Gear "
"support to a friend or colleague? Only ask this if they agreed to participate."
),
field_type="integer",
required=False,
),
guava.Field(
key="issue_resolved",
description=(
"Ask if their issue was fully resolved during the support call. "
"Capture 'yes', 'no', or 'partially'. Only ask if they agreed to participate."
),
field_type="text",
required=False,
),
guava.Field(
key="feedback",
description=(
"Ask if there's anything we could have done better, or any other "
"comments they'd like to share. Only ask if they agreed to participate."
),
field_type="text",
required=False,
),
],
)
@agent.on_task_complete("survey")
def save_survey(call: guava.Call) -> None:
customer_name = call.get_variable("customer_name")
original_contact_id = call.get_variable("original_contact_id")
willing = call.get_field("willing_to_participate", "")
if participation_recognizer.classify(willing) == "not willing to participate":
call.hangup(
"Respect their time and thank them for taking the call. "
"Wish them a great day."
)
return
nps_raw = call.get_field("nps_score")
issue_resolved = call.get_field("issue_resolved", "unknown")
feedback = call.get_field("feedback", "No additional feedback provided.")
# Derive NPS category from score.
try:
nps_int = int(nps_raw) if nps_raw else 0
except (ValueError, TypeError):
nps_int = 0
if nps_int >= 9:
nps_category = "promoter"
elif nps_int >= 7:
nps_category = "passive"
else:
nps_category = "detractor"
results = {
"timestamp": datetime.utcnow().isoformat() + "Z",
"agent": "Jamie",
"organization": "Pinnacle Gear Co.",
"use_case": "post_call_csat_survey",
"original_contact_id": original_contact_id,
"fields": {
"customer_name": customer_name,
"nps_score": nps_raw,
"nps_category": nps_category,
"issue_resolved": issue_resolved,
"feedback": feedback,
},
}
print(json.dumps(results, indent=2))
logger.info("CSAT survey results captured — NPS: %s (%s).", nps_raw, nps_category)
# Create a Connect task linked to the original support call via RelatedContactId.
# This ties the survey results to the interaction for reporting without altering
# the original contact's attributes.
try:
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"CSAT Survey — {customer_name} ({nps_category})"[:512],
Description=(
f"Customer: {customer_name}\n"
f"NPS Score: {nps_raw}/10 ({nps_category})\n"
f"Issue Resolved: {issue_resolved}\n"
f"Feedback: {feedback}"
)[:4096],
RelatedContactId=original_contact_id,
References={
"source": {"Value": "guava_csat_survey", "Type": "STRING"},
},
Attributes={
"customer_name": customer_name,
"nps_score": str(nps_raw or ""),
"nps_category": nps_category,
"issue_resolved": issue_resolved,
},
)
logger.info("Amazon Connect CSAT task created and linked to contact %s.", original_contact_id)
except Exception as e:
logger.error("Failed to create Amazon Connect CSAT task: %s", e)
call.hangup(
"Thank the customer sincerely for their feedback and time. "
"Let them know their input helps the team improve. Wish them a great day."
)
if __name__ == "__main__":
logging_utils.configure_logging()
parser = argparse.ArgumentParser(
description=(
"Outbound post-call CSAT survey for Pinnacle Gear Co. "
"Collects NPS score and feedback after a support interaction, then creates "
"a linked Amazon Connect task tied to the original call for reporting."
)
)
parser.add_argument("phone", help="Customer phone number in E.164 format (e.g. +15551234567)")
parser.add_argument("--name", required=True, help="Full name of the customer")
parser.add_argument(
"--contact-id",
required=True,
help="Amazon Connect ContactId of the original support call to link the survey to",
)
args = parser.parse_args()
logger.info(
"Calling %s (%s) for CSAT survey — original contact: %s",
args.name,
args.phone,
args.contact_id,
)
---
import { Callout } from '../views/docs/prose';
import MermaidDiagram from '../components/MermaidDiagram';
## Product Support
This example shows how to route inbound product support calls from Amazon Connect to a Guava AI agent that can answer most questions on its own — pulling from a product FAQ — and create an Amazon Connect task when a real human needs to follow up. Unlike the AI Customer Service example, this one keeps the routing simple (no live transfer back to a queue) and focuses on two outcomes: **resolve the question on the call**, or **collect details and hand off to a specialist asynchronously**.
The Guava agent (**Jordan**) can:
- Greet the caller, take their name, and understand what they need
- Answer product, return, shipping, and warranty questions in real time using a product FAQ knowledge base
- Recognize when an issue requires human follow-up (returns, refunds, complaints, damaged items, manager requests) and collect the customer's email and order number for a specialist to reach out
### How It Works
B["Amazon Connect contact flow\n(greeting, optional IVR)"]
B -->|Transfer to GUAVA_AGENT_NUMBER| C["Jordan — Guava AI
Greets caller · Takes name · Understands issue"]
KB([Product FAQ knowledge base]) -.->|on_question| C
C --> D{Outcome}
D -->|Question answered| E[Wrap up call]
D -->|Needs follow-up| F[Collect email + order number]
F --> G[Create Connect task for specialist]
G --> H[Promise email follow-up, end call]
`} />
### Prerequisites
### Step 1: Install Guava
Choose whichever package manager you prefer:
```bash
pip install guava-sdk # Install using pip
uv add guava-sdk # Install using uv
poetry add guava-sdk # Install using poetry
```
You also need `boto3` for the Amazon Connect API:
```bash
pip install boto3
```
### Step 2: Set Up Amazon Connect
#### 2a. Create or locate your Connect instance
#### 2b. Create a contact flow for escalation tasks
Jordan creates Amazon Connect tasks for cases that need specialist follow-up. Tasks need a dedicated contact flow — the default queue flow doesn't support them.
1. In your Connect instance, go to **Routing → Contact flows → Create contact flow**.
2. Name it `Guava Support Task Flow` (or similar).
3. Add a **Set working queue** block and point it to your support queue.
4. Connect it to a **Transfer to queue** block, then a **Disconnect** block.
5. **Save and publish** the flow.
6. Open the flow, click **Show additional flow information**, and copy the **Contact flow ID** (the UUID at the end of the ARN).
#### 2c. Create the contact flow that routes to Jordan
This is the contact flow your customers actually call into. It transfers them to Jordan's Guava number.
1. Go to **Routing → Contact flows → Create contact flow** (type: Inbound contact flow).
2. Name it `Product Support`.
3. Build the flow:
```
Entry ──▶ Play prompt ──▶ Transfer to phone number ──▶ Disconnect
"Thanks for (GUAVA_AGENT_NUMBER)
calling Pinnacle Gear.
Please hold."
```
4. **Save and publish** the flow.
5. Assign this flow to an inbound phone number: go to **Channels → Phone numbers**, select a number, and set its contact flow to `Product Support`.
**No live transfer queue here.** Unlike the AI Customer Service example, this example doesn't transfer escalations back to a live agent — it creates an asynchronous Connect task instead. If you'd rather offer a live transfer for escalations, see the AI Customer Service walkthrough for that pattern.
### Step 3: Configure AWS Credentials
The IAM user or role needs:
### Step 4: Set Environment Variables
```bash
# Guava
export GUAVA_API_KEY="your-guava-api-key"
export GUAVA_AGENT_NUMBER="+15551000000" # Your Guava phone number (Jordan's number)
# Amazon Connect
export CONNECT_INSTANCE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export CONNECT_CONTACT_FLOW_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Task flow from Step 2b
```
### Step 5: Run Jordan
```bash
python -m examples.integrations.ccaas.amazon_connect.product_support
```
You should see:
```
INFO:product_support:Jordan is ready — listening for inbound calls on +15551000000
```
Jordan is now live. Call your Amazon Connect number (the one you assigned the `Product Support` flow to in Step 2c) — Connect will transfer the call to Jordan automatically.
**What to expect:**
- Jordan greets the caller, takes their name, and asks what they need
- For straightforward questions ("How do I wash my jacket?", "What's your return window?", "Do you ship to Canada?"), Jordan answers from the product FAQ in real time and wraps up the call
- For requests that need a human (returns, refunds, complaints, damaged items, *"can I speak to a manager"*), Jordan collects the customer's email and order number, creates a Connect task with the issue summary, and tells the customer a specialist will email them within one business day
---
### How the Code Works
#### The product FAQ knowledge base
```python
# knowledge_base.py
PRODUCT_FAQ = """
Pinnacle Gear Co. — Product FAQ
RETURNS & REFUNDS
- We accept returns within 30 days of purchase ...
SHIPPING
- Standard shipping (5–7 business days): free on orders over $75 ...
WARRANTY
- All Pinnacle Gear products carry a 1-year limited warranty ...
...
"""
```
The knowledge base lives in a sibling `knowledge_base.py` file as a single multi-line string. Keeping it in its own module makes it easy to swap in a longer corpus, edit copy without touching the agent code, or load from a file at startup. There's no chunking or indexing required — `DocumentQA` handles all of that.
#### Wiring up the agent
```python
from knowledge_base import PRODUCT_FAQ
document_qa = DocumentQA(documents=PRODUCT_FAQ, namespace="pinnacle-gear-product-support")
agent = Agent(
name="Jordan",
organization="Pinnacle Gear Co.",
purpose=(
"to help customers with product questions, returns, shipping, "
"and warranty inquiries"
),
)
```
`Agent` is the top-level handle for the AI persona. `DocumentQA` with no `store` argument runs in **server mode** — your documents are uploaded to the Guava server and searched there, so you don't need to set up GCP credentials or a vector store yourself. The `namespace` parameter scopes the upload to this agent so it doesn't collide with documents from other `DocumentQA` instances in the same account.
`DocumentQA` is content-addressed: if `PRODUCT_FAQ` hasn't changed since the last run, nothing is re-uploaded — startup is instant after the first launch.
#### Accepting inbound calls
```python
agent.inbound_phone(os.environ["GUAVA_AGENT_NUMBER"]).run()
```
`inbound_phone` opens a persistent WebSocket to the Guava server and waits for calls. Each time a call arrives on Jordan's number — whether dialed directly or transferred from the Amazon Connect contact flow — the agent's registered handlers run on a fresh `Call` object that represents that conversation.
#### Kicking off the conversation
```python
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.set_task(
"intake",
objective="Help the customer with their Pinnacle Gear question. ...",
checklist=[
guava.Say("Thank you for calling Pinnacle Gear. My name is Jordan. ..."),
guava.Field(key="customer_name", ...),
guava.Field(key="issue_summary", ...),
],
)
```
`on_call_start` runs as soon as the call connects. We use it to set the first task — a named intake step Jordan works through, greeting the caller, taking their name, and capturing what they need in their own words. The `issue_summary` field's description tells Jordan to *try to resolve the question first* using the knowledge base, and only escalate if she can't — so simple FAQ questions get answered without ever entering an escalation flow.
#### Answering questions with a knowledge base
```python
@agent.on_question
def on_question(call: guava.Call, question: str) -> str:
"""Answer product questions from the knowledge base in real time."""
return document_qa.ask(question)
```
Whenever a caller asks something Jordan can't answer from context alone — *"What's your return policy?"*, *"Is this jacket machine washable?"*, *"Do you ship overnight?"* — Guava invokes `on_question` with the question in natural language. `DocumentQA.ask` retrieves the most relevant chunks from the FAQ and generates an accurate answer. Jordan speaks the answer back and continues the conversation without any perceivable delay.
This decorator is what gives Jordan her FAQ superpowers: she'll never make up a return policy. If the FAQ doesn't cover the question, the answer will reflect that, and the customer naturally drops into the escalation path.
#### Routing after the conversation
```python
intent_recognizer = IntentRecognizer(
{
"escalation_needed": "Customer needs a return, refund, exchange, or complaint resolved, wants to speak with a manager or specialist, or has a damaged or broken item",
"resolved": "Customer's question was answered and no further action is needed",
}
)
@agent.on_task_complete("intake")
def handle_outcome(call: guava.Call) -> None:
issue = call.get_field("issue_summary", "")
if intent_recognizer.classify(issue) == "escalation_needed":
collect_escalation_details(call)
else:
call.hangup("Thank the customer for calling Pinnacle Gear. ...")
```
After the `intake` task finishes, the registered `@agent.on_task_complete("intake")` handler classifies the outcome using `IntentRecognizer` and routes accordingly. Using an LLM-based classifier handles natural phrasing correctly — *"the seam ripped after one trip"* maps to `escalation_needed` even without explicitly matching "broken" or "return". The recognizer is instantiated once at module level and reused across calls.
| Outcome | Example signals | Action |
|---|---|---|
| Resolved | FAQ question answered, no action needed | Wrap up and end call |
| Escalation needed | Return, refund, complaint, damaged item, manager request | Collect email + order number, create Connect task |
#### Collecting follow-up details
```python
def collect_escalation_details(call: guava.Call) -> None:
call.set_task(
"escalation",
objective="Collect the customer's contact details so a specialist can follow up.",
checklist=[
guava.Say("I'll have a specialist follow up with you directly to take care of that."),
guava.Field(key="email", ..., required=True),
guava.Field(key="order_number", ..., required=False),
],
)
```
If the issue requires escalation, Jordan starts a second task to collect the email and order number. The order number is `required=False` because not every issue is order-bound (warranty inquiries on long-owned products, general complaints), and the field description explicitly tells Jordan that *"if they don't have one, that's fine"* — so she doesn't get stuck pestering the customer for something that doesn't exist.
#### Creating a Connect task for follow-up
```python
@agent.on_task_complete("escalation")
def create_support_task(call: guava.Call) -> None:
...
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"Support Escalation — {call.get_field('customer_name', 'Customer')}"[:512],
Description=f"Customer: ...\nEmail: ...\nOrder: ...\nIssue: ..."[:4096],
Attributes={
"customer_name": call.get_field("customer_name", ""),
"email": call.get_field("email", ""),
"order_number": call.get_field("order_number", ""),
},
)
call.hangup("Let the customer know a specialist will reach out by email ...")
```
Once the escalation task completes, the `@agent.on_task_complete("escalation")` handler creates a task in Amazon Connect via `StartTaskContact`. The task's `Description` carries the full issue summary, and its `Attributes` make the customer's name, email, and order number searchable in Connect's contact search — so support agents can pick up the work in the Contact Control Panel just like any other contact, with full context.
The handler also prints the captured fields as JSON for local debugging and ends the call with a promise of email follow-up within one business day.
---
### Customization Ideas
**Use your own product documentation**
Replace `PRODUCT_FAQ` with your real product manuals, policy pages, or help center articles. `DocumentQA` handles chunking and retrieval automatically — paste in as much text as you need, or load from files at startup:
```python
faq_text = pathlib.Path("docs/product_faq.md").read_text()
document_qa = DocumentQA(documents=faq_text, namespace="my-product-faq")
```
**Combine with a live-transfer escalation path**
This example only creates async tasks. If some escalations need a live agent immediately (high-value customers, urgent complaints), add a third intent class — e.g. `live_agent` — and use `call.transfer(...)` to send those calls back to a Connect queue, like the AI Customer Service example does.
**Look up customer info before answering**
If you can identify the caller from their phone number (CRM lookup), pass their order history into the call as variables and reference it from `on_call_start`. Jordan can then say *"I see your recent order shipped on Tuesday"* without the customer needing to provide an order number.
**Add real-time inventory or order lookups**
The `@agent.on_question` decorator can call any code, not just `DocumentQA`. Inspect the question, route product-availability questions to your inventory API, route order-status questions to your OMS, and fall back to the FAQ for everything else.
**Pass context from Connect to Jordan via SIP**
For more advanced setups, Amazon Connect can transfer calls over a SIP trunk to a Guava SIP endpoint. This lets Connect pass the original Contact ID and other attributes as SIP headers, which the agent can read from the call info — and you can link the resulting escalation task back to the original call using `RelatedContactId` for full call chain reporting (see the CSAT Survey example for the same `RelatedContactId` pattern).
---
### Complete Example
#### `__main__.py`
```python
import guava
import os
import sys
import logging
import json
import pathlib
import boto3
from datetime import datetime
from guava import Agent, logging_utils
from guava.helpers.openai import IntentRecognizer
from guava.helpers.rag import DocumentQA
logger = logging.getLogger("product_support")
# Load the product FAQ from the sibling knowledge_base module.
sys.path.insert(0, str(pathlib.Path(__file__).parent))
from knowledge_base import PRODUCT_FAQ
# Initialize DocumentQA in server mode — no GCP credentials needed.
# Documents are content-addressed: unchanged FAQ text is never re-uploaded.
document_qa = DocumentQA(documents=PRODUCT_FAQ, namespace="pinnacle-gear-product-support")
connect_client = boto3.client("connect")
intent_recognizer = IntentRecognizer(
{
"escalation_needed": "Customer needs a return, refund, exchange, or complaint resolved, wants to speak with a manager or specialist, or has a damaged or broken item",
"resolved": "Customer's question was answered and no further action is needed",
}
)
agent = Agent(
name="Jordan",
organization="Pinnacle Gear Co.",
purpose=(
"to help customers with product questions, returns, shipping, "
"and warranty inquiries"
),
)
@agent.on_call_start
def on_call_start(call: guava.Call) -> None:
call.set_task(
"intake",
objective=(
"Help the customer with their Pinnacle Gear question. Use the knowledge base "
"to answer product questions accurately. If the customer needs a return, refund, "
"or to speak with a specialist, collect their details for follow-up."
),
checklist=[
guava.Say(
"Thank you for calling Pinnacle Gear. My name is Jordan. "
"I can help with product questions, returns, shipping, and warranty. "
"How can I help you today?"
),
guava.Field(
key="customer_name",
description="Ask for the customer's name.",
field_type="text",
required=True,
),
guava.Field(
key="issue_summary",
description=(
"Understand what the customer needs. Answer their question if you can "
"using the knowledge base. If you can't resolve it — return request, "
"refund, complaint, or request to speak with a specialist — note what "
"they need in detail."
),
field_type="text",
required=True,
),
],
)
@agent.on_question
def on_question(call: guava.Call, question: str) -> str:
"""Answer product questions from the knowledge base in real time."""
return document_qa.ask(question)
@agent.on_task_complete("intake")
def handle_outcome(call: guava.Call) -> None:
issue = call.get_field("issue_summary", "")
if intent_recognizer.classify(issue) == "escalation_needed":
collect_escalation_details(call)
else:
call.hangup(
"Thank the customer for calling Pinnacle Gear. Ask if there's anything "
"else you can help with. If not, wish them a great day."
)
def collect_escalation_details(call: guava.Call) -> None:
call.set_task(
"escalation",
objective="Collect the customer's contact details so a specialist can follow up.",
checklist=[
guava.Say(
"I'll have a specialist follow up with you directly to take care of that."
),
guava.Field(
key="email",
description="Ask for the customer's email address.",
field_type="text",
required=True,
),
guava.Field(
key="order_number",
description=(
"Ask for their order number if relevant to the issue. "
"If they don't have one, that's fine."
),
field_type="text",
required=False,
),
],
)
@agent.on_task_complete("escalation")
def create_support_task(call: guava.Call) -> None:
results = {
"timestamp": datetime.utcnow().isoformat() + "Z",
"agent": "Jordan",
"organization": "Pinnacle Gear Co.",
"use_case": "inbound_product_support",
"fields": {
"customer_name": call.get_field("customer_name"),
"issue_summary": call.get_field("issue_summary"),
"email": call.get_field("email"),
"order_number": call.get_field("order_number"),
},
}
print(json.dumps(results, indent=2))
logger.info("Escalation details captured.")
try:
connect_client.start_task_contact(
InstanceId=os.environ["CONNECT_INSTANCE_ID"],
ContactFlowId=os.environ["CONNECT_CONTACT_FLOW_ID"],
Name=f"Support Escalation — {call.get_field('customer_name', 'Customer')}"[:512],
Description=(
f"Customer: {call.get_field('customer_name')}\n"
f"Email: {call.get_field('email')}\n"
f"Order: {call.get_field('order_number', 'N/A')}\n"
f"Issue: {call.get_field('issue_summary')}"
)[:4096],
References={
"source": {"Value": "guava_product_support", "Type": "STRING"},
},
Attributes={
"customer_name": call.get_field("customer_name", ""),
"email": call.get_field("email", ""),
"order_number": call.get_field("order_number", ""),
},
)
logger.info("Amazon Connect support task created successfully.")
except Exception as e:
logger.error("Failed to create Amazon Connect task: %s", e)
call.hangup(
"Let the customer know a specialist will reach out by email within one business "
"day. Thank them for their patience and wish them a great day."
)
if __name__ == "__main__":
logging_utils.configure_logging()
agent.inbound_phone(os.environ["GUAVA_AGENT_NUMBER"]).run()
```
#### `knowledge_base.py`
This file contains the product FAQ document imported by the main script.
```python
PRODUCT_FAQ = """
Pinnacle Gear Co. — Product FAQ
RETURNS & REFUNDS
- We accept returns within 30 days of purchase for unused items in original packaging.
- Items showing signs of use may be returned for store credit only, at our discretion.
- To start a return, visit pinnaclegear.com/returns or call our support line.
- Refunds are processed within 5–7 business days after we receive the returned item.
- Sale items are final sale and cannot be returned or exchanged.
- Gift recipients can exchange items for equal or lesser value without a receipt.
SHIPPING
- Standard shipping (5–7 business days): free on orders over $75, otherwise $7.99.
- Expedited shipping (2–3 business days): $14.99 flat rate.
- Overnight shipping (next business day): $29.99. Orders placed before 2 PM ET ship same day.
- We ship to all 50 US states and Canada. International shipping is not yet available.
- Orders placed before 2 PM ET on business days ship the same day.
WARRANTY
- All Pinnacle Gear products carry a 1-year limited warranty against manufacturing defects.
- Our Summit Series backpacks and Trail Pro footwear carry a lifetime warranty.
- Warranty claims require proof of purchase. Contact support@pinnaclegear.com to file a claim.
- Normal wear and tear, damage from misuse, or accidental damage are not covered under warranty.
SIZING
- Apparel follows standard US sizing. See our full size guide at pinnaclegear.com/size-guide.
- Footwear runs true to size. For wide feet, we recommend sizing up by half a size.
- Backpack sizing is based on torso length, not height. Measure from your C7 vertebra to your iliac crest.
- When between sizes in apparel, size up for layering and size down for a fitted athletic look.
PRODUCT CARE
- Most Pinnacle apparel is machine washable on cold, gentle cycle. Tumble dry on low heat.
- Do not use fabric softener on moisture-wicking or DWR-coated items — it reduces performance.
- Down insulation should be washed on a delicate cycle and dried on low heat with clean tennis balls.
- Re-apply DWR water repellent treatment (such as Nikwax TX.Direct) after 10–15 wash cycles.
- Store sleeping bags loosely in a large cotton storage sack — never compressed for long periods.
- Clean tents with mild soap and cool water. Never machine wash or put a tent in the dryer.
ORDERS & ACCOUNT
- Track your order at pinnaclegear.com/track using your order number and the email on the order.
- To modify or cancel an order, contact us within 1 hour of placing it. After that, it may have shipped.
- We accept Visa, Mastercard, American Express, Discover, PayPal, and Pinnacle gift cards.
- Pinnacle Rewards members earn 1 point per dollar spent. 100 points = $5 reward credit.
- To create an account or reset your password, visit pinnaclegear.com/account.
"""
```
---
## Release Notes
What's new in Guava.
---
### July 14, 2026
Guava 0.34.0 brings phone number filtering and navigation enhancements to the dashboard, adds SIP header forwarding to SDK event handlers, and improves CLI authentication feedback.
#### New Features
- SIP headers are now included in SDK call event payloads, making them accessible from event handlers.
- The CLI authentication flow now shows clearer success and error feedback after the OAuth callback.
#### Improvements
- The Conversations view in the dashboard can now be filtered by phone number, with the filter state preserved in the URL for shareable, bookmarkable links.
- Navigating back from a conversation detail page now highlights and scrolls to the previously viewed entry in the list.
- Call detail pages now display the reason a conversation ended.
#### Bug Fixes
- Transcripts now correctly truncate at the point of an interruption, removing speech that was cut off before the caller finished speaking.
---
### July 7, 2026
Guava 0.33.0 streamlines CLI workflows with direct project targeting, establishes `agent.roleplay()` as the canonical testing method name, and adds automated, voice-based "Do Not Call" detection and flagging for outbound campaigns.
#### New Features
- `guava deploy` and `guava update` now accept a `project_id` argument directly. The previous `task_id` parameter has been removed. See the [CLI Reference](/docs/cli-reference).
- `agent.roleplay()` is now the canonical method name for running simulated test calls, replacing `agent.test_roleplay()`. The previous name continues to work as an alias. See [Agent Testing](/docs/agent-testing).
- Voice-based Do Not Call (DNC) detection is now available for outbound campaigns. Callers who verbally opt out are automatically flagged, and a corresponding SDK event is emitted.
---
### June 30, 2026
Guava 0.32.0 adds outbound campaign support to the TypeScript SDK, refines outbound voicemail detection, and introduces filtering by status for campaign conversations.
#### New Features
- The [`attach_campaign`](/docs/campaign) method is now available in the TypeScript SDK, bringing parity with the Python SDK for campaign-based agent workflows.
- Campaign conversations can now be filtered by status in the dashboard.
#### Improvements
- Voicemail detection on outbound calls has been improved, driving greater accuracy of campaign statistics.
#### Bug Fixes
- Fixed `attach_campaign` in the Python SDK not exiting cleanly on Ctrl-C.
- Fixed datetime fields in the `CallAttempt` API response not being serialized correctly.
---
### June 24, 2026
Guava 0.31.0 adds DTMF (keypress tones) support to the TypeScript SDK, introduces datetime filtering for campaign calling attempts, and enables bundling of documentation directly into new projects.
#### New Features
- [`on_dtmf`](/docs/on-dtmf) is now supported in the TypeScript SDK, enabling agents to handle caller keypresses in TypeScript projects.
- `guava create` now downloads the Guava documentation bundle into new projects, giving immediate access to SDK reference material.
- Campaign attempts can now be filtered by a datetime range, making it easier to query attempt history for specific time windows.
#### Bug Fixes
- Fixed the `guava login` command holding TCP ports open if the OAuth callback fails.
---
### June 16, 2026
Guava 0.30.0 adds a new chat widget supporting audio and text, inbound SMS support, in-CLI management of outbound campaigns, Do Not Call list checks for outbound campaigns, and an updated intent recognizer.
#### New Features
- A new multimodal widget (`guava-widget-audio-chat`) supports audio and text chat within a single session.
- Agents can now send DTMF digits during a call using `call.set_agent_dtmf(enabled=True)`.
- [`on_session_end`](/docs/on-session-end) handlers now receive a `termination_reason` field describing why the session ended, available in both the Python and TypeScript SDKs.
- [`GET /v1/conversations`](/docs/conversations-api) now accepts phone-number query parameters to filter results by caller or callee.
- Reach-person detection has been updated to v2 with improved accuracy.
- Agents can read incoming messages via a new inbox API endpoint and the `next_sms` (Python) / `nextSms` (TypeScript) [SDK methods](/docs/messaging).
- `Agent.chat` mode in the TypeScript SDK enables text-based (non-voice) conversation sessions.
- [`MockCall`](/docs/agent-testing) and per-handler unit test support have been added to the TypeScript SDK, allowing agent handlers to be tested in isolation.
- SDK agents now attach to an existing [campaign](/docs/campaign) via `campaign_code`. Create campaigns through the API or dashboard before starting an agent.
- Do Not Call (DNC) list support has been added to campaigns; numbers on the list are automatically skipped when dialing.
- Contacts API v2 adds expanded filtering and batch management capabilities.
- A new [`IntentRecognizer`](/docs/intent-helpers) class in `guava.helpers.llm` uses Guava's LLM endpoint for intent recognition.
- OpenAI-compatible wrappers have been added for [document QA](/docs/document-qa) and [vector store](/docs/vector-stores) workflows. VertexAI helpers have been renamed to GenAI helpers (`guava.helpers.genai`).
- New CLI subcommands: `guava contact upload`, `guava conversations`, and `guava campaigns`.
- `guava login` now accepts a `--no-launch-browser` flag for headless and CI environments.
- CLI configuration is now stored as a plain TOML file, making it easy to inspect and edit by hand.
- `guava deploy` now includes a dashboard view showing the status of active deployments.
- Campaigns can now be created and edited directly from the dashboard.
#### Improvements
- Updated `guava create` project templates. See the [CLI Reference](/docs/cli-reference).
- Outbound dialing and SMS compliance forms have been updated with bug fixes and improved field syncing.
- A `skipDeprecationCheck` option has been added to the TypeScript SDK client constructor.
---
### June 9, 2026
Guava 0.29.0 introduces text-based chat sessions, an agent testing framework, CLI self-upgrade, and TypeScript SDK Transport v2.
#### New Features
- Agents can now conduct text-based chat sessions in addition to voice calls.
- An initial [agent testing framework](/docs/agent-testing) has been added to the Python SDK, including `guava.testing.MockCall` for mocking call interactions.
- The `guava` CLI now supports self-upgrade via `guava self-upgrade`, updating the binary in place. See the [CLI Reference](/docs/cli-reference).
- The TypeScript SDK has been updated to Transport v2, with a rewritten socket layer, updated event types, and improved inbound call handling.
- The TypeScript SDK now supports CLI-based authentication, removing the need to pass API keys explicitly when the `guava` CLI is in use.
- The LLM helper (`guava.helpers.llm`) in the Python SDK now authenticates via CLI credentials.
- Added [outbound scheduling](/docs/outbound-scheduling) examples to the Python SDK with `--local` flag support.
#### Improvements
- Phone numbers are now displayed and formatted correctly during `guava create` flows.
- Improved error handling when agent code throws exceptions during execution.
- Improved call screener resilience against transient errors in both the Python and TypeScript SDKs.
#### Bug Fixes
- Fixed `guava deploy up` incorrectly defaulting to an inbound deployment when run on an existing project without a `.guava` configuration file.
---
### June 2, 2026
Guava 0.28.0 brings smarter intent handling, automated SMS follow-up for unanswered campaign calls, and CLI improvements.
#### New Features
- Agents now handle ambiguous user intents more robustly. A new [intent helper](/docs/intent-helpers) method returns a list of plausible matches, and the [`on_action_request`](/docs/on-action-request-execute) callback accepts this list to naturally disambiguate with the caller.
- [Agentic campaigns](/docs/agentic-tenacity) now automatically send an SMS follow-up when a call goes unanswered, informing the recipient of the attempt to reach out.
- `guava run` now accepts additional arguments to pass through to the running agent. See the [CLI Reference](/docs/cli-reference).
- The TypeScript SDK now supports local calling.
#### Improvements
- The [WebRTC Helper](/docs/webrtc-widgets) has been updated to v0.2.0, fixing slow bot audio and Bluetooth headset connection issues.
- The API and Python SDK now warn when attempting to stop a [campaign](/docs/campaign) that has already dispatched calls.
#### Bug Fixes
- Fixed a crash triggered by multiple action requests or questions said at once.
- Fixed a bug where admin users were unable to delete deployments from the dashboard.
- Fixed an issue where inbound calls could be routed incorrectly.
---
### May 27, 2026
WebRTC support arrives in the TypeScript SDK, agentic tenacity comes to campaigns with SMS, and CLI messaging is refined.
#### New Features
- The TypeScript SDK now includes [WebRTC](/docs/webrtc-widgets) support, with an updated `property-insurance` example to get started.
- Python SDK examples now open an interactive phone number picker when run in an interactive terminal session.
- The `guava deploy` command now provides clearer, more informative output messages.
- [Agentic tenacity](/docs/agentic-tenacity) is now available for campaigns with SMS enabled.
#### Bug Fixes & Improvements
- Updated the [quickstart guide](/docs/quickstart) with separate install method sections and added agent test and stop steps.
- The docs section now has its own dedicated navigation bar.
- Various website fixes and content updates.
---
### May 19, 2026
Guava introduces new and improved tools for measuring outbound calling campaign performance.
#### New Features
- A new **Campaign Stats Endpoint** enables querying of call outcome statistics, with support for filtering by multiple statuses. See the [Campaign](/docs/campaign) reference for details.
- A **PowerShell install script** has been added for Windows [CLI](/docs/cli-reference) installation.
#### Bug Fixes & Improvements
- Voicemail detection accuracy is improved. "Voicemail" as a call termination reason is now reported by agents and tracked in autodialer campaigns, yielding better campaign outcomes data. See [`set_voicemail_action()`](/docs/set-voicemail-action) for related configuration.
- The process for approving outbound calling and SMS agent workflows has been streamlined. Read more about requesting outbound permissions [here](/docs/outbound-and-sms-permissions).
- Various refinements to ASR (speech recognition), TTS (text-to-speech), and background noise handling.
---
### May 12, 2026
The Guava CLI makes gains in utility and flexibility. TTS pronunciation is improved.
#### New Features
- `guava create` and `guava update` now support non-interactive mode, making it easier for scripts, CI pipelines, and agents to run commands. See the [CLI Reference](/docs/cli-reference).
- Added `guava numbers list` to list phone numbers from the [CLI](/docs/cli-reference).
- Added `guava run` to run your agent project locally. See the [CLI Reference](/docs/cli-reference).
- The Guava CLI is now available as a Windows binary. See the [CLI Reference](/docs/cli-reference).
- Added [`get_var` / `set_var`](/docs/get-set-variable) as shorter aliases for `get_variable` / `set_variable` in the Guava Agent API.
- `call_info` is now accessible directly on the `call` object.
- The Python SDK can now authenticate using CLI credentials.
#### Bug Fixes & Improvements
- For spelling back words (e.g. "I have that as 'Guava, spelled G-U-A-V-A'"), TTS pronunciation and rate of speech are improved.
---
### May 5, 2026
The Guava Agent API gains voice configuration, DTMF event support, and call ID access. Campaigns now support custom caller IDs for pre-approved accounts.
#### New Features
- Added a `voice` parameter to the [Agent](/docs/agent) class.
- Exposed `call.id` for use in [agent](/docs/agent) code.
- Added support for DTMF events in the Guava Agent API.
- Pre-approved accounts can set their own number as the caller ID for outbound calls. See the [Campaign](/docs/campaign) reference.
- `guava deploy` can now use `.env` files to mount secrets. See the [Deployment](/docs/deployment) guide.
- One login can now access multiple orgs.
#### Bug Fixes & Improvements
- Increased robustness of ASR background noise rejection and short utterance handling.
- Various ease-of-use updates to the [Guava CLI](/docs/cli-reference).
---
### April 29, 2026
The Guava SIP Trunk goes live, bringing inbound SIP calling support. Agent capabilities and campaign management see significant additions.
#### New Features
- The **Guava SIP Trunk** is now live, enabling agents to receive inbound calls over SIP. See the [SIP Integration](/docs/sip-integrations) guide.
- Voicemail behavior is now configurable via [`set_voicemail_action()`](/docs/set-voicemail-action).
- The `guava widget` CLI command generates embed codes for [WebRTC-based voice widget](/docs/webrtc-widgets) integrations.
- `agent.on_escalate` enables agents to hand off calls to another destination. See [`transfer()`](/docs/transfer) for related functionality.
- [`set_language_mode()`](/docs/set-language-mode) has been added to allow language configuration.
- The [Campaigns API](/docs/campaign) now supports streamlined outbound campaign creation and modification.
---