Create Chat Agent

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const chatAgentResponse = await client.chatAgent.create({
  response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' },
});

console.log(chatAgentResponse.agent_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
chat_agent_response = client.chat_agent.create(
    response_engine={
        "llm_id": "llm_234sdertfsdsfsdf",
        "type": "retell-llm",
    },
)
print(chat_agent_response.agent_id)

curl --request POST \
  --url https://api.retellai.com/create-chat-agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "agent_name": "Jarvis",
  "version_title": "Production hotfix",
  "auto_close_message": "Thank you for chatting. The conversation has ended.",
  "end_chat_after_silence_ms": 3600000,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "webhook_events": [],
  "webhook_timeout_ms": 10000,
  "contact_memory_config": {
    "enable_update": true,
    "enable_read": true
  },
  "data_storage_setting": "everything",
  "data_storage_retention_days": 30,
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 86400000,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ],
      "required": true,
      "conditional_prompt": "<string>"
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "guardrail_config": {
    "output_topics": [],
    "input_topics": [
      "platform_integrity_jailbreaking"
    ]
  },
  "handbook_config": {
    "default_personality": true,
    "high_empathy": true,
    "ai_disclosure": true,
    "scope_boundaries": true
  },
  "timezone": "America/New_York",
  "pre_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ],
  "post_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/create-chat-agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'response_engine' => [
        'type' => 'retell-llm',
        'llm_id' => 'llm_234sdertfsdsfsdf',
        'version' => 0
    ],
    'agent_name' => 'Jarvis',
    'version_title' => 'Production hotfix',
    'auto_close_message' => 'Thank you for chatting. The conversation has ended.',
    'end_chat_after_silence_ms' => 3600000,
    'language' => 'en-US',
    'webhook_url' => 'https://webhook-url-here',
    'webhook_events' => [
        
    ],
    'webhook_timeout_ms' => 10000,
    'contact_memory_config' => [
        'enable_update' => true,
        'enable_read' => true
    ],
    'data_storage_setting' => 'everything',
    'data_storage_retention_days' => 30,
    'opt_in_signed_url' => true,
    'signed_url_expiration_ms' => 86400000,
    'post_chat_analysis_data' => [
        [
                'type' => 'string',
                'name' => 'customer_name',
                'description' => 'The name of the customer.',
                'examples' => [
                                'John Doe',
                                'Jane Smith'
                ],
                'required' => true,
                'conditional_prompt' => '<string>'
        ]
    ],
    'post_chat_analysis_model' => 'gpt-4.1-mini',
    'guardrail_config' => [
        'output_topics' => [
                
        ],
        'input_topics' => [
                'platform_integrity_jailbreaking'
        ]
    ],
    'handbook_config' => [
        'default_personality' => true,
        'high_empathy' => true,
        'ai_disclosure' => true,
        'scope_boundaries' => true
    ],
    'timezone' => 'America/New_York',
    'pre_session_tools' => [
        [
                'type' => 'integration_app',
                'name' => '<string>',
                'app_id' => '<string>',
                'provider' => '<string>',
                'app_tool_template_name' => '<string>',
                'parameters' => [
                                [
                                                                'type' => 'object',
                                                                'properties' => [
                                                                                                                                
                                                                ],
                                                                'required' => [
                                                                                                                                '<string>'
                                                                ]
                                ]
                ],
                'response_variables' => [
                                'contact_first_name' => 'data.first_name'
                ],
                'output_selection' => [
                                'mode' => 'all',
                                'fields' => [
                                                                '<string>'
                                ]
                ],
                'description' => '<string>',
                'speak_during_execution' => true,
                'speak_after_execution' => true,
                'execution_message_description' => '<string>',
                'enable_typing_sound' => true,
                'depends_on' => [
                                '<string>'
                ]
        ]
    ],
    'post_session_tools' => [
        [
                'type' => 'integration_app',
                'name' => '<string>',
                'app_id' => '<string>',
                'provider' => '<string>',
                'app_tool_template_name' => '<string>',
                'parameters' => [
                                [
                                                                'type' => 'object',
                                                                'properties' => [
                                                                                                                                
                                                                ],
                                                                'required' => [
                                                                                                                                '<string>'
                                                                ]
                                ]
                ],
                'response_variables' => [
                                'contact_first_name' => 'data.first_name'
                ],
                'output_selection' => [
                                'mode' => 'all',
                                'fields' => [
                                                                '<string>'
                                ]
                ],
                'description' => '<string>',
                'speak_during_execution' => true,
                'speak_after_execution' => true,
                'execution_message_description' => '<string>',
                'enable_typing_sound' => true,
                'depends_on' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/create-chat-agent"

	payload := strings.NewReader("{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.retellai.com/create-chat-agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/create-chat-agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "last_modification_timestamp": 1703413636133,
  "version": 0,
  "base_version": 12,
  "assigned_tags": [
    "<string>"
  ],
  "is_published": false,
  "agent_name": "Jarvis",
  "version_title": "Production hotfix",
  "auto_close_message": "Thank you for chatting. The conversation has ended.",
  "end_chat_after_silence_ms": 3600000,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "webhook_events": [
    "chat_started"
  ],
  "webhook_timeout_ms": 10000,
  "contact_memory_config": {
    "enable_update": true,
    "enable_read": true
  },
  "data_storage_setting": "everything",
  "data_storage_retention_days": 30,
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 86400000,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ],
      "required": true,
      "conditional_prompt": "<string>"
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "pii_config": {
    "mode": "post_call",
    "categories": []
  },
  "guardrail_config": {
    "output_topics": [
      "harassment"
    ],
    "input_topics": [
      "platform_integrity_jailbreaking"
    ]
  },
  "handbook_config": {
    "default_personality": true,
    "high_empathy": true,
    "ai_disclosure": true,
    "scope_boundaries": true
  },
  "timezone": "America/New_York",
  "pre_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "execution_message_type": "prompt",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ],
  "post_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "execution_message_type": "prompt",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ],
      "condition": {
        "type": "equation",
        "equations": [
          {
            "left": "<string>",
            "operator": "==",
            "right": "<string>"
          }
        ],
        "operator": "||"
      }
    }
  ]
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

