Create an agent
https://server.heyrik.com/api/v1/agentsHeaders
AuthorizationstringRequiredUse Bearer $HEYRIK_API_KEY with an account-scoped API key. Keep the key on your server.
Parameters 26
Fields documented for this operation. See the request example for placement and structure.
namestringRequiredShown in the dashboard and call logs.
system_promptstringAlternative to prompt_sections: a single free-text instruction block. If BOTH are sent, prompt_sections wins. Use this only for a very simple agent.
languagestringPrimary BCP-47 code: en-IN, hi-IN, te-IN… Defaults to English.
greetingstringFirst line on an OUTBOUND call. Supports {{placeholders}} — any input variable you declare in config.input_variables (e.g. {{customer_name}}), plus {{lead_name}}, {{agency_name}}. Each is filled per call and falls back to its declared default when unset (an empty default drops it from the sentence, so a token never leaks).
inbound_greetingstringFirst line when someone calls IN. Falls back to greeting.
voice_settingsobject{ "voice_id": "<id from GET /voices>", "speed": 1.0 }. Works with any library voice OR one of your cloned voices. Omit and a default is picked.
configobjectEverything else the dashboard builder configures — each key below is one builder section.
10 properties
prompt_sectionsobject[]RequiredThe agent's instructions as an ordered list of sections — edit these inside Assistant Details in the dashboard. Each: { title, content, order?, enabled? }. They're compiled in order into the agent's prompt (sections with enabled:false are skipped). Use these; this is how the builder defines an agent.
4 properties
titlestringThe section heading, e.g. "Identity & Purpose", "Language Restrictions", "Conversational Flow", "Guardrails", "Closing".
contentstringThe instructions for that section (plain text; newlines and bullet dashes are fine).
ordernumber0-based position. Sections run top to bottom by order. Optional — array order is used if omitted.
enabledbooleanfalse turns the section off without deleting it. Defaults to true.
languagesstring[]Every language the agent may speak. It mirrors the caller's language automatically.
personalitystringResponse Behavior → tone: Professional | Friendly | Empathetic | Energetic | Concise. (This is the persona/how-it-sounds steer — separate from the instruction sections.)
fillersobjectResponse Behavior → filler phrases: { "enabled": true }. Speaks a brief "let me check…" while a tool runs, so the caller isn't left in silence.
call_behaviorobjectCall Configuration + End Call Rules + Ambient Sound — see below.
5 properties
silence_msnumberSilence timeout in ms before the agent re-engages (e.g. 3000 = 3s).
max_call_duration_secnumberEnd Call Rules → hard cap. The agent signs off and hangs up at this length. 0 = no cap.
end_call_phrasesstring[]End Call Rules → phrases that end the call when the caller says them (e.g. "goodbye", "that's all").
background_audio_namestringAmbient Sound → the name of an available background clip from GET /background-audios, such as "Office"/"Café". Uploads are managed by the HeyRik team. null = silent.
background_audio_idstringAmbient Sound → the exact clip id (from GET /background-audios). Takes priority over the name. null = silent.
no_responseobjectSilence Handling: { "enabled": true, "max_retries": 2, "prompts": [{ "after_sec": 3, "text": "Are you still there?" }] }. Re-engages a quiet caller, then gives up after max_retries.
transferobjectTransfer & Routing: { "enabled": true, "mode": "static", "static_number": "+91…", "condition": "when the caller asks for a human" }. Escalates to a phone number.
input_variablesobject[]Variables tab → INPUT: the {{placeholders}} your greeting and prompt_sections use, each DECLARED with a fallback: [{ "name": "customer_name", "default": "there", "description": "who is being called" }]. A per-call value (the originate `variables` object, or a lead's custom field) fills it; if none is supplied the `default` is used, so a token never leaks to the caller as literal "{{customer_name}}". Identity slots — {{agent_name}}, {{company_name}} — left with an empty default drop gracefully from the sentence when unknown. This is what POST /agents/generate returns for any placeholder it writes.
extracted_variablesobject[]Post-Call → OUTPUT: data to collect: [{ "name": "customer_name", "description": "the caller's full name" }]. The agent fills these DURING the call and they appear on each call afterwards. (Input variables go IN via {{placeholders}}; extracted variables come OUT.)
post_call_webhookstringPost-Call → a URL we POST the finished call to (transcript, recording URL, extracted fields, summary).
curl -X POST https://server.heyrik.com/api/v1/agents \
-H "Authorization: Bearer $HEYRIK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support agent",
"language": "en-IN",
"config": {
"prompt_sections": [
{
"title": "Instructions",
"content": "You are the Acme support assistant. Answer from approved knowledge. If an answer is unavailable, offer a human follow-up."
}
]
}
}'Creates a draft using the default voice. Add your knowledge and test the agent before placing calls.
{
"data": {
"id": "agc_9f2a1c30",
"name": "Real Estate Qualifier",
"language": "te-IN",
"greeting": "Namaskaram {{customer_name}}, calling from the property team about your enquiry.",
"voice_settings": { "voice_id": "vx_9f2a1c30", "speed": 1.0 },
"config": {
"personality": "Professional",
"languages": ["te-IN", "en-IN"],
"prompt_sections": [ { "order": 0, "title": "Identity & Purpose", "content": "…" }, "…" ],
"input_variables": [ { "name": "customer_name", "default": "there", "description": "…" }, "…" ],
"extracted_variables": [ { "name": "property_type", "description": "…" }, "…" ],
"call_behavior": { "max_call_duration_sec": 900 }
},
"created_at": "2026-07-24T06:11:44.201Z"
}
}Illustrative examples · No live request is sent