Skip to Content
Builder Docs
Agent Design & Conversation Logic

Nodes, Prompts & Variables

Complete builder reference for all 9 node types, edges, built-in tools, RECORDING_ID audio, voice prompting rules, Unified Built-In Variables Cheat Sheet, extraction, and publish validation.

Talkar agents run as a directed conversation graph (Agent Canvas). Each active node supplies its own system prompt, tools, Knowledge Base documents, and outgoing transition edges dynamically at every step of the call. Cycles (Agent <-> Agent loops) are allowed, which makes verification retries and FAQ-return flows easy to model.

1. All 9 Node Types on the Canvas

Node TypeCategoryGraph RulesPurpose & Key Settings
startCall (Start Call)Core CallExactly 1 per graph; 0 incoming edgesEntry point of the call. Configures greeting_type (text or pre-recorded audio), greeting, delayed_start (bool, default false), delayed_start_duration (0.1s–10.0s, default 2.0s wait after answer), pre_call_fetch_*, allow_interrupt (default false), add_global_prompt (default true), tools, KB docs, and live extraction.
agentNode (Agent)Core Call>= 1 incoming edgeMain conversational stages (qualification, scheduling, support). Exposes prompt, allow_interrupt (default true), add_global_prompt (default true), tools, KB docs, MCP tool filters, and live extraction.
endCall (End Call)Core Call>= 1 incoming edge; 0 outgoing edgesSpeaks closing line and ends the call automatically (allow_interrupt always forced off and hidden in UI, add_global_prompt defaults false, no tools/KB attached). Supports closing variable extraction.
globalNode (Global Prompt)GlobalMax 1 per graph; 0 edgesPrepended before any Start Call, Agent, or End Call node where add_global_prompt is enabled. Ideal for persona, voice rules, common FAQs, and {{current_time}}.
trigger (API Trigger)TriggerMax 1 per graph; 0 incoming edgesExposes a trigger_path ([a-zA-Z0-9_-], up to 36 chars, UUID when auto-generated) for POST /api/v1/public/agent/{trigger_path} (published) and POST /api/v1/public/agent/test/{trigger_path} (draft), both requiring X-API-Key. Toggle enabled off to return 404 without deleting.
webhook (Post-Call Webhook)IntegrationMultiple allowed; 0 edgesFires asynchronously after QA, Post-Call Intelligence, and billing integrations complete. Supports POST/PUT/PATCH/GET/DELETE, Credentials Vault (credential_uuid), and JSON payload_template (auto-injects call_disposition).
qa (QA Analysis)IntegrationMultiple allowed; 0 edgesEvaluates transcript quality, sentiment, score, and tags per node (or whole call) after completion. Configurable minimum duration (15s default), qa_sample_rate (1–100%), qa_voicemail_calls, and optional separate QA LLM. (Note: qa_system_prompt evaluates double braces like `{{node_summary}}`, `{{previous_conversation_summary}}`, `{{transcript}}`, `{{metrics}}` at runtime.)
paygent3rd-PartyMax 1 per graph; 0 edgesPost-call usage/billing export integration (paygent_api_key, paygent_agent_id, paygent_customer_id, paygent_indicator).
tuner3rd-PartyMax 1 per graph; 0 edgesPost-call observability & optional BYOK cost export to Tuner (tuner_agent_id, tuner_workspace_id, tuner_api_key, token/audio rates).

Webhook Security & Retry Rules

  • custom_headers strips secret headers matching authorization, token, secret, password, api-key, etc. (except X-Idempotency-Key)—always store webhook tokens in the Credentials Vault (credential_uuid).
  • Retries: Retries automatically with 30s–600s exponential backoff on network errors and HTTP 408 / 425 / 429 / 5xx (30s HTTP timeout, up to 5 attempts), auto-retries once on OAuth2 401, and marks permanent 4xx responses as dead-letter failures.

2. How Edges, Transition Speech & End Conditions Work

Talkar does not use a separate router LLM. Every outgoing edge from the active node becomes a callable LLM tool function derived from its label (lowercased, non-alphanumeric replaced with _), with its condition passed verbatim as the function description.