POST

create-chat-agent

JavaScript

import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const chatAgentResponse = await client.chatAgent.create({
  response_engine: { llm_id: 'llm_234sdertfsdsfsdf', type: 'retell-llm' },
});

console.log(chatAgentResponse.agent_id);

import os
from retell import Retell

client = Retell(
    api_key=os.environ.get("RETELL_API_KEY"),  # This is the default and can be omitted
)
chat_agent_response = client.chat_agent.create(
    response_engine={
        "llm_id": "llm_234sdertfsdsfsdf",
        "type": "retell-llm",
    },
)
print(chat_agent_response.agent_id)

curl --request POST \
  --url https://api.retellai.com/create-chat-agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "agent_name": "Jarvis",
  "version_title": "Production hotfix",
  "auto_close_message": "Thank you for chatting. The conversation has ended.",
  "end_chat_after_silence_ms": 3600000,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "webhook_events": [],
  "webhook_timeout_ms": 10000,
  "contact_memory_config": {
    "enable_update": true,
    "enable_read": true
  },
  "data_storage_setting": "everything",
  "data_storage_retention_days": 30,
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 86400000,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ],
      "required": true,
      "conditional_prompt": "<string>"
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "guardrail_config": {
    "output_topics": [],
    "input_topics": [
      "platform_integrity_jailbreaking"
    ]
  },
  "handbook_config": {
    "default_personality": true,
    "high_empathy": true,
    "ai_disclosure": true,
    "scope_boundaries": true
  },
  "timezone": "America/New_York",
  "pre_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ],
  "post_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ]
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.retellai.com/create-chat-agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'response_engine' => [
        'type' => 'retell-llm',
        'llm_id' => 'llm_234sdertfsdsfsdf',
        'version' => 0
    ],
    'agent_name' => 'Jarvis',
    'version_title' => 'Production hotfix',
    'auto_close_message' => 'Thank you for chatting. The conversation has ended.',
    'end_chat_after_silence_ms' => 3600000,
    'language' => 'en-US',
    'webhook_url' => 'https://webhook-url-here',
    'webhook_events' => [
        
    ],
    'webhook_timeout_ms' => 10000,
    'contact_memory_config' => [
        'enable_update' => true,
        'enable_read' => true
    ],
    'data_storage_setting' => 'everything',
    'data_storage_retention_days' => 30,
    'opt_in_signed_url' => true,
    'signed_url_expiration_ms' => 86400000,
    'post_chat_analysis_data' => [
        [
                'type' => 'string',
                'name' => 'customer_name',
                'description' => 'The name of the customer.',
                'examples' => [
                                'John Doe',
                                'Jane Smith'
                ],
                'required' => true,
                'conditional_prompt' => '<string>'
        ]
    ],
    'post_chat_analysis_model' => 'gpt-4.1-mini',
    'guardrail_config' => [
        'output_topics' => [
                
        ],
        'input_topics' => [
                'platform_integrity_jailbreaking'
        ]
    ],
    'handbook_config' => [
        'default_personality' => true,
        'high_empathy' => true,
        'ai_disclosure' => true,
        'scope_boundaries' => true
    ],
    'timezone' => 'America/New_York',
    'pre_session_tools' => [
        [
                'type' => 'integration_app',
                'name' => '<string>',
                'app_id' => '<string>',
                'provider' => '<string>',
                'app_tool_template_name' => '<string>',
                'parameters' => [
                                [
                                                                'type' => 'object',
                                                                'properties' => [
                                                                                                                                
                                                                ],
                                                                'required' => [
                                                                                                                                '<string>'
                                                                ]
                                ]
                ],
                'response_variables' => [
                                'contact_first_name' => 'data.first_name'
                ],
                'output_selection' => [
                                'mode' => 'all',
                                'fields' => [
                                                                '<string>'
                                ]
                ],
                'description' => '<string>',
                'speak_during_execution' => true,
                'speak_after_execution' => true,
                'execution_message_description' => '<string>',
                'enable_typing_sound' => true,
                'depends_on' => [
                                '<string>'
                ]
        ]
    ],
    'post_session_tools' => [
        [
                'type' => 'integration_app',
                'name' => '<string>',
                'app_id' => '<string>',
                'provider' => '<string>',
                'app_tool_template_name' => '<string>',
                'parameters' => [
                                [
                                                                'type' => 'object',
                                                                'properties' => [
                                                                                                                                
                                                                ],
                                                                'required' => [
                                                                                                                                '<string>'
                                                                ]
                                ]
                ],
                'response_variables' => [
                                'contact_first_name' => 'data.first_name'
                ],
                'output_selection' => [
                                'mode' => 'all',
                                'fields' => [
                                                                '<string>'
                                ]
                ],
                'description' => '<string>',
                'speak_during_execution' => true,
                'speak_after_execution' => true,
                'execution_message_description' => '<string>',
                'enable_typing_sound' => true,
                'depends_on' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.retellai.com/create-chat-agent"

	payload := strings.NewReader("{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.retellai.com/create-chat-agent")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.retellai.com/create-chat-agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"response_engine\": {\n    \"type\": \"retell-llm\",\n    \"llm_id\": \"llm_234sdertfsdsfsdf\",\n    \"version\": 0\n  },\n  \"agent_name\": \"Jarvis\",\n  \"version_title\": \"Production hotfix\",\n  \"auto_close_message\": \"Thank you for chatting. The conversation has ended.\",\n  \"end_chat_after_silence_ms\": 3600000,\n  \"language\": \"en-US\",\n  \"webhook_url\": \"https://webhook-url-here\",\n  \"webhook_events\": [],\n  \"webhook_timeout_ms\": 10000,\n  \"contact_memory_config\": {\n    \"enable_update\": true,\n    \"enable_read\": true\n  },\n  \"data_storage_setting\": \"everything\",\n  \"data_storage_retention_days\": 30,\n  \"opt_in_signed_url\": true,\n  \"signed_url_expiration_ms\": 86400000,\n  \"post_chat_analysis_data\": [\n    {\n      \"type\": \"string\",\n      \"name\": \"customer_name\",\n      \"description\": \"The name of the customer.\",\n      \"examples\": [\n        \"John Doe\",\n        \"Jane Smith\"\n      ],\n      \"required\": true,\n      \"conditional_prompt\": \"<string>\"\n    }\n  ],\n  \"post_chat_analysis_model\": \"gpt-4.1-mini\",\n  \"guardrail_config\": {\n    \"output_topics\": [],\n    \"input_topics\": [\n      \"platform_integrity_jailbreaking\"\n    ]\n  },\n  \"handbook_config\": {\n    \"default_personality\": true,\n    \"high_empathy\": true,\n    \"ai_disclosure\": true,\n    \"scope_boundaries\": true\n  },\n  \"timezone\": \"America/New_York\",\n  \"pre_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"post_session_tools\": [\n    {\n      \"type\": \"integration_app\",\n      \"name\": \"<string>\",\n      \"app_id\": \"<string>\",\n      \"provider\": \"<string>\",\n      \"app_tool_template_name\": \"<string>\",\n      \"parameters\": [\n        {\n          \"type\": \"object\",\n          \"properties\": {},\n          \"required\": [\n            \"<string>\"\n          ]\n        }\n      ],\n      \"response_variables\": {\n        \"contact_first_name\": \"data.first_name\"\n      },\n      \"output_selection\": {\n        \"mode\": \"all\",\n        \"fields\": [\n          \"<string>\"\n        ]\n      },\n      \"description\": \"<string>\",\n      \"speak_during_execution\": true,\n      \"speak_after_execution\": true,\n      \"execution_message_description\": \"<string>\",\n      \"enable_typing_sound\": true,\n      \"depends_on\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "response_engine": {
    "type": "retell-llm",
    "llm_id": "llm_234sdertfsdsfsdf",
    "version": 0
  },
  "last_modification_timestamp": 1703413636133,
  "version": 0,
  "base_version": 12,
  "assigned_tags": [
    "<string>"
  ],
  "is_published": false,
  "agent_name": "Jarvis",
  "version_title": "Production hotfix",
  "auto_close_message": "Thank you for chatting. The conversation has ended.",
  "end_chat_after_silence_ms": 3600000,
  "language": "en-US",
  "webhook_url": "https://webhook-url-here",
  "webhook_events": [
    "chat_started"
  ],
  "webhook_timeout_ms": 10000,
  "contact_memory_config": {
    "enable_update": true,
    "enable_read": true
  },
  "data_storage_setting": "everything",
  "data_storage_retention_days": 30,
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 86400000,
  "post_chat_analysis_data": [
    {
      "type": "string",
      "name": "customer_name",
      "description": "The name of the customer.",
      "examples": [
        "John Doe",
        "Jane Smith"
      ],
      "required": true,
      "conditional_prompt": "<string>"
    }
  ],
  "post_chat_analysis_model": "gpt-4.1-mini",
  "pii_config": {
    "mode": "post_call",
    "categories": []
  },
  "guardrail_config": {
    "output_topics": [
      "harassment"
    ],
    "input_topics": [
      "platform_integrity_jailbreaking"
    ]
  },
  "handbook_config": {
    "default_personality": true,
    "high_empathy": true,
    "ai_disclosure": true,
    "scope_boundaries": true
  },
  "timezone": "America/New_York",
  "pre_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "execution_message_type": "prompt",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ]
    }
  ],
  "post_session_tools": [
    {
      "type": "integration_app",
      "name": "<string>",
      "app_id": "<string>",
      "provider": "<string>",
      "app_tool_template_name": "<string>",
      "parameters": [
        {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        }
      ],
      "response_variables": {
        "contact_first_name": "data.first_name"
      },
      "output_selection": {
        "mode": "all",
        "fields": [
          "<string>"
        ]
      },
      "description": "<string>",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "execution_message_description": "<string>",
      "execution_message_type": "prompt",
      "enable_typing_sound": true,
      "depends_on": [
        "<string>"
      ],
      "condition": {
        "type": "equation",
        "equations": [
          {
            "left": "<string>",
            "operator": "==",
            "right": "<string>"
          }
        ],
        "operator": "||"
      }
    }
  ]
}

