## Outbound Campaigns

While you can use `agent.call_phone("+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.get_variable()`.

## Write your agent

Define an `Agent` and attach callbacks for each stage of the call.

```python
import guava
from guava import Agent, Field

agent = Agent(
    name="Sarah",
    organization="Valley Dental",
    purpose="Remind patients about their upcoming dental appointments.",
)

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.reach_person(
        contact_full_name=call.get_variable("patient_name"),
    )

@agent.on_reach_person
def on_reach_person(call: guava.Call, outcome: str):
    if outcome == "available":
        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()

@agent.on_task_complete("confirm_appointment")
def on_confirmed(call: guava.Call):
    call.hangup("Thank them and end the call.")
```

## Test your agent

Before attaching to a campaign, test your agent using `agent.call_local()` or `agent.chat()`. Pass a `variables` dict to simulate per-contact data:

```python
agent.chat(variables={
    "patient_name": "Jane Smith",
    "appointment_date": "Monday, June 23rd",
    "appointment_time": "2:00 PM",
})
```

## Attach and serve the campaign

Next, run `agent.attach_campaign("gcmp-...")`. This "attaches" your agent to the Campaign that we previously created.

```python
agent.attach_campaign(campaign_code="gcmp-...")
```

## Review calls in the dashboard

Once your campaign is running, visit the [Campaigns](https://app.goguava.ai/dashboard/campaigns) page to monitor progress.

Questions? [hi@goguava.ai](mailto:hi@goguava.ai)

Guava is an API for building natural and reliable voice agents. All of our docs can be downloaded in plain-text form.