AgentCreate
Payload to create an agent. config defaults to the standard agent configuration.
ID of the product (workspace) that owns this record. Most endpoints scope access by product.
Human-readable agent name.
Agent behavior mode. Defaults to outreach; use support for support-ticket processing.
Possible values: [outreach, support]
outreachWhether the agent starts active. Defaults to true.
trueconfig object
Agent behavior configuration.
Europe/MoscowPossible values: [ru, en, pt, es]
rugender object
Optional persona gender metadata included in user-facing LLM runs for human-readable wording when set.
- string
- null
Possible values: [male, female]
Strings pii-guard must pass to the model verbatim even when they look like a person's name — product or brand names, the agent's persona name. Only read when the company's pii_mode is not off.
true30message_debounce_guard_pre_cooldown_seconds object
- integer
- null
truecommunication_context_config object
Controls whether the agent receives shared context from prior communication episodes resolved to the same lead or customer.
Whether shared communication context is assembled and supplied to text and voice agents. Defaults to true.
trueWhether automatic shared-context lookup is also enabled for leads marked as test. Defaults to false.
falsetrueredirect_to_agent_id object
- integer
- null
redirect_message_source object
- MessageSource
- null
text object
- string
- null
prompt_id object
- integer
- null
prompt_version_id object
- integer
- null
prepared_message_id object
- integer
- null
waba_template_id object
- integer
- null
caption object
- string
- null
falsetruefalsePossible values: >= 0 and <= 100
25truequote_replies_probability_percent object
- integer
- null
Possible values: >= 0 and <= 100
falsedelay_messages_symbols_per_second object
- integer
- null
delay_messages_seconds object
- integer
- null
true336rag_config object
Possible values: >= 1
10Possible values: >= 1
20Possible values: >= 1
16000per_mode_limits object
lead_research_config object
falsellm_model_config object
- LLMModelConfig
- null
Possible values: [chatgpt, gemini, anthropic, grok, sber, openrouter]
0.7falsePossible values: >= 1 and <= 100
5Possible values: >= 256 and <= 20000
5000Possible values: >= 512 and <= 10000
1800truetruecurrency_rates_config object
Live exchange rates supplied to the agent so it can quote prices in the client's currency instead of inventing a rate. Rates are fetched from the selected source on a schedule and are shared platform-wide; this config only selects which pairs this agent quotes and how it should talk about them. A pair with no fetched rate available is silently omitted from the agent's context rather than guessed.
Whether the agent receives exchange rates at all. Requires at least one enabled pair.
falseWhere the rates are fetched from.
Possible values: [cbr, open_er_api]
cbrFree-text instruction shown to the agent above the rate list, applying to every pair (for example "the price list is in USD, always also state the price in rubles").
max_staleness_minutes object
Maximum age of a fetched rate, in minutes. A rate fetched longer ago than this is dropped instead of quoted. Null means any stored rate may be used.
- integer
- null
Possible values: >= 1
pairs object[]
The exchange rates this agent may quote.
Currency being converted from. The rate is expressed as "1 base = N quote".
Possible values: [usd, eur, rub]
Currency being converted to. Must differ from base.
Possible values: [usd, eur, rub]
Whether this pair is quoted. Disabled pairs are kept but never supplied to the agent.
trueNumber of decimal places the quoted rate is rounded to.
Possible values: >= 0 and <= 6
2markup_percent object
Percentage added to the market rate before it reaches the agent, for quoting above (or, when negative, below) the source rate. 0 quotes the source rate as published.
- number
- string
Possible values: >= -100 and <= 100
models_config object
chatbot_model_config object
- LLMModelConfig
- null
Possible values: [chatgpt, gemini, anthropic, grok, sber, openrouter]
0.7falseclassification_model_config object
- LLMModelConfig
- null
Possible values: [chatgpt, gemini, anthropic, grok, sber, openrouter]
0.7falseping_model_config object
- LLMModelConfig
- null
Possible values: [chatgpt, gemini, anthropic, grok, sber, openrouter]
0.7falsedocument_model_config object
- LLMModelConfig
- null
Possible values: [chatgpt, gemini, anthropic, grok, sber, openrouter]
0.7falseclassification_config object
Controls what the agent extracts from a conversation and stores on the lead.
Run a dedicated collector that reads the lead's timezone from the conversation and stores it on the lead. Stops once a timezone is known.
falseRun a dedicated collector that reads the lead's own phone number from the conversation. A collected number becomes a real phone contact on the lead rather than a classification field, and is mirrored to the CRM. It is stored in canonical form (country code and national number) and is never made the lead's main contact, so it does not become an outreach target on its own. Stops once the lead has any phone contact. To avoid a pointless call on every message, the collector runs only when the lead's own recent messages actually contain enough digits to be a number. It also picks up the lead's name when they give one in the same breath, and names the contacts it creates with it.
falseRun a dedicated collector that reads the lead's own email address from the conversation. Works exactly like collect_phone: a collected address becomes a real email contact on the lead rather than a classification field, is mirrored to the CRM, and is never made the lead's main contact. It is stored lowercased. Stops once the lead has any email contact, and runs only when the lead's own recent messages contain something address-shaped — written, dictated, or obfuscated. Like collect_phone it also picks up the lead's name when they give one alongside the address.
falseWhether the agent extracts the configured fields from dialogues at all.
falsefields object[]
The fields to extract, each described in the agent's own words for the model to fill.
The CRM field's name. Also the key it is stored and read under.
What the agent should look for. Shown to the extraction model.
Legacy type hint. Superseded by the referenced CRM field definition wherever one exists — the definition owns the type and the option set.
stringcrm_field_id object
The CRM field definition this fills, when it has been linked to one. Optional; a field is matched by name when it is absent.
- integer
- null
Whether the agent may overwrite a value that is already there. Filling an empty field needs no permission — listing the field here is that permission. Defaults to true.
truesupport_ticket_request_category_config object
Settings controlling support-ticket request-category classification and whether the LLM may create new reusable categories.
Whether closed support tickets are assigned to an agent-scoped request category.
trueWhether the LLM may create a new reusable category when no active existing category fits. When false, unmatched tickets are assigned to the system insufficient_info category.
truerefusal_reason_config object
Settings controlling refusal reason classification and whether the LLM may create new reusable refusal reasons.
Whether refusal-stage dialogues are assigned to an agent-scoped refusal reason.
trueWhether the LLM may create a new reusable refusal reason when no active existing reason fits. When false, unmatched dialogues are assigned to the system insufficient_info reason.
truehuman_clarification_config object
Human-in-the-loop clarification settings for this agent.
Whether the agent may defer a dialogue and ask a human manager for help.
falsechannel_id object
Manager-facing destination chat/channel for clarification notifications.
- string
- null
message_thread_id object
Optional thread or topic inside the manager channel.
- string
- null
How long the clarification may stay pending before expiring.
Possible values: >= 1
14400extra_text object
Optional extra static text appended to the manager notification.
- string
- null
Whether the client-facing waiting message is sent after the manager notification succeeds.
truefollow_up_message_source object
Optional source of the client-facing waiting message. Literal content (text, prepared_message_id, waba_template_id, files) is sent as-is; a source with only prompt_id generates the message with that prompt; when unset, the message is generated with a built-in prompt.
- MessageSource
- null
text object
- string
- null
prompt_id object
- integer
- null
prompt_version_id object
- integer
- null
prepared_message_id object
- integer
- null
waba_template_id object
- integer
- null
caption object
- string
- null
timeout_follow_up_message_source object
- MessageSource
- null
text object
- string
- null
prompt_id object
- integer
- null
prompt_version_id object
- integer
- null
prepared_message_id object
- integer
- null
waba_template_id object
- integer
- null
caption object
- string
- null
Ordered lead CRM field keys that should be snapshotted into each clarification.
How the pre-reply clarification gate participates. With enforce (default), a separate classifier decides per client message whether the agent may ask the manager, and the agent's clarification prompt is applied as that classifier's policy instead of as main-prompt instructions. With shadow, the classifier runs and its verdicts are logged, but nothing changes for the agent. With off, the classifier does not run. Automatic re-runs (dialogue resumer, pings) never ask the manager, in any mode.
Possible values: [off, shadow, enforce]
enforceGate verdict labels that let the agent ask the manager when gate_mode is enforce. Defaults to needs_manager_fact and likely_needs_manager_fact; narrow to needs_manager_fact alone for the strictest gating.
Possible values: [needs_manager_fact, likely_needs_manager_fact, answerable_or_clarify, out_of_scope, background_turn, gate_error]
max_clarifications_per_day object
Maximum manager-reaching clarification attempts per dialogue per rolling 24 hours (default 3). Over the limit the agent answers from available knowledge instead of asking the manager. Null removes the limit.
- integer
- null
Possible values: >= 1
tools_config object
falsefalsehook_tools object[]
External tools exposed to the LLM. These are separate from lifecycle event hooks.
Relative hook path. For tool_backend lifecycle hooks use {client}/hooks/{endpoint}; it is resolved below the client-tools /clients/ base.
Delivery backend. n8n calls the configured n8n host; tool_backend calls the client-tools service.
Possible values: [n8n, tool_backend]
n8ntool_name object
LLM tool name. Used only when this configuration appears in hook_tools.
- string
- null
Reload lead and contact context after a successful lifecycle hook, for synchronous handlers that mutate them.
falsellm_description object
Instructions shown to the LLM for an external tool. Used only in hook_tools.
- string
- null
Whether an external tool returns later through the asynchronous call-result callback.
falseMaximum wait for an asynchronous tool result, in seconds.
600callback_task_config object
- CallbackTaskConfig
- null
Length of one callback slot, in minutes.
30How far ahead callback availability is calculated, in hours.
168manager_web_call_links object
Optional per-manager call URLs to inject into the CRM task text. Keys should use the manager_key returned by the callback-task-managers endpoint.
manager_callback_tasks_enabled object
Optional per-manager allowlist for callback task assignment. Leave empty to allow every live CRM manager; once populated, only managers with a true flag stay assignable.
reminders object[]
Reminder schedule for created callback tasks.
source objectrequired
Specifies the content of a message to send, by reference to exactly one source — raw text, a prompt, a prepared message, a WABA template, or file(s).
text object
- string
- null
prompt_id object
- integer
- null
prompt_version_id object
- integer
- null
prepared_message_id object
- integer
- null
waba_template_id object
- integer
- null
caption object
- string
- null
Expose all provider event custom fields as template variables for this reminder; currently supported for YClients. Defaults to false; the legacy fields list is ignored without migration. Hyphens in keys become underscores (my-custom-field is used as {{ my_custom_field }}); values are preserved. Event fields override same-named lead fields under the existing enrichment rules, including built-in contact-name precedence. If normalized event keys collide, the last key in the provider response wins. The reminder is skipped when the record is unavailable, custom_fields is empty/invalid, or any value is empty; its step number is not advanced, so the next scheduler tick retries it. Values 0 and false count as filled. When enabled, direct text is rendered before scheduling; other providers perform no external lookup.
falsehooks_config object
Lifecycle event hooks grouped by event type. Each event is journaled once and delivered synchronously to every configured destination.
hooks object
Hook destinations keyed by lifecycle event type. n8n and tool_backend destinations can be mixed.
property name* object[]
Relative hook path. For tool_backend lifecycle hooks use {client}/hooks/{endpoint}; it is resolved below the client-tools /clients/ base.
Delivery backend. n8n calls the configured n8n host; tool_backend calls the client-tools service.
Possible values: [n8n, tool_backend]
n8ntool_name object
LLM tool name. Used only when this configuration appears in hook_tools.
- string
- null
Reload lead and contact context after a successful lifecycle hook, for synchronous handlers that mutate them.
falsellm_description object
Instructions shown to the LLM for an external tool. Used only in hook_tools.
- string
- null
Whether an external tool returns later through the asynchronous call-result callback.
falseMaximum wait for an asynchronous tool result, in seconds.
600Whether mapped CRM stage changes are prevented from moving product leads away from terminal local stages.
falseinbound_lead_config object
Controls lead creation and the optional acknowledgement sent before the main generated reply.
stage_id object
Pipeline stage assigned to a lead created from an inbound message. Null falls back to the agent's initial pipeline stage, then the product's first stage.
- integer
- null
Whether to send the quick reply for a newly created inbound lead dialogue or an eligible replacement support-ticket dialogue after response eligibility checks pass.
falseJinja template rendered from lead CRM fields and sent immediately before main reply generation. Replacement support tickets use a server-configured closure cooldown. Blank text disables the quick reply.
Whether to send a canned reply when a new dialogue opens with a bare "/start" message (common from Telegram/Max bots). When it fires it replaces the generated reply for that turn and takes precedence over the quick reply.
falseJinja template sent in response to a "/start" opener (matched on the first token, so deep links like "/start
voice_config object
Proprietary voice-agent settings (providers, models, greeting, and call behavior). Unset fields inherit the deployment defaults.
llm_provider object
- string
- null
Possible values: [google, gemini, anthropic, yandex]
llm_fallback_enabled object
- boolean
- null
llm_attempt_timeout object
- number
- null
Possible values: >= 1 and <= 60
gemini_model object
- string
- null
gemini_temperature object
- number
- null
Possible values: >= 0 and <= 2
gemini_thinking_level object
- string
- null
anthropic_model object
- string
- null
anthropic_temperature object
- number
- null
Possible values: >= 0 and <= 1
yandex_model object
- string
- null
yandex_temperature object
- number
- null
Possible values: >= 0 and <= 1
stt_provider object
- string
- null
Possible values: [soniox, deepgram]
soniox_model object
- string
- null
soniox_language_hints object
- string[]
- null
soniox_context object
- string
- null
deepgram_flux_model object
- string
- null
stt_keyterms object
- string[]
- null
tts_provider object
- string
- null
Possible values: [elevenlabs, cartesia, gemini]
elevenlabs_model object
- string
- null
elevenlabs_voice_id object
- string
- null
elevenlabs_language object
- string
- null
cartesia_model object
- string
- null
cartesia_voice_id object
- string
- null
cartesia_language object
- string
- null
gemini_tts_model object
- string
- null
gemini_tts_voice object
- string
- null
gemini_tts_instructions object
- string
- null
voice_agent_greeting_enabled object
- boolean
- null
voice_agent_greeting object
- string
- null
voice_agent_greeting_allow_interruptions object
- boolean
- null
voice_agent_greeting_delay_s object
- number
- null
Possible values: >= 0 and <= 5
voice_agent_opener object
- string
- null
tts_style_tags_enabled object
- boolean
- null
cartesia_slowly_speed_ratio object
- number
- null
Possible values: >= 0.6 and <= 1.5
cartesia_whisper_volume_ratio object
- number
- null
Possible values: >= 0.5 and <= 2
cartesia_emotion_tags_enabled object
- boolean
- null
cartesia_pause_break_ms object
- integer
- null
Possible values: >= 100 and <= 2000
livekit_interruption_enabled object
- boolean
- null
livekit_interruption_mode object
- string
- null
Possible values: [vad, adaptive]
end_call_enabled object
- boolean
- null
inactivity_pings_enabled object
- boolean
- null
inactivity_timeout object
- number
- null
Possible values: >= 5 and <= 600
backchannel_enabled object
- boolean
- null
backchannel_probability object
- number
- null
Possible values: >= 0 and <= 1
{
"product_id": 0,
"name": "string",
"bot_type": "outreach",
"is_active": true,
"config": {
"timezone": "Europe/Moscow",
"language": "ru",
"gender": "male",
"pii_allowlist": [
"string"
],
"mute_after_handoff": true,
"max_bot_turns_limit": 30,
"message_debounce_guard_pre_cooldown_seconds": 0,
"add_dt_to_prompt": true,
"communication_context_config": {
"enabled": true,
"include_test_leads": false
},
"redirects_enabled": true,
"redirect_to_agent_id": 0,
"redirect_message_source": {
"text": "string",
"prompt_id": 0,
"prompt_version_id": 0,
"prepared_message_id": 0,
"waba_template_id": 0,
"file_ids": [
0
],
"caption": "string"
},
"prevent_bot_misuse": false,
"resolve_if_message_is_for_agent": true,
"reactions_enabled": false,
"reactions_probability_percent": 25,
"quote_replies_enabled": true,
"quote_replies_probability_percent": 0,
"fetch_history_on_onboarding": false,
"delay_messages_symbols_per_second": 0,
"delay_messages_seconds": 0,
"split_messages": true,
"lead_expires_in_hours": 336,
"rag_config": {
"max_documents": 10,
"max_units": 20,
"max_chars": 16000,
"per_mode_limits": {}
},
"lead_research_config": {
"enabled": false,
"source_fields": [
"string"
],
"llm_model_config": {
"vendor": "chatgpt",
"model": "string",
"temperature": 0.7,
"prompt_caching_enabled": false
},
"max_tool_calls": 5,
"max_output_tokens": 5000,
"summary_max_chars": 1800,
"require_reliable_identity_match": true,
"review_required_before_outreach": true
},
"currency_rates_config": {
"enabled": false,
"source": "cbr",
"prompt": "",
"max_staleness_minutes": 0,
"pairs": [
{
"base": "usd",
"quote": "usd",
"enabled": true,
"precision": 2,
"markup_percent": 0
}
]
},
"models_config": {
"chatbot_model_config": {
"vendor": "chatgpt",
"model": "string",
"temperature": 0.7,
"prompt_caching_enabled": false
},
"classification_model_config": {
"vendor": "chatgpt",
"model": "string",
"temperature": 0.7,
"prompt_caching_enabled": false
},
"ping_model_config": {
"vendor": "chatgpt",
"model": "string",
"temperature": 0.7,
"prompt_caching_enabled": false
},
"document_model_config": {
"vendor": "chatgpt",
"model": "string",
"temperature": 0.7,
"prompt_caching_enabled": false
}
},
"classification_config": {
"collect_lead_timezone": false,
"collect_phone": false,
"collect_email": false,
"classification_enabled": false,
"fields": [
{
"name": "string",
"description": "string",
"data_type": "string",
"crm_field_id": 0,
"can_update": true
}
]
},
"support_ticket_request_category_config": {
"classification_enabled": true,
"auto_create_enabled": true
},
"refusal_reason_config": {
"classification_enabled": true,
"auto_create_enabled": true
},
"human_clarification_config": {
"enabled": false,
"channel_id": "string",
"message_thread_id": "string",
"timeout_seconds": 14400,
"extra_text": "string",
"follow_up_enabled": true,
"follow_up_message_source": {
"text": "string",
"prompt_id": 0,
"prompt_version_id": 0,
"prepared_message_id": 0,
"waba_template_id": 0,
"file_ids": [
0
],
"caption": "string"
},
"timeout_follow_up_message_source": {
"text": "string",
"prompt_id": 0,
"prompt_version_id": 0,
"prepared_message_id": 0,
"waba_template_id": 0,
"file_ids": [
0
],
"caption": "string"
},
"lead_field_names": [
"string"
],
"gate_mode": "enforce",
"gate_arming_labels": [
"needs_manager_fact"
],
"max_clarifications_per_day": 0
},
"tools_config": {
"calendar_enabled": false,
"crm_callback_tasks_enabled": false,
"hook_tools": [
{
"webhook_url": "string",
"backend_type": "n8n",
"tool_name": "string",
"refresh_ctx_after": false,
"llm_description": "string",
"wait_for_results_async": false,
"wait_for_results_async_timeout_seconds": 600
}
],
"files_to_send": [
0
]
},
"callback_task_config": {
"slot_duration_minutes": 30,
"lookahead_hours": 168,
"manager_web_call_links": {},
"manager_callback_tasks_enabled": {},
"reminders": [
{
"step_number": 0,
"before_minutes": 0,
"source": {
"text": "string",
"prompt_id": 0,
"prompt_version_id": 0,
"prepared_message_id": 0,
"waba_template_id": 0,
"file_ids": [
0
],
"caption": "string"
},
"use_event_provider_custom_fields": false
}
]
},
"hooks_config": {
"hooks": {}
},
"skip_crm_stage_sync_from_terminal_stage": false,
"inbound_lead_config": {
"stage_id": 0,
"quick_reply_enabled": false,
"quick_reply_text": "",
"reply_to_start_enabled": false,
"reply_to_start_text": ""
},
"voice_config": {
"llm_provider": "google",
"llm_fallback_enabled": true,
"llm_attempt_timeout": 0,
"gemini_model": "string",
"gemini_temperature": 0,
"gemini_thinking_level": "string",
"anthropic_model": "string",
"anthropic_temperature": 0,
"yandex_model": "string",
"yandex_temperature": 0,
"stt_provider": "soniox",
"soniox_model": "string",
"soniox_language_hints": [
"string"
],
"soniox_context": "string",
"deepgram_flux_model": "string",
"stt_keyterms": [
"string"
],
"tts_provider": "elevenlabs",
"elevenlabs_model": "string",
"elevenlabs_voice_id": "string",
"elevenlabs_language": "string",
"cartesia_model": "string",
"cartesia_voice_id": "string",
"cartesia_language": "string",
"gemini_tts_model": "string",
"gemini_tts_voice": "string",
"gemini_tts_instructions": "string",
"voice_agent_greeting_enabled": true,
"voice_agent_greeting": "string",
"voice_agent_greeting_allow_interruptions": true,
"voice_agent_greeting_delay_s": 0,
"voice_agent_opener": "string",
"tts_style_tags_enabled": true,
"cartesia_slowly_speed_ratio": 0,
"cartesia_whisper_volume_ratio": 0,
"cartesia_emotion_tags_enabled": true,
"cartesia_pause_break_ms": 0,
"livekit_interruption_enabled": true,
"livekit_interruption_mode": "vad",
"end_call_enabled": true,
"inactivity_pings_enabled": true,
"inactivity_timeout": 0,
"backchannel_enabled": true,
"backchannel_probability": 0
}
}
}