{
  "status": "error",
  "message": "Invalid request format, please check API reference."
}

{
  "status": "error",
  "message": "API key is missing or invalid."
}

{
  "status": "error",
  "message": "Trial has ended, please add payment method."
}

{
  "status": "error",
  "message": "An unexpected server error occurred."
}

Authorizations

Authorization

string

header

required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json

response_engine

object

required

The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.

Option 1
Option 2
Option 3

Show child attributes

Example:

{
  "type": "retell-llm",
  "llm_id": "llm_234sdertfsdsfsdf",
  "version": 0
}

agent_name

string | null

The name of the chat agent. Only used for your own reference.

Example:

"Jarvis"

version_title

string | null

Optional title of the chat agent version. Used for your own reference.

Example:

"Production hotfix"

auto_close_message

string | null

Message to display when the chat is automatically closed.

Example:

"Thank you for chatting. The conversation has ended."

end_chat_after_silence_ms

integer | null

If users stay silent for a period after agent speech, end the chat. The minimum value allowed is 120,000 ms (2 minutes). The maximum value allowed is 259,200,000 ms (72 hours). By default, this is set to 3,600,000 (1 hour).

Example:

3600000

language

Specifies what language(s) the agent will operate in. Accepts either a single locale (e.g. en-US) or an array of locales for multilingual agents (e.g. ["en-US","es-ES"]). The scalar value multi is deprecated but still accepted as a scalar, and is stored and returned as the ten locales it used to mean. It must not appear inside the array form. Send an explicit locale array instead. If unset, defaults to en-US.