Validation Rule: Unique Edge Labels & Tool Collisions

Two outgoing edges from the same node cannot resolve to the same normalized tool name (e.g., "End Call" and "End-Call" collide), nor match the name of an HTTP/custom tool attached to that node. Publishing blocks until renamed cleanly.

Edge Transition Execution Order & Prompt Assembly

When the LLM calls an edge transition tool:

  1. If the departing node has extraction_enabled = true, Talkar starts async variable extraction on the conversation so far.
  2. If the edge defines transition_speech_type (text or audio), Talkar plays that transition speech (rendering any `{{variables}}`) before switching prompts. Leave transition_speech blank to route silently into the next node.
  3. If context_compaction_enabled = true and message history exceeds 6 messages (> 6 messages) when entering a non-start node, older turns are summarized automatically.
  4. If cross_node_variable_injection_enabled = true, Talkar awaits pending extraction (up to 30s) before rendering the destination node prompt so `{{gathered_context.*}}` is populated immediately.
  5. The LLM system prompt updates cleanly in place without breaking conversation history, assembled as [Global Prompt] + "\n\n" + [Node Prompt] + "\n\n" + [Recording Instructions] (Recording Instructions are injected only if the org has recordings AND "RECORDING_ID:" appears in the prompt).

All 5 Ways a Call Ends

  1. Transition into an End Call node: Agent delivers its final closing response, flushes final extraction, and hangs up cleanly (user_qualified).
  2. Calling an end_call Custom Tool: Ends immediately unless a goodbye customMessage or audioRecordingId is configured on the tool (end_call_tool / custom reason disposition).
  3. Calling a transfer_call Custom Tool: Speaks optional handoff audio (up to 12s wait) and transfers to a static or API-resolved phone/SIP destination.
  4. Guardrail Timeouts / AMD: Voicemail/AMD detection (voicemail_detected), user idle (max_user_idle_timeout, default 10s), or max_call_duration (300s default + 30s extraction grace).
  5. Caller Hangup or Explicit End API: Triggers final extraction flush and post-call integrations (user_hangup).

Post-Call Pipeline Order: Public download tokens -> QA Analysis -> Post-Call Intelligence (PCI) -> Paygent / Tuner -> Post-Call Webhook deliveries.

3. Built-In Tools, MCP Filters & Inline Pre-Recorded Audio (RECORDING_ID)

In addition to Custom HTTP APIs and MCP servers, nodes (Start Call, Agent) can attach built-in tools:

  • End Call Tool & Transfer Call Tool (category tools configured in Dashboard Tools)
  • Wait (wait_for_user): Pauses while the caller looks up an ID, OTP, or document (message required; schema seconds default 60s, max 300s; keep prompt guidance >= 15s when asking callers to look something up).
  • Calculator (safe_calculator): Safe AST math evaluator (+, -, *, /, **, %, parentheses).
  • Knowledge Base (retrieve_from_knowledge_base): Auto-injected whenever document_uuids are attached to the node (limit = 3 default at runtime).
  • MCP Tool Filtering (mcp_tool_filters): Leaving a server entry unset (null) exposes all discovered tools on that server, whereas [] suppresses all tools from that server; unreachable external MCP servers degrade cleanly without failing the call.

Mixing Studio Audio with TTS (RECORDING_ID)

  • Upload .wav files (max 5 MB per file) in Organization Recordings.
  • Inside node prompts: Reference the string recording_id as `RECORDING_ID: intro_clip`. Talkar automatically instructs the LLM to prefix spoken lines with ▸ (TTS) or exact recordings with ● <recording_id> <transcript> — never mixing both in one response.
  • In Start Call greetings & Edge transition speech: Selecting audio mode stores the recording's numeric record ID directly.

4. Unified Built-In & Template Variables Cheat Sheet

All prompts, Start Call greetings, edge transition speech, HTTP tool URLs/headers/bodies, transfer targets, and webhook templates share one template engine.

