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

# Objectives

> Objectives are goal-oriented instructions to define the desired outcomes and flow of your conversations.

Objectives work alongside your system prompt to provide a structured, flexible approach to guide conversations. They provide the most value during purposeful conversations that need to be tailored to specific processes, customer journeys, or workflows, while maintaining engaging and natural interactions.

For example, if you're creating a lead qualification PAL for sales, you can set objectives to gather contact information, understand budget requirements, and assess decision-making authority before scheduling a follow-up meeting.

<Note>
  You can create objectives with the [Create Objectives](/api-reference/objectives/create-objectives) API, or build them in [PAL Maker](https://maker.tavus.io). Charlie can walk you through it there.
</Note>

<Tip>
  For a deep dive on best practices for structuring objectives and guardrails, see the [Objectives and Guardrails Prompting Guide](/sections/onboarding-guide/objectives).
</Tip>

When designing your objectives, it's helpful to keep a few things in mind:

* Plan your entire ideal workflow. This will help create a robust branching structure that successfully takes the participant from start to finish.
* Think through the possible answers a participant might give, and ensure the workflow covers these cases.
* Ensure your PAL's system prompt does not conflict with the objectives. For example, a system prompt, "You are a tutor," would not perform well with the objectives workflow of a sales associate.

## Attaching objectives to a PAL

To attach objectives to a PAL, you can either:

* Add them during [PAL creation](/api-reference/pals/create-pal) like this:

```sh theme={null}
curl --request POST \
  --url https://tavusapi.com/v2/pals/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "system_prompt": "You are a lead qualification assistant.",
    "objectives_id": "o12345"
  }'
```

OR

* Add them by [editing the PAL](/api-reference/pals/patch-pal) like this:

```sh theme={null}
curl --request PATCH \
  --url https://tavusapi.com/v2/pals/{pal_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '[
    {"op": "add", "path": "/objectives_id", "value": "o12345"}
  ]'
```

<Note>
  For the best results, try creating unique objectives for different conversation purposes or business outcomes.

  For example, a customer onboarding PAL might use objectives focused on data collection, while a support PAL might use objectives focused on issue resolution.
</Note>

## Overriding objectives per conversation

Pass `objectives_id` on [Create Conversation](/api-reference/conversations/create-conversation) to use a different set of objectives for a single call. The conversation-level `objectives_id` replaces the PAL's objectives for that conversation without modifying the PAL.

Use this to reuse one PAL across different workflows without editing the PAL between calls. For example, run the same support PAL through an intake objectives set for new tickets and a follow-up objectives set for returning callers.

```sh theme={null}
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "pal_id": "pcb7a34da5fe",
    "face_id": "rc9cff32ceba",
    "objectives_id": "o12345"
  }'
```

## Parameters

### `objective_name`

A desciptive name for the objective.

Example: `"check_patient_status"`

<Note>
  This must be a string value without spaces.
</Note>

### `objective_prompt`

A text prompt that explains what the goals of this objective are. The more detail you can provide, the better.

Example: `"Ask the patient if they are new or are returning."`

### `confirmation_mode`

Whether the LLM or the participant confirms that the objective is complete.

Allowed values:

* `"auto"` (default) - the LLM decides when the objective is complete
* `"manual"` - the platform sends `conversation.objective.pending`; the participant confirms with `conversation.objective.confirm` (and can review collected values for accuracy)

### `output_variables` (optional)

This is a list of string variables that should be collected as a result of the objective being successfully completed.

Example: `["patient_status", "patient_group"]`

### `modality`

Whether this objective is completed from the participant's spoken responses or from what Raven sees.

Allowed values:

* `"verbal"` (default) - completed from the participant's verbal responses
* `"visual"` - completed only from visual / perception cues Raven observes

Each objective is either verbal or visual (not both). Different objectives in the same set can use different modalities.

### `next_conditional_objectives`

This represents a mapping of objectives (identified by `objective_name`), to conditions that must be satisfied for that objective to be triggered after the completion of the current objective.

<Warning>
  `next_conditional_objectives` and `next_required_objective` are mutually exclusive - you can use one or the other on a given objective, but not both.
</Warning>

Example:

```json theme={null}
{
  "new_patient_intake_process": "If the patient has never been to the practice before",
  "existing_patient_intake_process": "If the patient has been to the practice before"
}
```

### `next_required_objective`

The name of the next required objective (identified by `objective_name`) that will be activated once the current objective is completed. Use this to define a single next objective without conditions.

<Warning>
  `next_required_objective` and `next_conditional_objectives` are mutually exclusive - you can use one or the other on a given objective, but not both.
</Warning>

Example: `"get_patient_name"`

### `callback_url` (optional)

A URL that you can send notifications to when a particular objective has been completed.

Example: `"https://your-server.com/objectives-webhook"`

When completed, the callback payload includes the `conversation_id`, the name of the objective, and any collected output variables:

```json theme={null}
{
  "conversation_id": "<conversation_id>",
  "objective_name": "<objective_name>",
  "output_variables": {
    "<variable_name>": "<value>"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.