Available options:

en-US,

en-IN,

en-GB,

en-AU,

en-NZ,

de-DE,

es-ES,

es-419,

hi-IN,

fr-FR,

fr-CA,

ja-JP,

pt-PT,

pt-BR,

zh-CN,

ru-RU,

it-IT,

ko-KR,

nl-NL,

nl-BE,

pl-PL,

tr-TR,

vi-VN,

ro-RO,

bg-BG,

ca-ES,

th-TH,

da-DK,

fi-FI,

el-GR,

hu-HU,

id-ID,

no-NO,

sk-SK,

sv-SE,

lt-LT,

lv-LV,

cs-CZ,

ms-MY,

af-ZA,

ar-SA,

az-AZ,

bs-BA,

cy-GB,

fa-IR,

fil-PH,

gl-ES,

he-IL,

hr-HR,

hy-AM,

is-IS,

kk-KZ,

kn-IN,

mk-MK,

mr-IN,

ne-NP,

sl-SI,

sr-RS,

sw-KE,

ta-IN,

ur-IN,

yue-CN,

uk-UA

Example:

"en-US"

webhook_url

string | null

The webhook for agent to listen to chat events. See what events it would get at webhook doc. If set, will binds webhook events for this agent to the specified url, and will ignore the account level webhook for this agent. Set to null to remove webhook url from this agent.

