PALs

Returns a single PAL by its unique identifier.

get/v2/pals/{pal_id}

Request

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

Response

pal_idstring

A unique identifier for the PAL.

pal_namestring

A name for the PAL.

system_promptstring

The system prompt that will be used by the llm.

greetingstring

Opening line the PAL speaks at the start of every conversation. Empty means silent unless dynamic_greeting is true.

dynamic_greetingboolean

When true, conversations that omit dynamic_greeting generate an opener from this PAL if it has no greeting. A conversation can still send custom_greeting or dynamic_greeting: true.

default_face_idstring

The default face_id associated with this PAL if one exists.

conferencing_emailstring nullable

The PAL's invitable meeting email on tavusinvite.com, derived from layers.conferencing.username. Present when conferencing is configured.

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

AI disclosure setting for EU AI Act compliance. always, auto (default, follows the conversation's policy param), or off.

verbal_disclosurestring

Text the PAL speaks before its greeting when disclosure_type fires. Empty falls back to "Just a note, I am an AI system, not a person."

visual_disclosurestring

Text shown as an on-screen banner when disclosure_type fires. Empty falls back to "You are interacting with an AI system."

document_idsstring[]

Array of document IDs that the PAL has access to. These documents will be available to the PAL in all their conversations. 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 has access to. Documents matching these tags will be available to the PAL in all their conversations.

created_atstring

The date and time the PAL was created.

updated_atstring

The date and time of when the PAL was last updated.

Example response

{
  "pal_id": "pcb7a34da5fe",
  "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",
  "conferencing_email": "acme-anna@tavusinvite.com",
  "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.",
  "document_ids": [
    "d1234567890",
    "d2468101214"
  ],
  "document_tags": [
    "product_info",
    "company_policies"
  ],
  "layers": {
    "llm": {
      "base_url": "your-base-url",
      "api_key": "your-api-key",
      "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"
    },
    "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": "This is a hotword example"
    },
    "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": "outcome",
      "visual_updates": "outcome"
    }
  }
}

Changes

    • warning

      deleted the query request parameter source

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      added the new raven-2 enum value to the // response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      response property layers/perception/audio_tool_prompt deprecated

    • info

      response property layers/perception/audio_tools deprecated

    • info

      response property layers/perception/visual_tool_prompt deprecated

    • info

      response property layers/perception/visual_tools deprecated