> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with assistants

An assistant is a stored config: the prompt, the voice, the models, the tools. Everything else (every call, every campaign, every transcript) hangs off one. This page is the map: how the lifecycle runs, what you can change at call time, and where the details live.

## The lifecycle

```mermaid theme={null}
flowchart LR
  C["1 · Create<br/>build from a brief,<br/>or hand-write"] --> T["2 · Test<br/>simulate, then<br/>call it yourself"]
  T --> P["3 · Put it on calls<br/>web · phone ·<br/>campaigns · widget"]
  P --> M["4 · Measure<br/>scorecards grade every call ·<br/>webhooks feed your system"]
  M --> I["5 · Iterate<br/>models shift, edge cases surface<br/>portal · update · refine"]
  I --> T
```

1. **Create.** The recommended path is to [build from a brief](/voice-agents/assistants/build-refine-simulate): describe the call, and we write the Urdu prompt and test it against tough callers before you ever dial. Prefer to hand-write? Read [Voice prompting](/voice-agents/assistants/voice-prompting) first, take the [Recommended stack](/voice-agents/assistants/recommended-stack), and [create the assistant](/api-reference/assistants/create-an-assistant).
2. **Test.** [Simulate](/api-reference/authoring-an-assistant/rehearse-a-call-against-a-persona) your own worst callers in text — no call placed, no customer risked. Then make a [web call](/voice-agents/getting-started/quickstart-web) yourself, and a [phone call](/voice-agents/getting-started/quickstart-phone) to your own number. A test call from the portal runs your **draft**, so you hear an edit before any caller does.
3. **Put it on calls.** One assistant serves every channel: [web sessions](/api-reference/starting-a-conversation/create-a-web-session-token), [outbound dials](/api-reference/starting-a-conversation/dispatch-a-call-from-this-assistant), [campaigns](/voice-agents/campaigns/getting-started) that dial a whole list, and the [widget](/voice-agents/frontend/widget) straight on your site.
4. **Measure.** Give it a [scorecard](/voice-agents/assistants/scorecards) and every call comes back graded. Read calls on the [session detail](/api-reference/sessions-%26-call-records/get-a-calls-transcript-and-outcomes), and wire [webhooks](/voice-agents/webhooks/overview) to push grades, conversions, and callbacks into your own system as they land — alert on a bad call the moment it ends, not a day later.
5. **Iterate.** A voice agent is never one-and-done: a model upgrade shifts behavior, and real callers keep finding edge cases the prompt never covered. Quick tweaks and test calls are easiest in the [portal](https://upliftai.org/app/calling): edit, talk to it, repeat. Over the API, most changes are a direct [update](/api-reference/assistants/update-an-assistant). Updates replace the config rather than merge it, so send the whole object back. Once you've published, an update changes only the **draft** until you publish again — see [Draft and publish](/voice-agents/assistants/versions). For a real rework of what the agent says, [refine](/voice-agents/assistants/build-refine-simulate#refine-vs-edit).

## When to reach for a campaign

An assistant is the caller. A [campaign](/voice-agents/campaigns/getting-started) points it at a whole contact list and handles the rest: dialing, retries, calling windows, aggregated results. Dial [one call at a time](/api-reference/starting-a-conversation/dispatch-a-call-from-this-assistant) if your own system decides who to call and when. Reach for a campaign when the job is a list, or when you want the post-call analysis that comes with one.

## Change it at call time

The stored config is the default, not a cage. Three ways to specialize it without touching the assistant:

* **Per call**: [`additionalInstructions`](/voice-agents/personalization/per-call-instructions) and [`variables`](/voice-agents/personalization/variables) on the dial — each customer gets their own facts.
* **Per session**: send the whole config inline with a [transient assistant](/voice-agents/assistants/transient-vs-stored) — nothing stored at all.
* **Mid-call, on web**: the browser can [update instructions and tools](/voice-agents/tools/client-tools) while the conversation runs — the agent adapts to what the user is doing on the page. Good if you're running a second, bigger brain to process and direct the conversation.

## Greeting and sound

Three settings on the assistant config. I recommend turning all three on for every phone deployment:

* **`initialGreeting: true`** makes the agent speak first. On inbound and web, the moment the caller is connected. On outbound, the moment the callee picks up and the line goes quiet. `greetingInstructions` steers that first line: "Say salam, and confirm you are talking to the person named in the caller record." On campaigns the model takes the name from the caller record. On an API dial, send the name in [`variables`](/voice-agents/personalization/variables). [Voice prompting](/voice-agents/assistants/voice-prompting#the-anatomy) covers how the greeting sits in the prompt.
* **`backgroundNoise: { "enabled": true }`** plays room tone, and a typing sound while the agent is thinking, so a pause never sounds like a dropped line.
* **`noiseCancellation: { "enabled": true }`** cleans the caller's audio before it reaches speech-to-text, so a noisy line does not confuse the agent.

## Give it tools

Tools are where assistants stop being talkers and start doing things:

* [Client tools](/voice-agents/tools/client-tools): the agent calls functions in the user's browser — it can drive your UI while they talk. Also an easy way to hand us data without building any APIs: just turn what the app already has access to into tools.
* [Webhook tools](/voice-agents/tools/webhook-tools): the agent calls your APIs mid-conversation — order status, account balance, anything you serve.
* [System tools](/voice-agents/concepts/tools-overview): built-ins like calendar booking, address validation, and ending the call.