Example:

"https://webhook-url-here"

webhook_events

enum<string>[] | null

Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed.

Available options:

chat_started,

chat_ended,

chat_analyzed,

transcript_updated

webhook_timeout_ms

integer

The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.

Example:

10000

contact_memory_config

object

Contact memory settings for phone calls and SMS chats. Creating an agent defaults enable_update to false and enable_read to true. Updates only change the supplied flags; omitted flags stay unchanged and an empty object has no effect. Set a flag to false to disable it. The configuration cannot be cleared. Existing agents without this configuration have both disabled.

Show child attributes

data_storage_setting

enum<string> | null

Controls what data is stored for this agent. "everything" stores all data including transcripts and recordings. "everything_except_pii" stores data but excludes PII when possible based on PII configuration. "basic_attributes_only" stores only basic metadata. If not set, defaults to "everything".

Available options:

everything,

everything_except_pii,

basic_attributes_only

Example:

"everything"

data_storage_retention_days

integer | null

Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion).

Required range: 1 <= x <= 730

Example:

30

opt_in_signed_url

boolean

Whether this agent opts in to signed url for public log. If not set, default value of false will apply.

Example:

true

signed_url_expiration_ms

integer | null

The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply.

Example:

86400000

post_chat_analysis_data

object[] | null

Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends.

Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment).

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

post_chat_analysis_model

enum<string> | null

The model to use for post chat analysis. Default to gpt-5.6-terra.

Available options:

gpt-4.1,

gpt-4.1-mini,

gpt-4.1-nano,

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-5.1,

gpt-5.2,

gpt-5.4,

