> ## 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.
# Create PAL
> Creates a PAL and configures how it behaves in CVI for every conversation that uses that PAL.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
`default_face_id` is required on `POST /v2/pals` (unlike the legacy `POST /v2/personas` path, where `default_replica_id` was optional). `/v2/personas` and `persona_id` / `default_replica_id` remain supported as aliases.
## OpenAPI
````yaml post /v2/pals
openapi: 3.0.3
info:
title: Tavus Developer API Collection
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
- name: Faces
- name: Voices
- name: Conversations
- name: Deployments
- name: PALs
- name: Tools
- name: PAL Tools
- name: Connectors
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
- name: Memory Stores
paths:
/v2/pals:
post:
tags:
- PALs
summary: Create PAL
description: >
Creates a PAL and configures how it behaves in CVI for every
conversation that uses that PAL.
operationId: createPal
requestBody:
content:
application/json:
schema:
type: object
properties:
pal_name:
type: string
description: A name for the PAL.
example: Life Coach
system_prompt:
type: string
description: >-
This is the system prompt that will be used by the llm.
**Required unless using echo mode.**
example: >-
As a Life Coach, you are a dedicated professional who
specializes in...
greeting:
type: string
description: >-
Optional opening line the PAL speaks at the start of every
conversation. When empty, the PAL stays silent unless
`dynamic_greeting` is true.
example: Hey there! What can I help you with today?
dynamic_greeting:
type: boolean
description: >
When true, conversations that omit `dynamic_greeting`
generate an opener if this PAL has no `greeting`. The line
is generated from the PAL (system prompt and context). A
conversation can still send `custom_greeting` or
`dynamic_greeting: true` — the latter generates even over
this written greeting. Default is false. Generated in the
first tag of the conversation's `properties.languages`,
otherwise this PAL's `languages`.
default: false
example: false
pipeline_mode:
type: string
description: >-
The pipeline mode to use for the PAL. Possible values:
`full`, `echo`. `full` will provide the default end-to-end
experience. `echo` will turn off most steps, and allow the
PAL to sync video with audio passed in through Echo events,
which it will speak out.
enum:
- full
- echo
default_face_id:
type: string
description: >-
**Required.** The default face associated with this PAL.
Also **required** when `layers.conferencing` is set - see
[Google Meet / Zoom /
Teams](/sections/conversational-video-interface/pal/meetings).
example: rc9cff32ceba
languages:
type: array
description: >
The languages every conversation with this PAL is expected
to run in, from the [spoken
languages](/sections/conversational-video-interface/language-support#spoken-languages)
Tavus supports. Tavus restricts speech recognition to this
set, holds the PAL's replies to it, and selects a matching
version of the voice per language where one exists.
The fewer languages you supply, the more accurate the
conversation. Only include languages the PAL is actually
expected to speak.
A conversation may override this with its own `languages` on
`properties`; the sets are not merged. A language the PAL's
TTS engine and model cannot speak is rejected rather than
ignored. See [Language
support](/sections/conversational-video-interface/language-support#setting-languages).
maxItems: 42
items:
type: string
maxLength: 16
example:
- en
- es
document_ids:
type: array
description: >-
Array of document IDs that the PAL will have access to. The
`document_ids` are returned in the response of the [Get
Document](/api-reference/documents/get-document) and the
[Create Document](/api-reference/documents/create-document)
endpoints.
items:
type: string
example:
- d1234567890
- d2468101214
document_tags:
type: array
description: >-
Array of document tags that the PAL will have access to.
Documents matching these tags will be available to the PAL
in all their conversations. The tags are passed in the
`document_tags` parameter of the [Create
Document](/api-reference/documents/create-document)
endpoint. As soon as one document has the tag, you will be
able to pass the tags in this parameter..
items:
type: string
example:
- product_info
- company_policies
objectives_id:
type: string
description: >-
The unique identifier of the objectives to attach to this
PAL. Objectives provide goal-oriented instructions that help
guide conversations toward specific outcomes. Create
objectives using the [Create
Objectives](/api-reference/objectives/create-objectives)
endpoint.
example: o12345
guardrail_ids:
type: array
maxItems: 50
description: >-
Array of guardrail IDs enforced during this PAL's
conversations. Up to 50 per PAL. Guardrail IDs are returned
by [Create
Guardrails](/api-reference/guardrails/create-guardrails) and
[Get Guardrails](/api-reference/guardrails/get-guardrails).
items:
type: string
example:
- g1234567890ab
- g0987654321cd
guardrail_tags:
type: array
maxItems: 50
description: >-
Array of guardrail tags. Any guardrail you own with a
matching tag is attached to this PAL dynamically. Up to 50
tags per PAL, and a PAL can have at most 50 guardrails
total.
items:
type: string
example:
- compliance
- healthcare
guardrails_id:
type: string
description: >-
**Deprecated.** The unique identifier of a guardrail set to
attach to this PAL. New integrations should use
`guardrail_ids` / `guardrail_tags` instead - see [Deprecated
guardrail
sets](/api-reference/guardrails/legacy-guardrail-sets).
example: g12345
disclosure_type:
type: string
description: >
Controls the AI disclosure the PAL delivers at the start of
a conversation. See [EU AI
Act](/sections/onboarding-guide/eu-ai-act) product guidance.
- `always`: the PAL speaks `verbal_disclosure` before the
greeting and shows `visual_disclosure` on screen for every
conversation.
- `auto` (default): applies the disclosure only when the
conversation's
[`policy`](/api-reference/conversations/create-conversation)
is `eu`.
- `off`: never delivers a Tavus-built-in disclosure.
When `always` or `auto` fires and `verbal_disclosure` /
`visual_disclosure` are empty, Tavus supplies these
defaults:
- `verbal_disclosure`: "Just a note, I am an AI system, not
a person."
- `visual_disclosure`: "You are interacting with an AI
system."
enum:
- always
- auto
- 'off'
default: auto
example: auto
verbal_disclosure:
type: string
description: >-
Text the PAL speaks before its greeting when
`disclosure_type` fires. When empty, Tavus falls back to
"Just a note, I am an AI system, not a person."
example: >-
Just so you know, you're speaking with an AI agent from
Acme.
visual_disclosure:
type: string
description: >-
Text shown as an on-screen banner while the PAL delivers
`verbal_disclosure`. When empty, Tavus falls back to "You
are interacting with an AI system."
example: You are speaking with an AI agent.
layers:
type: object
description: >
Optional nested settings for each CVI pipeline layer
(perception, STT, conversational flow, LLM, TTS,
conferencing). For an overview of what each layer controls,
see [PAL overview - CVI
layers](/sections/conversational-video-interface/pal/overview#cvi-layer).
properties:
perception:
type: object
properties:
perception_model:
type: string
description: >-
The perception model to use. `raven-1` (default and
recommended) provides real-time emotional
understanding from user audio, more natural and
human-like interactions, plus all visual
capabilities from raven-0. `raven-0` (legacy
settings
[here](/sections/troubleshooting#migration-from-legacy-perception-to-raven-1))
offers advanced visual perception only. `off`
disables all perception.
enum:
- raven-1
- raven-0
- 'off'
default: raven-1
example: raven-1
emotion_recognition:
type: string
description: >
Controls whether Raven-1 may infer emotion from
biometric signals (what it sees and hears - facial
expression, tone of voice). See [EU AI
Act](/sections/onboarding-guide/eu-ai-act).
- `full`: Raven-1 attaches biometric emotion
analysis to user audio and video.
- `limited`: Raven-1 is instructed not to attach any
biometric-derived emotion data.
`user_audio_analysis` and `user_visual_analysis`
tags still fire for non-emotional cues (spoken
content, objects, activity).
- `auto` (default): follows the conversation's
[`policy`](/api-reference/conversations/create-conversation)
parameter. Behaves like `limited` when `policy` is
`eu`, and like `full` otherwise.
enum:
- full
- limited
- auto
default: auto
example: auto
visual_awareness_queries:
type: array
description: >-
Custom queries that Raven continuously monitors in
the visual stream. These provide ambient visual
context without requiring explicit prompting.
items:
type: string
example:
- Is the user showing an ID card?
- Does the user appear distressed or uncomfortable?
visual_tool_prompt:
type: string
description: >-
A prompt that details how and when to use visual
tools based on what Raven sees. This helps the PAL
understand the context of the visual tools.
example: >-
You have a tool to notify the system when an ID card
is detected, named `notify_if_id_shown`. You MUST
use this tool when a form of ID is detected.
visual_tools:
type: array
description: >-
**Legacy.** Inline vision tools on the PAL (OpenAI
function shape). Deprecated - create tools with
`origin: vision` via [Create
Tool](/api-reference/tools/create-tool) and attach
to the PAL. Still supported at runtime; see [Legacy
inline tool
calling](/sections/troubleshooting#legacy-inline-tool-calling).
items:
type: object
properties:
name:
type: string
description: The name of the tool to be called.
description:
type: string
description: >-
A description of what the tool does and when
it should be called.
example:
- type: function
function:
name: notify_if_id_shown
description: >-
Use this function when a drivers license or
passport is detected in the image with high
confidence. After collecting the ID,
internally use final_ask()
parameters:
type: object
properties:
id_type:
type: string
description: best guess on what type of ID it is
required:
- id_type
audio_awareness_queries:
type: array
description: >-
Custom queries that Raven-1 continuously monitors in
the audio stream. These provide ambient audio
context such as user tone and emotional state. Only
available with `raven-1`.
items:
type: string
example:
- Does the user sound frustrated or confused?
- Is the user speaking quickly as if in a hurry?
audio_tool_prompt:
type: string
description: >-
A prompt that details how and when to use audio
tools based on what Raven-1 hears. Only available
with `raven-1`.
example: >-
You have a tool to escalate to a human agent when
the user sounds very frustrated, named
`escalate_to_human`. Use this tool when detecting
sustained frustration.
audio_tools:
type: array
description: >-
**Legacy.** Inline audio tools on the PAL (OpenAI
function shape). Deprecated - create tools with
`origin: audio` via [Create
Tool](/api-reference/tools/create-tool) and attach
to the PAL. Raven-1 only. See [Legacy inline tool
calling](/sections/troubleshooting#legacy-inline-tool-calling).
items:
type: object
properties:
name:
type: string
description: The name of the tool to be called.
description:
type: string
description: >-
A description of what the tool does and when
it should be called.
example:
- type: function
function:
name: escalate_to_human
description: >-
Escalate the conversation to a human agent
when user frustration is detected
parameters:
type: object
properties:
reason:
type: string
description: The reason for escalation
required:
- reason
stt:
type: object
description: >
**Note**: Turn-taking is now configured on the
[Conversational Flow
layer](/sections/conversational-video-interface/pal/conversational-flow).
properties:
stt_engine:
type: string
description: >-
The STT engine used for transcription. `tavus-auto`
(default, recommended) automatically selects the
best model for the conversation's language.
`tavus-soniox` is purpose-built for Indian languages
with broad multilingual coverage. `tavus-whisper`
provides broad multilingual coverage across all
supported languages. `tavus-deepgram-medical` is
domain-specific English STT optimized for clinical
and healthcare vocabulary. `tavus-parakeet` and
`tavus-advanced` are deprecated and not recommended
for new integrations. See the [STT layer
documentation](/sections/conversational-video-interface/pal/stt)
for details.
enum:
- tavus-auto
- tavus-parakeet
- tavus-soniox
- tavus-whisper
- tavus-deepgram-medical
- tavus-advanced
default: tavus-auto
example: tavus-auto
hotwords:
type: string
description: >
The hotwords parameter lets you provide example
phrases that guide the STT model to prioritize
certain words or phrases-especially names, technical
terms, or uncommon language. For instance, including
"Roey is the name of the person you're speaking
with" helps the model transcribe "Roey" correctly
instead of "Rowie."
example: Roey is the name of the person you're speaking with.
conversational_flow:
type: object
description: >-
Controls conversational flow dynamics for the PAL. When
omitted or partially configured, unspecified fields use
sensible defaults (`sparrow-1`, `medium`
patience/interruptibility, etc.). `sparrow-2` becomes
the default on September 8, 2026. See more details
[here](/sections/conversational-video-interface/pal/conversational-flow).
properties:
turn_detection_model:
type: string
description: >-
The model used for turn detection. `sparrow-1`
(default until September 8, 2026) uses tone, rhythm,
pauses, and other audio cues for natural
conversational timing. `sparrow-2` is the frontier
model, with faster responses, fewer PAL
interruptions, graceful handling of backchannels and
user interruptions, and robust turn-taking in noisy
environments. `sparrow-2` becomes the default on
September 8, 2026.
enum:
- sparrow-2
- sparrow-1
example: sparrow-2
turn_taking_patience:
type: string
description: >-
Controls how eagerly and quickly the PAL claims
conversational turns. Affects both response latency
and likelihood of interrupting during natural
pauses. `low` = eager and quick to respond, may
interrupt pauses; `medium` (default) = balanced;
`high` = patient, waits for clear turn completion.
enum:
- low
- medium
- high
example: medium
pal_interruptibility:
type: string
description: >-
Controls how sensitive the PAL is to user speech
while the PAL is talking. Determines whether the PAL
stops to listen or keeps speaking. `low` = keeps
talking, less interruptible; `medium` (default) =
balanced; `high` = stops easily, more interruptible.
enum:
- low
- medium
- high
example: medium
replica_interruptibility:
deprecated: true
type: string
description: >-
**Legacy alias** for `pal_interruptibility`. Still
accepted at runtime; existing integrations do not
need to change.
enum:
- low
- medium
- high
voice_isolation:
type: string
description: >-
Controls the voice isolation model used on
participant audio. `near` (default) separates speech
from background noise for scenarios where the user
is less than 1 meter from the microphone; `off`
sends raw audio down the conversational pipeline.
This setting is not used by `sparrow-2` and
currently affects audio processing only when using
`sparrow-1`.
enum:
- 'off'
- near
default: near
example: near
wake_phrase:
type: string
description: >-
A specific phrase the PAL listens for before
responding. When set, the PAL remains silent until
it hears the wake phrase, similar to a voice
assistant. The PAL still records all user utterances
in the transcript so it has full conversation
context when it does respond. Choose a phrase that
is unique enough to avoid over-triggering (avoid
generic greetings like `Hey`). Default is `None`
(disabled).
example: Hey Charlie
sleep_phrase:
type: string
description: >-
A specific phrase that puts the persona back to
sleep after it has been woken with the
`wake_phrase`. When the persona hears the sleep
phrase, it stops responding and returns to the
silent state, listening again for the wake phrase
before it will respond. The persona still records
all user utterances in the transcript while asleep.
Choose a phrase that is unique enough to avoid
over-triggering. Default is `None` (disabled).
example: Thanks Charlie
idle_engagement:
type: string
description: >-
Controls whether the PAL proactively re-engages the
user after a stretch of silence, and how eagerly.
`off` (default) = the PAL never breaks silence;
`patient` = re-engages after longer silences, suited
to tutors or contemplative use cases; `eager` =
re-engages after shorter silences, suited to SDR or
sales-style use cases.
enum:
- 'off'
- patient
- eager
default: 'off'
example: 'off'
llm:
type: object
properties:
model:
type: string
description: >
The model name that will be used by the LLM.
**tavus-gemma-4** is recommended as the default.
Other Tavus-hosted options include
tavus-gpt-5.6-sol, tavus-gpt-5.6-terra, and
tavus-gemini-2.5-flash. See the [LLM layer
documentation](/sections/conversational-video-interface/pal/llm)
for a full comparison.
For your own OpenAI-compatible LLM, provide a
`model`, `base_url`, and `api_key`.
**Context window:** Performance and intelligence are
best when prompts are limited to 5,000 tokens.
Degradations in speed and instruction following may
occur in the 15,000–20,000 token range. Context
limits vary by model. Tip: 1 token ≈ 4 characters.
base_url:
type: string
description: The base url for your OpenAI compatible endpoint.
example: your-base-url
api_key:
type: string
description: The API key for the OpenAI compatible endpoint.
example: your-api-key
speculative_inference:
type: boolean
description: >-
When set to `true`, the LLM begins processing speech
transcriptions before user input ends, improving
responsiveness. Default is `true`.
example: true
default: true
tools:
type: array
description: >-
**Legacy.** Inline OpenAI-style function tools on
the PAL. Deprecated - create tools via [Create
Tool](/api-reference/tools/create-tool) and attach
with [Attach Tools to
PAL](/api-reference/pal-tools/attach-tools-to-pal).
Still supported at runtime; see [Legacy inline tool
calling](/sections/troubleshooting#legacy-inline-tool-calling).
example:
- type: function
function:
name: get_current_weather
description: Get the current weather in a given location
parameters:
type: object
properties:
location:
type: string
description: >-
The city and state, e.g. San Francisco,
CA
unit:
type: string
enum:
- celsius
- fahrenheit
required:
- location
headers:
type: object
description: Optional headers to provide to your custom LLM
example:
Authorization: Bearer your-api-key
extra_body:
type: object
description: >
Optional parameters to customize the LLM request.
For Tavus-hosted models, you can pass `temperature`
and `top_p`:
- `temperature`: Controls randomness in the model's
output. Range typically 0.0 to 2.0. Lower values
make output more deterministic and focused, higher
values make it more creative and varied.
- `top_p`: Controls diversity via nucleus sampling.
Range 0.0 to 1.0. Lower values make output more
focused on high-probability tokens, higher values
allow more diverse token selection.
For custom LLMs, you can pass any parameters that
your LLM provider supports (e.g., `temperature`,
`top_p`, `frequency_penalty`, etc.).
example:
temperature: 0.7
top_p: 0.9
tts:
type: object
properties:
api_key:
type: string
description: >
The API key for the chosen TTS provider. Only
required when using private voices.
**ElevenLabs:** When using pronunciation
dictionaries with your own ElevenLabs key, the key
must have the `pronunciation_dictionaries_write`
scope (or full account access). See [ElevenLabs API
key
scopes](https://elevenlabs.io/docs/api-reference/service-accounts/api-keys/create).
**Cartesia:** No additional scope required - any
valid Cartesia API key works.
example: your-api-key
tts_engine:
type: string
description: >
The TTS engine that will be used. `tavus-auto`
automatically selects the best TTS model for each
conversation (recommended). See the [TTS layer
documentation](/sections/conversational-video-interface/pal/tts)
for details.
default: tavus-auto
enum:
- tavus-auto
- cartesia
- elevenlabs
- azure
voice_id:
type: string
description: >-
A Tavus Voice to speak with, e.g. `v0a1b2c3d4e5f`.
Tavus picks the provider that is the best fit for
the language(s) of the conversation. Mutually
exclusive with `external_voice_id`, and cannot be
combined with your own TTS `api_key`. See
[Voices](/sections/conversational-video-interface/voices).
example: v0a1b2c3d4e5f
external_voice_id:
type: string
description: >-
The voice ID used for the TTS engine when you want
to customize your face's voice. Choose from
Cartesia's stock voices by referring to their [Voice
Catalog](https://docs.cartesia.ai/api-reference/voices/list),
or if you want more options you can consider
[ElevenLabs](https://elevenlabs.io/docs/api-reference/voices/get-all).
example: external-voice-id
voice_settings:
type: object
description: >
Optional voice settings to customize TTS behavior.
For Cartesia we support inline Cartesia SSML
settings
(https://docs.cartesia.ai/build-with-cartesia/sonic-3/ssml-tags).
For ElevenLabs we support: `speed` (0.7–1.2),
`stability` (0.0–1.0), `similarity_boost` (0.0–1.0),
`style` (0.0–1.0), `use_speaker_boost` (boolean).
See [ElevenLabs Voice
Settings](https://elevenlabs.io/docs/api-reference/voices/settings/get).
example:
speed: 0.5
emotion:
- positivity:high
- curiosity
tts_model_name:
type: string
description: >-
The model name that will be used by the TTS engine.
Please double check this with the TTS provider you
are using to ensure valid model names.
example: sonic-3
pronunciation_dictionary_id:
type: string
description: >
The unique identifier of a Tavus pronunciation
dictionary to attach to this PAL. Tavus will apply
the dictionary's rules at conversation time.
Provider-specific dictionary IDs are managed
internally by Tavus and are not exposed in GET
responses - only this field is visible.
example: pd_abc123def456
conferencing:
$ref: '#/components/schemas/conferencingLayer'
mcp:
type: object
description: >-
Connects registered MCP servers to the PAL. See [MCP
Connectors](/sections/conversational-video-interface/pal/mcp-connectors).
properties:
connectors:
type: array
description: >-
Connector IDs (from [Create
Connector](/api-reference/connectors/create-connector))
the PAL can delegate background tasks to during a
conversation - the PAL discovers each server's tools
itself, so there is nothing to import. Attaching a
connector reserves the `delegate_background_task`
tool name, so a tool of your own with that name is
rejected. Up to 10 connectors.
items:
type: string
example:
- c8-58ea0f6420b2
connector_tools:
type: object
description: >-
Scopes an attached connector down to specific tools,
keyed by connector ID. A connector with no entry
here allows every tool it exposes; an empty array is
rejected. Up to 200 unique names per connector, each
1-64 characters of letters, digits, `_`, `.`, `:` or
`-`.
additionalProperties:
type: array
items:
type: string
example:
c8-58ea0f6420b2:
- search_messages
- list_channels
spoken_updates:
type: string
enum:
- none
- outcome
- all
description: >-
Which moments of a background task the PAL speaks.
`outcome` (the default) speaks the outcome once the
task finishes. `all` also voices the updates the
background agent chooses to give while it works - a
short title and a sentence, a few per task - one at
a time and only when there is room, so a fast task
voices less than it reports over
`conversation.agent_update`. `none` volunteers
nothing; the outcome still reaches the PAL's context
for when the user asks. Booleans are rejected.
default: outcome
example: all
visual_updates:
type: string
enum:
- none
- outcome
- all
description: >-
Which moments of a background task the PAL shows as
a Magic Canvas text card, when it has that skill on
a video call. `none` (the default) shows nothing.
`outcome` shows the outcome as a card once the task
finishes. `all` also shows each update the
background agent gives as it comes, replacing the
card. Independent of `spoken_updates`; inert without
Magic Canvas.
default: none
example: all
examples:
Required Parameters Only:
value:
pipeline_mode: full
system_prompt: >-
As a Life Coach, you are a dedicated professional who
specializes in...
default_face_id: rc9cff32ceba
Full Customizations:
value:
pal_name: Life Coach
system_prompt: >-
As a Life Coach, you are a dedicated professional who
specializes in...
pipeline_mode: full
default_face_id: rc9cff32ceba
layers:
llm:
model: tavus-gemma-4
speculative_inference: true
tools:
- type: function
function:
name: life_coach_insight
description: >-
Offer personalized life coaching advice or
guidance based on a user's challenge or goal.
parameters:
type: object
properties:
topic:
type: string
description: >-
The area of life or goal the user wants to
improve (e.g. career, relationships,
confidence)
urgency_level:
type: string
enum:
- low
- medium
- high
required:
- topic
tts:
voice_id: v0a1b2c3d4e5f
perception:
perception_model: raven-1
visual_awareness_queries:
- Is the user showing an ID card?
- Does the user appear distressed or uncomfortable?
visual_tool_prompt: >-
You have a tool to notify the system when an ID card is
detected, named `notify_if_id_shown`. You MUST use this
tool when a form of ID is detected.
visual_tools:
- type: function
function:
name: notify_if_id_shown
description: >-
Use this function when a drivers license or
passport is detected in the image with high
confidence. After collecting the ID, internally
use final_ask()
parameters:
type: object
properties:
id_type:
type: string
description: best guess on what type of ID it is
required:
- id_type
audio_awareness_queries:
- Does the user sound frustrated or confused?
stt:
stt_engine: tavus-auto
conversational_flow:
turn_detection_model: sparrow-2
turn_taking_patience: medium
pal_interruptibility: high
idle_engagement: 'off'
document_ids:
- d1234567890
- d2468101214
document_tags:
- product_info
- company_policies
mcp:
connectors:
- c8-58ea0f6420b2
connector_tools:
c8-58ea0f6420b2:
- search_messages
- list_channels
spoken_updates: outcome
visual_updates: all
Conferencing:
value:
pal_name: Anna
system_prompt: >-
You are Anna, a helpful meeting assistant who takes notes
and answers questions.
pipeline_mode: full
default_face_id: rc9cff32ceba
layers:
conferencing:
username: acme-anna
allowlist:
- .*@acme\.com
EU AI Act compliance:
value:
pal_name: Acme EU Agent
system_prompt: You are a helpful support agent for Acme.
pipeline_mode: full
default_face_id: rc9cff32ceba
disclosure_type: auto
verbal_disclosure: >-
Just so you know, you're speaking with an AI agent from
Acme.
visual_disclosure: You are speaking with an AI agent.
layers:
perception:
perception_model: raven-1
emotion_recognition: auto
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
pal_id:
type: string
description: A unique identifier for the PAL.
example: pcb7a34da5fe
pal_name:
type: string
description: The name of the PAL.
example: Life Coach
conferencing_email:
type: string
nullable: true
description: >-
The PAL's invitable meeting email on `tavusinvite.com`,
derived from `layers.conferencing.username`. Present when
conferencing is configured. See [Google Meet / Zoom /
Teams](/sections/conversational-video-interface/pal/meetings).
example: acme-anna@tavusinvite.com
created_at:
type: string
description: The date and time the PAL was created.
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: Invalid replica_uuid
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
security:
- apiKey: []
components:
schemas:
conferencingLayer:
type: object
description: >
[Conferencing
layer](/sections/conversational-video-interface/pal/meetings) settings.
Provisions a `@tavusinvite.com` email identity so the PAL can be invited
to calendar events with Google Meet, Zoom, or Microsoft Teams links and
join automatically. Requires `default_face_id` on the PAL.
properties:
username:
type: string
minLength: 2
description: >
Local part of the PAL's meeting email
(`@tavusinvite.com`). Stored lowercase. Must start and end
with an alphanumeric character; `.`, `_`, and `-` are allowed in
between. Usernames matching `botN` (for example `bot1`, `bot42`) are
reserved. Globally unique across `tavusinvite.com`.
example: acme-anna
allowlist:
type: array
description: >
Controls who may invite this PAL via calendar. Each entry is an
exact email address or a regex matched against the organizer's
email. Empty or omitted allows any sender.
items:
type: string
example:
- alex@acme.com
- .*@acme\.com
required:
- username
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.