Context Layers

  1. initial_context (flattened + nested): Caller info, Campaign CSV row values, Pre-Call Data Fetch responses, or API initial_context. Reachable directly (`{{first_name}}`) or via `{{initial_context.first_name}}`. (Pre-Call Fetch runs with a 10-second fail-safe timeout sending POST JSON {"event": "call_inbound", "call_inbound": {"agent_id", "from_number", "to_number"}} and retries once on OAuth2 401—failures never drop the call.)
  2. gathered_context (live call state): Variables extracted by previous nodes (`{{gathered_context.budget}}`) plus runtime telemetry (call_disposition, call_tags, answered_by, call_id).
  3. Dynamic Date/Time Tokens: Evaluated fresh at render time.

Complete System Variables & Availability by Call Mode

Variable TokenResolves ToAvailable InValidation Note
`{{current_time}}`UTC timestamp (YYYY-MM-DD HH:MM:SS UTC), or inherits <TZ> if current_time_<TZ> is in the same templateAll modesAdd | default in campaigns so CSV header check skips it
`{{current_time_Asia/Kolkata}}`Live timestamp in any valid IANA timezone (ZoneInfo)All modesAdd | default in campaigns so CSV header check skips it
`{{current_weekday}}` / `{{current_weekday_Asia/Kolkata}}`Full weekday name (Monday, Tuesday, ...); bare current_weekday inherits <TZ> from current_time_<TZ>All modesAdd | default in campaigns so CSV header check skips it
`{{initial_context.caller_number}}` (or `{{caller_number | fallback:unknown}}`)Inbound: Caller's phone number.
Outbound (Direct / Trigger / Campaign): Talkar's outbound Caller-ID (from_number).		Inbound, Outbound, Trigger, CampaignAlways use initial_context. prefix or | fallback: so Campaign/Publish validation does not treat bare {{caller_number}} as a missing CSV column!
`{{initial_context.called_number}}` (or `{{called_number | fallback:unknown}}`)Inbound: Your Talkar DID dialed (to_number).
Outbound: Contact's destination phone number.		Inbound, Outbound, Trigger, CampaignAlways use initial_context. prefix or | fallback:
from_number / to_number (JSON body)Pre-Call Fetch webhook receives call_inbound.from_number (caller_number) and call_inbound.to_number (called_number)Pre-Call Fetch (Start Call)Not a prompt token — read inside your Pre-Call endpoint
`{{phone_number}}`Campaigns: Required CSV contact column.
External Trigger API: Legacy alias for called_number.		Campaigns (CSV), External TriggerDeprecated in favor of called_number outside Campaigns CSV
`{{initial_context.direction}}`"inbound" on inbound PSTN/SIP callsInbound TelephonyUse | fallback: if workflow also runs outbound
`{{campaign_id}}`, `{{provider}}`, `{{source_uuid}}`System-injected campaign ID, telephony provider, and lead UUIDCampaigns / TelephonyBuilt-in system exclusions (never flagged as missing)
`{{gathered_context.<var>}}`Variable extracted from an earlier nodeDownstream nodes & WebhooksRequires cross_node_variable_injection_enabled = true on Workflow Settings
`{{call_disposition}}`, `{{call_tags}}`, `{{answered_by}}`Final disposition (see Canonical Dispositions), tags list, and Twilio AMD statusPost-Call Webhooks & LogsAvailable after call state updates / post-call

Important Cross-Node Timing Rule

Node-level extraction triggers when exiting a node (or on hangup). Node A cannot read its own extracted variable inside Node A's prompt — only downstream Node B (after exiting Node A) can read `{{gathered_context.<var>}}`.

Syntax, Safe Fallbacks & URL Hardening

  • Fallback vs. Default: `{{first_name | fallback:there}}` renders "there" when missing/empty (writing `{{first_name | fallback:}}` with empty text renders Title-Cased "First Name"), whereas `{{first_name | default:Guest}}` renders "Guest" (and empty `{{first_name | default:}}` renders "").
  • Newlines & Nested Paths: `{{annotations.qa_123.tags}}` reads nested JSON objects/arrays, and literal \n escapes convert to newlines outside URL templates.
  • URL Safety: HTTP tool and webhook URL templates percent-encode values, reject objects/arrays or empty non-defaulted parameters, and forbid placeholders from mutating URL scheme or host.