gpt-5.4-mini,

gpt-5.4-nano,

gpt-5.5,

gpt-5.6-terra,

gpt-5.6-luna,

gpt-6-astra,

gpt-6-sol,

gpt-6.1-sol,

gpt-6-luna,

claude-4.5-sonnet,

claude-4.6-sonnet,

claude-5-opus,

claude-5.5-opus,

claude-5-sonnet,

claude-5.5-sonnet,

claude-4.5-haiku,

gemini-3.0-flash,

gemini-3.1-flash-lite,

gemini-3.5-flash,

gemini-3.5-flash-lite,

gemini-3.6-flash,

gemini-3.7-flash,

gemini-3.8-flash,

null

Example:

"gpt-4.1-mini"

pii_config

object

Configuration for PII scrubbing from transcripts and recordings.

Show child attributes

guardrail_config

object

Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input.

Show child attributes

handbook_config

object

Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents.

Show child attributes

timezone

string | null

IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set.

Example:

"America/New_York"

pre_session_tools

object[] | null

Integration (Agent Functions) tools run as a dependency graph before the chat's first message. Outputs are injected as dynamic variables. Set to null to clear.

Maximum array length: 15

A pre-session tool (app / custom / code, discriminated by type) plus its dependency edges. The tool's name is the depends_on handle and must be unique across the agent's session tools. Parameters may set a constant value or a description for the LLM to infer the value. Pre-session inference uses the agent prompt and dynamic variables.

Option 1
Option 2
Option 3

Show child attributes

post_session_tools

object[] | null

Integration (Agent Functions) tools run as a dependency graph at chat end, after post-chat analysis. Each tool can be gated by a condition. Set to null to clear.

Maximum array length: 15

A post-session tool with an optional condition. Parameter inference uses the agent prompt, dynamic variables, and conversation. Same tools as PreSessionTool plus send_sms, which is only supported on phone calls — the session is over, so the speak settings are ignored and an inferred sms_content is written by the LLM from the transcript at teardown.

Option 1
Option 2
Option 3
Option 4

Show child attributes

Response

Successfully created a new chat agent.

agent_id

string

required

Unique id of chat agent.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

response_engine

object

required

The Response Engine to attach to the agent. It is used to generate responses for the agent. You need to create a Response Engine first before attaching it to an agent.

Option 1
Option 2
Option 3

Show child attributes

Example:

{
  "type": "retell-llm",
  "llm_id": "llm_234sdertfsdsfsdf",
  "version": 0
}

last_modification_timestamp

integer

required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example:

1703413636133

version

integer

The version of the chat agent.

Example:

0

base_version

integer | null

Version that this draft was based on. Null for initial versions.

Example:

12

assigned_tags

string[]

Tags assigned to this chat agent version. Preferred tag is listed first.

is_published

boolean

Whether the chat agent is published.

Example:

false

agent_name

string | null

The name of the chat agent. Only used for your own reference.

Example:

"Jarvis"

version_title

string | null

Optional title of the chat agent version. Used for your own reference.

Example:

"Production hotfix"

auto_close_message

string | null

Message to display when the chat is automatically closed.

Example:

"Thank you for chatting. The conversation has ended."

end_chat_after_silence_ms

integer | null

Example:

3600000

language

Available options:

en-US,

en-IN,

en-GB,

en-AU,

en-NZ,

de-DE,

es-ES,

es-419,

hi-IN,

fr-FR,

fr-CA,

ja-JP,

pt-PT,

pt-BR,

zh-CN,

ru-RU,

it-IT,

ko-KR,

nl-NL,

nl-BE,

pl-PL,

tr-TR,

vi-VN,

ro-RO,

bg-BG,

ca-ES,

th-TH,

da-DK,

fi-FI,

el-GR,

hu-HU,

id-ID,

no-NO,

sk-SK,

sv-SE,

lt-LT,

lv-LV,

cs-CZ,

ms-MY,

af-ZA,

ar-SA,

az-AZ,

bs-BA,

cy-GB,

fa-IR,

fil-PH,

gl-ES,

he-IL,

hr-HR,

hy-AM,

is-IS,

kk-KZ,

kn-IN,

mk-MK,

mr-IN,

ne-NP,

