PALs

Creates a PAL and configures how it behaves in CVI for every conversation that uses that PAL.

post/v2/pals

Request

  • Base URL
    https://tavusapi.com
  • URL
    https://tavusapi.com/v2/pals
  • Auth
    API key in header x-api-key

Request body

pal_namestring

A name for the PAL.

system_promptstring

This is the system prompt that will be used by the llm. Required unless using echo mode.

greetingstring

Optional opening line the PAL speaks at the start of every conversation. When empty, the PAL stays silent unless dynamic_greeting is true.

dynamic_greetingboolean

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.

pipeline_mode'full' | 'echo'

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.

default_face_idstring

Required. The default face associated with this PAL. Also required when layers.conferencing is set - see Google Meet / Zoom / Teams.

languagesstring[]

The languages every conversation with this PAL is expected to run in, from the 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.

document_idsstring[]

Array of document IDs that the PAL will have access to. The document_ids are returned in the response of the Get Document and the Create Document endpoints.

document_tagsstring[]

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 endpoint. As soon as one document has the tag, you will be able to pass the tags in this parameter..

objectives_idstring

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 endpoint.

guardrail_idsstring[]

Array of guardrail IDs enforced during this PAL's conversations. Up to 50 per PAL. Guardrail IDs are returned by Create Guardrails and Get Guardrails.

guardrail_tagsstring[]

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.

guardrails_idstring

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.

disclosure_type'always' | 'auto' | 'off'

Controls the AI disclosure the PAL delivers at the start of a conversation. See 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 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."
verbal_disclosurestring

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."

visual_disclosurestring

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 request

{
  "pal_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "greeting": "Hey there! What can I help you with today?",
  "default_face_id": "rc9cff32ceba",
  "languages": [
    "en",
    "es"
  ],
  "document_ids": [
    "d1234567890",
    "d2468101214"
  ],
  "document_tags": [
    "product_info",
    "company_policies"
  ],
  "objectives_id": "o12345",
  "guardrail_ids": [
    "g1234567890ab",
    "g0987654321cd"
  ],
  "guardrail_tags": [
    "compliance",
    "healthcare"
  ],
  "guardrails_id": "g12345",
  "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",
      "callouts": "on",
      "emotion_recognition": "auto",
      "perception_analysis_queries": [
        "Which error messages appeared on the shared screen?"
      ],
      "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"
              ]
            }
          }
        }
      ],
      "screen_awareness_queries": [
        "What error message is visible on the shared screen?"
      ],
      "screen_tool_prompt": "Call notify_screen_error when an error dialog appears on the shared screen.",
      "audio_awareness_queries": [
        "Does the user sound frustrated or confused?",
        "Is the user speaking quickly as if in a hurry?"
      ],
      "audio_tool_prompt": "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": "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": {
      "stt_engine": "tavus-auto",
      "hotwords": "Roey is the name of the person you're speaking with."
    },
    "conversational_flow": {
      "turn_detection_model": "sparrow-2",
      "turn_taking_patience": "medium",
      "pal_interruptibility": "medium",
      "voice_isolation": "near",
      "wake_phrase": "Hey Charlie",
      "sleep_phrase": "Thanks Charlie",
      "idle_engagement": "off"
    },
    "llm": {
      "base_url": "your-base-url",
      "api_key": "your-api-key",
      "speculative_inference": true,
      "tools": [
        {
          "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": {
        "Authorization": "Bearer your-api-key"
      },
      "extra_body": {
        "temperature": 0.7,
        "top_p": 0.9
      }
    },
    "tts": {
      "api_key": "your-api-key",
      "voice_id": "v0a1b2c3d4e5f",
      "external_voice_id": "external-voice-id",
      "voice_settings": {
        "speed": 0.5,
        "emotion": [
          "positivity:high",
          "curiosity"
        ]
      },
      "tts_model_name": "sonic-3",
      "pronunciation_dictionary_id": "pd_abc123def456"
    },
    "conferencing": {
      "username": "acme-anna",
      "allowlist": [
        "alex@acme.com",
        ".*@acme\\.com"
      ]
    },
    "mcp": {
      "connectors": [
        "c8-58ea0f6420b2"
      ],
      "connector_tools": {
        "c8-58ea0f6420b2": [
          "search_messages",
          "list_channels"
        ]
      },
      "prompt": "Use search_jobs to find jobs and get_job for details; always filter jobs by the technician's name.",
      "spoken_updates": "all",
      "visual_updates": "all"
    }
  }
}

Response

pal_idstring

A unique identifier for the PAL.

pal_namestring

The name of the PAL.

conferencing_emailstring nullable

The PAL's invitable meeting email on tavusinvite.com, derived from layers.conferencing.username. Present when conferencing is configured. See Google Meet / Zoom / Teams.

created_atstring

The date and time the PAL was created.

Example response

{
  "pal_id": "pcb7a34da5fe",
  "pal_name": "Life Coach",
  "conferencing_email": "acme-anna@tavusinvite.com"
}

Changes

    • breaking

      removed the enum value sparrow-0 of the request property //

    • warning

      removed the request property //

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property /

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request property // deprecated

    • info

      request property // deprecated

    • info

      request property // deprecated

    • info

      request property // deprecated

    • info

      added the new raven-2 enum value to the request property //

    • info

      added the new sparrow-2 enum value to the request property //