REretellai

POST /v3/create-web-call

Changed on

Create a new web call and return browser connection details.

Request

  • Base URL
    https://api.retellai.com
  • Auth
    HTTP bearer

Request body

agent_idstring required

Unique id of agent used for the call. Your agent would contain the LLM Websocket url used for this call.

metadataobject

An arbitrary object for storage purpose only. You can put anything here like your internal customer id associated with the call. Not used for processing. You can later get this field from the call object.

retell_llm_dynamic_variablesobject

Add optional dynamic variables in key value pairs of string that injects into your Response Engine prompt and tool description. Only applicable for Response Engine.

current_node_idstring nullable

Start the call at this conversation flow node (stage). Must be a valid node id in the agent's conversation flow. Only applicable when the agent uses conversation flow as the response engine. Ignored for retell-llm agents.

current_statestring nullable

Start the conversation in this state (stage). Must be a valid state name in the agent's Retell LLM. Only applicable when the agent uses Retell LLM with states. Ignored for conversation-flow agents.

Example request

{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "agent_version": "latest_published",
  "agent_override": {
    "agent": {
      "agent_name": "Jarvis",
      "version_description": "Customer support agent for handling product inquiries",
      "version_title": "Production hotfix",
      "voice_id": "retell-Cimo",
      "fallback_voice_ids": [
        "cartesia-Cimo",
        "minimax-Cimo"
      ],
      "voice_temperature": 1,
      "voice_speed": 1,
      "enable_dynamic_voice_speed": true,
      "enable_dynamic_responsiveness": true,
      "volume": 1,
      "enable_expressive_mode": true,
      "expressive_emotion_tags": [
        "empathetic",
        "excited",
        "sigh",
        "clear throat",
        "emphasis"
      ],
      "expressive_mode_prompt": "Use [sigh] for thoughtful pauses and [excited] for good news.",
      "responsiveness": 1,
      "interruption_sensitivity": 1,
      "enable_backchannel": true,
      "backchannel_frequency": 0.9,
      "backchannel_words": [
        "yeah",
        "uh-huh"
      ],
      "reminder_trigger_ms": 10000,
      "reminder_max_count": 2,
      "ambient_sound_volume": 1,
      "language": "en-US",
      "webhook_url": "https://webhook-url-here",
      "webhook_timeout_ms": 10000,
      "boosted_keywords": [
        "retell",
        "kroger"
      ],
      "data_storage_setting": "everything",
      "data_storage_retention_days": 30,
      "opt_in_signed_url": true,
      "signed_url_expiration_ms": 86400000,
      "pronunciation_dictionary": [
        {
          "word": "actually",
          "alphabet": "ipa",
          "phoneme": "ˈæktʃuəli"
        }
      ],
      "end_call_after_silence_ms": 600000,
      "max_call_duration_ms": 3600000,
      "voicemail_option": {
        "action": {
          "type": "static_text",
          "text": "Please give us a callback tomorrow at 10am."
        }
      },
      "ivr_option": {
        "action": {
          "type": "hangup"
        }
      },
      "call_screening_option": {
        "agent_identity": "Acme Health scheduling team",
        "call_purpose": "confirming your appointment for tomorrow"
      },
      "post_call_analysis_data": [
        {
          "type": "string",
          "name": "customer_name",
          "description": "The name of the customer.",
          "examples": [
            "John Doe",
            "Jane Smith"
          ]
        }
      ],
      "begin_message_delay_ms": 1000,
      "ring_duration_ms": 30000,
      "stt_mode": "fast",
      "vocab_specialization": "general",
      "allow_user_dtmf": true,
      "user_dtmf_options": {
        "termination_key": "#"
      },
      "denoising_mode": "noise-cancellation",
      "denoising_enhancement_level": 0.8,
      "timezone": "America/New_York",
      "pre_session_tools": [
        {
          "response_variables": {
            "contact_first_name": "data.first_name"
          },
          "output_selection": {
            "fields": [
              "id",
              "properties.email"
            ]
          }
        }
      ],
      "post_session_tools": [
        {
          "response_variables": {
            "contact_first_name": "data.first_name"
          },
          "output_selection": {
            "fields": [
              "id",
              "properties.email"
            ]
          }
        }
      ]
    },
    "retell_llm": {
      "model_high_priority": true,
      "model_ultrafast": true,
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "begin_after_user_silence_ms": 2000,
      "begin_message": "Hey I am a virtual assistant calling from Retell Hospital."
    },
    "conversation_flow": {
      "model_temperature": 0.7,
      "knowledge_base_ids": [
        "kb_001",
        "kb_002"
      ],
      "kb_config": {
        "top_k": 3,
        "filter_score": 0.6
      },
      "start_speaker": "agent",
      "begin_after_user_silence_ms": 2000
    }
  },
  "retell_llm_dynamic_variables": {
    "customer_name": "John Doe"
  },
  "current_node_id": "collect_info",
  "current_state": "information_collection"
}

Response

Successfully created a web call.

call_idstring required

Unique identifier for the web call.

access_tokenstring required

Token authorizing this browser to join the web call. Pass it to your frontend.

transport'gateway' required

Connection transport to select in the web client.

expires_atinteger required

Unix epoch ms when the access_token expires.

Example response

{
  "call_id": "call_Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ2aWRlbyI6eyJyb29tSm9p",
  "expires_at": 1735689600000
}

Changes

  • de3a1d542da5Revision changes
    • warning

      removed the request property ///////

    • warning

      removed the request property ///////

  • 5d018ad1bc4dRevision changes
    • info

      added to the // request property anyOf list

    • info

      added to the // request property anyOf list