sl-SI,

sr-RS,

sw-KE,

ta-IN,

ur-IN,

yue-CN,

uk-UA

Example:

"en-US"

webhook_url

string | null

Example:

"https://webhook-url-here"

webhook_events

enum<string>[] | null

Which webhook events this agent should receive. If not set, defaults to chat_started, chat_ended, chat_analyzed.

Available options:

chat_started,

chat_ended,

chat_analyzed,

transcript_updated

webhook_timeout_ms

integer

The timeout for the webhook in milliseconds. If not set, default value of 10000 will apply.

Example:

10000

contact_memory_config

object

Show child attributes

data_storage_setting

enum<string> | null

Available options:

everything,

everything_except_pii,

basic_attributes_only

Example:

"everything"

data_storage_retention_days

integer | null

Number of days to retain call/chat data before automatic deletion. Must be between 1 and 730 days. If not set, data is retained forever (no automatic deletion).

Required range: 1 <= x <= 730

Example:

30

opt_in_signed_url

boolean

Whether this agent opts in to signed url for public log. If not set, default value of false will apply.

Example:

true

signed_url_expiration_ms

integer | null

The expiration time for the signed url in milliseconds. Only applicable when opt_in_signed_url is true. If not set, default value of 86400000 (24 hours) will apply.

Example:

86400000

post_chat_analysis_data

object[] | null

Post chat analysis data to extract from the chat. This data will augment the pre-defined variables extracted in the chat analysis. This will be available after the chat ends.

Post-chat analysis item (custom data or chat preset). Use for chat agent post_chat_analysis_data; validates only chat presets (chat_summary, chat_successful, user_sentiment).

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

post_chat_analysis_model

enum<string> | null

The model to use for post chat analysis. Default to gpt-5.6-terra.

Available options:

gpt-4.1,

gpt-4.1-mini,

gpt-4.1-nano,

gpt-5,

gpt-5-mini,

gpt-5-nano,

gpt-5.1,

gpt-5.2,

gpt-5.4,

gpt-5.4-mini,

gpt-5.4-nano,

gpt-5.5,

gpt-5.6-terra,

gpt-5.6-luna,

gpt-6-astra,

gpt-6-sol,

gpt-6.1-sol,

gpt-6-luna,

claude-4.5-sonnet,

claude-4.6-sonnet,

claude-5-opus,

claude-5.5-opus,

claude-5-sonnet,

claude-5.5-sonnet,

claude-4.5-haiku,

gemini-3.0-flash,

gemini-3.1-flash-lite,

gemini-3.5-flash,

gemini-3.5-flash-lite,

gemini-3.6-flash,

gemini-3.7-flash,

gemini-3.8-flash,

null

Example:

"gpt-4.1-mini"

pii_config

object

Configuration for PII scrubbing from transcripts and recordings.

Show child attributes

guardrail_config

object

Configuration for guardrail checks to detect and prevent prohibited topics in agent output and user input.

Show child attributes

handbook_config

object

Toggle behavior presets on/off to influence agent response style and behaviors. Voice-only presets are not available for chat agents.

Show child attributes

timezone

string | null

IANA timezone for the agent (e.g. America/New_York). Defaults to America/Los_Angeles if not set.

Example:

"America/New_York"

pre_session_tools

object[] | null

Integration (Agent Functions) tools run as a dependency graph before the chat's first message. Outputs are injected as dynamic variables. Set to null to clear.

Maximum array length: 15

Option 1
Option 2
Option 3

Show child attributes

post_session_tools

object[] | null

Integration (Agent Functions) tools run as a dependency graph at chat end, after post-chat analysis. Each tool can be gated by a condition. Set to null to clear.

Maximum array length: 15

Option 1
Option 2
Option 3
Option 4

Show child attributes

⌘I

Call

Chat

Playground

Phone Number

Voice Agent

Chat Agent

Retell LLM Response Engine (for single / multi prompt agent)

Conversation Flow Response Engine (for conversation flow agent)

Conversation Flow Subflows

MCP Tool

Knowledge Base

Voice

Batch call

Contact

App

CRM

Test Case Definitions

Batch Tests

Test Runs

Account

Custom Telephony

Custom LLM

Authorizations

Body

Response