5. Voice Prompting & Edge-Condition Best Practices

  • Voice-First Output Formatting: Keep responses to 1–3 short sentences using contractions (I'm, we'll). Never output bullet lists, numbered markdown, or parenthetical stage directions.
  • Hinglish / Code-Mixed English Calls: Instruct the LLM in # VOICE to understand mixed languages silently and output Latin script only unless bilingual TTS is configured.
  • One Question Per Turn & Clear Re-Ask Rules: Explicitly instruct Agent nodes to wait for a clear answer before calling transition edges, allow at most one simpler re-ask on noisy replies, and record "unclear" / "declined" rather than looping indefinitely.
  • Guard Sensitive Edges: Put explicit prerequisites in every End Call or jump edge condition so negative answers never trigger premature hangup.
  • Silence vs. Spoken Transition Speech: Leave transition_speech empty whenever the destination node will speak immediately so callers don't hear two consecutive openings.
  • Lock Interruptions on Greetings & Closings: Keep allow_interrupt = false on Start Call greetings (default false; End Call always forces it off).

6. Live Extraction vs. Post-Call Intelligence (PCI)

MechanismWhen It RunsIdeal ForKey Behavior & Limits
Node-Level Live Extraction (extraction_enabled)Async on every outgoing edge transition + final flush at call endMulti-step forms, feeding downstream `{{gathered_context.*}}`, capturing answers per sectionSupports string, number, boolean. Sequence-locked so out-of-order updates don't overwrite newer values; empty / "null" extractions never erase existing non-empty values. History truncated to last 16,000 chars (2,000 chars per tool result).
Post-Call Intelligence (post_call_schema)Once after call end, right after QA and before Post-Call WebhooksFull-call summaries, final classification, fields spanning multiple nodesSkips automatically if duration < 10s, call_disposition == "voicemail_detected", or empty transcript. Enriches/overwrites final extracted_data in run logs & webhooks.

7. Pre-Publish Validation Checklist

Before clicking Publish, Talkar verifies every rule below (Draft Save permits incomplete prompts, but Publish blocks on failures):

  1. Prompt Completeness: Every Start Call, Agent, End Call, and Global Prompt node has a non-empty prompt.
  2. Graph Topology: Exactly 1 Start Call (0 incoming edges); >= 1 incoming edge on every Agent and End Call; 0 outgoing edges on every End Call; 0 incoming edges on Trigger; 0 edges on Global, Webhook, QA, Paygent, Tuner.
  3. Unique Tool & Edge Names: No duplicate normalized edge labels from the same node, and no edge label colliding with an attached custom tool name.
  4. Unique Trigger Path: Trigger node trigger_path doesn't conflict with another workflow.

Quickstart: Build & Test Your First Client Agent

Go from blank canvas (or AI template) to a tested, published client agent in minutes.

Voice, Models & STT/TTS Selection

Choosing Pipeline vs. Realtime S2S, Production Provider Trust Policy, 3-tier override precedence, key rotation, Indian language models, sample rates, custom ambient noise, and pronunciation keyterms.

On this page

1. All 9 Node Types on the Canvas2. How Edges, Transition Speech & End Conditions WorkEdge Transition Execution Order & Prompt AssemblyAll 5 Ways a Call Ends3. Built-In Tools, MCP Filters & Inline Pre-Recorded Audio (RECORDING_ID)Mixing Studio Audio with TTS (RECORDING_ID)4. Unified Built-In & Template Variables Cheat SheetContext LayersComplete System Variables & Availability by Call ModeSyntax, Safe Fallbacks & URL Hardening5. Voice Prompting & Edge-Condition Best Practices6. Live Extraction vs. Post-Call Intelligence (PCI)7. Pre-Publish Validation Checklist