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.
| Status | Meaning |
|---|---|
| trying | Eligible for dispatch |
| completed | Call finished successfully |
| partially_completed | Call connected but not all tasks done |
| failed | Permanent error or max attempts exhausted |
| do_not_call | Contact has asked not to be called |
| 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 |
- 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.
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`.
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 - 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 ``` 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 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 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." ``` - 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 `Product Support`.
What's new in Guava.
--- ## May 5, 2026 ## Headline / Summary The Guava Agent API gains direct voice configuration, DTMF event support, and call ID access. Campaigns now support custom caller IDs for pre-approved accounts. ## New Features **Guava Agent API** - Added `voice` parameter to the Agent class — voice can now be set directly on the agent. - Exposed `call.id` for use in agent code. - Added support for DTMF events. **Campaigns** - Pre-approved accounts can set their own number as the caller ID for outbound calls. **CLI** - `guava deploy` can now use `.env` files to mount secrets. - One login can now access multiple orgs. ## Improvements - Increased robustness of ASR background noise rejection and short utterance handling. - Various ease-of-use updates to Guava CLI. --- ## April 29, 2026 The **public SIP gateway** is live. Guava agents can receive and place calls over SIP. **Voicemail detection** for Guava agents is configurable and testable. *Outbound agents, of course!* **WebRTC** is supported in the **Guava CLI** **Agent / Call API** receives **expanded and refined capabilities**, including: - **escalation support**: the supervisor can escalate calls - simpler **language mode** setting for agents **Campaigns API** has streamlined **outbound campaign creation and modification** **one-time passwords (OTPs)** replace magic links for login/authentication. ---