v1

latestOpenAPI 3.0.32026-07-267015229.9 KB

PALs

Create PAL

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

default_face_id is required on POST /v2/pals (unlike the legacy POST /v2/personas path, where default_replica_id was optional).

Legacy: /v2/personas and persona_id / default_replica_id remain supported as aliases.

post/v2/pals

Request body

pal_namestring

A name for the PAL.

system_promptstring

This is the system prompt that will be used by the llm. Each request must have a system_prompt value unless you're using echo mode.

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. When creating a conversation, a pal_id with a default_face_id can be used without specifying a separate face_id. Also required when layers.conferencing is set - see Google Meet.

document_idsstring[]

Array of document IDs that the PAL will have 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 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.

Example request

{
  "pal_name": "Life Coach",
  "system_prompt": "As a Life Coach, you are a dedicated professional who specializes in...",
  "default_face_id": "r90bbd427f71",
  "document_ids": [
    "d1234567890",
    "d2468101214"
  ],
  "document_tags": [
    "product_info",
    "company_policies"
  ],
  "objectives_id": "o12345",
  "guardrail_ids": [
    "g1234567890ab",
    "g0987654321cd"
  ],
  "guardrail_tags": [
    "compliance",
    "healthcare"
  ],
  "guardrails_id": "g12345",
  "layers": {
    "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?",
        "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-1",
      "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",
      "external_voice_id": "external-voice-id",
      "voice_settings": {
        "speed": 0.5,
        "emotion": [
          "positivity:high",
          "curiosity"
        ]
      },
      "tts_emotion_control": true,
      "tts_model_name": "sonic-3",
      "pronunciation_dictionary_id": "pd_abc123def456"
    },
    "conferencing": {
      "username": "acme-anna",
      "allowlist": [
        "alex@acme.com",
        ".*@acme\\.com"
      ]
    }
  }
}

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.

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