` that you place in your page. | You want the agent embedded in a specific section (landing-page hero, support tab, etc.). |
| **Headless** | No UI. Only the audio/chat pipeline plus a JavaScript API on `window.DograhWidget`. | You want full control over the UI — your own buttons, design system, framework state, animations. |
## Prerequisites
These apply to all three modes:
* **Voice widgets:** serve your page over **HTTPS** or from `http://localhost`. Browsers refuse microphone access on plain HTTP origins or `file://`. Chat widgets have no microphone requirement, though HTTPS is still recommended.
* If you set **Allowed Domains** in the dashboard, include your test origin (e.g. `localhost`) — otherwise the widget's requests are rejected. Leave the list empty to allow all domains.
* The embed snippet you copy from the dashboard is a single `
```
Because it's built in JavaScript at page load, you can put anything your page knows in it — a logged-in customer's name, their plan, cart contents. Replace the object inside `JSON.stringify(...)` in the generated snippet, for example:
```js theme={null}
{
customer_name: currentUser.firstName,
plan: currentUser.plan,
cart: { items: cart.length, total: cart.total }
}
```
Each key is then available in any node prompt as `{{initial_context.}}`:
```text theme={null}
Greet {{initial_context.customer_name | there}} and mention their {{initial_context.plan}} plan.
```
Values can be strings, numbers, booleans, or nested objects. This works for voice and chat widgets alike, and the values are recorded on the conversation so you can see what the agent was given.
### Update context after the page loads
The attribute is fixed at page load, which doesn't fit a single-page app — the visitor logs in, changes route, or fills a cart long after the snippet ran. For that, call `setContext()`:
```js theme={null}
window.DograhWidget.setContext({
customer_name: user.firstName,
plan: user.plan
});
```
Each call merges into the context already collected, so you can add details as they arrive and re-send a name to correct it. `getContext()` returns the current set.
Context is read when a conversation starts, so `setContext()` applies to the **next** conversation — calling it mid-call or mid-chat doesn't change the one in progress (the widget logs a console warning if you do). For chat widgets, "next" includes the fresh conversation started by **Start new chat** after a session expires.
The widget script loads asynchronously, so `window.DograhWidget` may not exist yet when your app's code first runs. Call `setContext()` from an event that fires after load — a `window.load` listener, or a user action like clicking your own "Chat with us" button. See [Lifecycle callbacks](#lifecycle-callbacks-all-modes) for the same timing rule.
Use whichever fits: `data-dograh-context` for what the page knows at render, `setContext()` for what it learns later. They merge, and `setContext()` wins on a repeated name.
Context comes from the page, so a visitor can both read it and change it before it reaches your agent. Never pass secrets, and don't let it gate what the agent will do or disclose — treat `plan: "pro"` as a hint for phrasing, not proof of entitlement. For data the agent must trust, pass an opaque id like `customer_id` and let Dograh fetch the real details from your API with [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch).
Limits, applied per conversation: up to 50 variables, 64 characters per name, 2000 characters per value, and 8 KB in total. Anything past a limit is dropped and the conversation still starts. The names `provider` and `runtime_configuration` are reserved and ignored.
## Floating Widget
![Floating widget shown in the corner of a host page]()
Renders a pill-shaped button anchored to a corner of the page.
* **Voice:** clicking the button (microphone icon + text) starts a call; clicking again ends it. The button auto-updates its label and color across the call lifecycle: configured text → "Connecting…" → "End Call" → "Retry" on failure.
* **Chat:** clicking the button (chat icon + text) opens a chat panel anchored to the same corner; the agent greets the visitor and the conversation happens in the panel. Clicking the button (or the panel's ×) closes the panel without ending the conversation — reopening shows the same transcript.
Configure **Button Text**, **Button Color**, and **Position** (top/bottom + left/right) from the dashboard.
Every other word a visitor sees is editable too, under a collapsible section in the same dialog, so you can run the widget in your site's language: **Chat Panel Text** for chat widgets (end chat button, conversation-ended message, start-new-chat and retry buttons, message placeholder, and the send/close screen-reader labels), or **Voice Call Text** for voice widgets. Leave a field blank to keep the English default.
The host page writes no JavaScript — pasting the embed snippet is the entire integration. If you want to subscribe to call lifecycle events (e.g. analytics), see [Lifecycle callbacks](#lifecycle-callbacks-all-modes) below
## Inline Component
![Inline widget rendered inside a page section]()
Renders a panel inside a `
` you place in your page.
* **Voice:** a status panel (status icon + status text + CTA button). Status changes update the panel in place.
* **Chat:** a call-to-action screen first; clicking the button replaces it with a chat panel that fills the container. No extra JavaScript is needed.
Configure **Button Text**, **Button Color**, and **Call to Action Text** from the dashboard, plus the **Chat Panel Text** / **Voice Call Text** section described under [Floating Widget](#floating-widget). Inline voice widgets show the most copy of any mode — a heading and subtext for each of ready, connecting, connected, ended, failed, and lost — so that section carries the full set here.
### Plain HTML
Place a container `
` where you want the widget to render. The widget auto-attaches to it.
```html theme={null}
```
### React
Because React mounts after the widget script may have already loaded, integrate via `initInline` on first mount and `refresh` on remount. Poll for `window.DograhWidget` to handle the async script load.
```tsx theme={null}
import { useEffect } from 'react';
declare global {
interface Window {
DograhWidget?: {
initInline: (options: { container: HTMLElement }) => void;
refresh: () => void;
getState: () => { isInitialized: boolean };
};
}
}
export function Assistant() {
useEffect(() => {
let retries = 0;
const tryInit = () => {
const container = document.getElementById('dograh-inline-container');
if (window.DograhWidget && container) {
const { isInitialized } = window.DograhWidget.getState();
if (isInitialized) window.DograhWidget.refresh();
else window.DograhWidget.initInline({ container });
} else if (retries++ < 50) {
setTimeout(tryInit, 100);
}
};
tryInit();
}, []);
return ;
}
```
## Headless Mode
![Headless widget driven by host-page UI]()
In Headless mode the widget injects no UI of its own. You render whatever buttons, banners, or chat interfaces you want, and drive the agent through the JavaScript API.
### JavaScript API (voice widgets)
| Method / Callback | Description |
| - | - |
| `window.DograhWidget.start()` | Begin a voice call. Must be called from inside a user-gesture handler (e.g. `click`) so the browser grants microphone access. |
| `window.DograhWidget.end()` | End the active call. |
| `window.DograhWidget.onCallStart(cb)` | Fires when `start()` is invoked (status `connecting`). No payload. |
| `window.DograhWidget.onCallConnected(cb)` | Fires when the WebRTC connection is established. Payload: `{ agentId, workflowRunId, token }`. |
| `window.DograhWidget.onCallDisconnected(cb)` | Fires only if the call had connected, when teardown runs. Payload: `{ agentId, workflowRunId, token, durationSeconds }`. |
| `window.DograhWidget.onCallEnd(cb)` | Fires whenever the call session is torn down (including failed-to-connect attempts). No payload. |
| `window.DograhWidget.onStatusChange(cb)` | Fires on every status change. Callback receives `(status, text, subtext)`. Status values: `idle`, `connecting`, `connected`, `failed`. |
| `window.DograhWidget.onError(cb)` | Fires on errors (mic permission denied, server error, etc.). Callback receives an `Error` object. |
| `window.DograhWidget.setContext(vars)` | Merge visitor context for the next call — see [Pass context to the agent](#pass-context-to-the-agent). Works in every embed mode, not just headless. |
All `on*` setters are single-listener — calling the same one again replaces the previous handler.
### JavaScript API (chat widgets)
| Method / Callback | Description |
| - | - |
| `window.DograhWidget.startChat()` | Start a conversation. The agent's greeting arrives via `onMessage`. |
| `window.DograhWidget.sendMessage(text)` | Send a visitor message. Returns a Promise that resolves with the updated transcript (array of turns), or `null` if the message couldn't be delivered. |
| `window.DograhWidget.getMessages()` | Current transcript as an array of turns: `{ id, status, user_message, assistant_message }`, each message being `{ text, created_at }`. |
| `window.DograhWidget.onMessage(cb)` | Fires once per new agent reply. Callback receives `(text, turn)`. |
| `window.DograhWidget.onChatStateChange(cb)` | Fires on every chat state change. States: `idle`, `starting`, `ready`, `waiting` (agent is replying), `ended`, `expired`, `error`. |
| `window.DograhWidget.onError(cb)` | Fires on errors. Callback receives an `Error` object. |
| `window.DograhWidget.setContext(vars)` | Merge visitor context for the next conversation — see [Pass context to the agent](#pass-context-to-the-agent). Works in every embed mode, not just headless. |
In chat mode `start()` aliases `startChat()` and `end()` is a no-op teardown (chat sessions need none), so generic snippets keep working. Sends are serialized — `sendMessage` while a reply is pending (`waiting`) resolves to `null`.
```html theme={null}
```
**About timing.** The widget script loads asynchronously, so `window.DograhWidget` may not exist at the moment your inline `
```
### React + TypeScript
```tsx theme={null}
import { useEffect, useState } from 'react';
type CallStatus = 'idle' | 'connecting' | 'connected' | 'failed';
declare global {
interface Window {
DograhWidget: {
start: () => void;
end: () => void;
onStatusChange: (cb: (status: CallStatus, text?: string, subtext?: string) => void) => void;
onError: (cb: (err: Error) => void) => void;
};
}
}
export function TalkButton() {
const [status, setStatus] = useState('idle');
useEffect(() => {
window.DograhWidget.onStatusChange((s) => setStatus(s));
window.DograhWidget.onError((err) => console.error('Dograh error:', err.message));
}, []);
const isLive = status === 'connected' || status === 'connecting';
const label = { idle: 'Talk to AI', connecting: 'Connecting…', connected: 'End Call', failed: 'Retry' }[status];
return (
);
}
```
`start()` must run inside a real user-gesture handler (`click`, `touchend`, etc.). Browsers refuse to grant microphone access to scripts that request it outside of one — calling `start()` from a `setTimeout` or on page load will fail with a permission error.
## Lifecycle callbacks (all modes)
The `on*` callbacks in the [Headless JavaScript API](#javascript-api-voice-widgets) work in **all three embed modes**, not just Headless. Use them for analytics or to trigger UI in the host page even when the widget is rendering its own UI (Floating or Inline). The call callbacks (`onCall*`) fire for voice widgets; for chat widgets use `onMessage` and `onChatStateChange` the same way.
```js theme={null}
window.DograhWidget.onCallConnected(({ agentId, workflowRunId }) => {
analytics.track('voice_call_started', { agentId, workflowRunId });
});
window.DograhWidget.onCallDisconnected(({ workflowRunId, durationSeconds }) => {
analytics.track('voice_call_ended', { workflowRunId, durationSeconds });
});
```
`onCallConnected` and `onCallDisconnected` only fire when the call actually establishes a media connection — failed-to-connect attempts (e.g. denied mic, network failure) don't trigger them, so analytics stay clean.
# Agent Node
Source: https://docs.dograh.com/voice-agent/agent
Agent node contains the prompts that drives the conversation with the Voice Agent
## Video Tutorial
Agent Node is the core building block of every Dograh workflow. It holds the LLM prompt that drives the conversation, any tools the agent can call, and knowledge base documents to reference. You can have multiple Agent Nodes in a single workflow, each handling a distinct phase of the conversation.
The Edges connected with Agent Nodes are pathways that the LLMs can take depending on how the conversation has been going so far.
## What goes in an Agent Node
**Prompt**
The instructions for how the agent should behave at this step. Be explicit about sequence: if the agent should confirm identity before discussing payment, say so in the prompt. Vague prompts produce inconsistent behavior.
**Tools**
External functions the agent can call during this step - for example, looking up account balances or updating a CRM record. Add tools via the "HTTP & Tools" or "MCP" tabs in the node settings panel.
**Allow Interruption**
When on, the caller can interrupt the agent mid-utterance.
**Add Global Prompt**
When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default.
**Knowledge Base Documents**
Files the agent can reference when answering questions - product guides, FAQs, policies. Attach them via the "Manage Documents" button in the node settings panel.
## Configuring edges
Each outgoing edge has a condition written in plain language. The LLM evaluates the conversation and picks the edge whose condition best matches.
Write edge conditions as specifically as possible:
| Vague (avoid) | Specific (use) |
| - | - |
| "Debtor responds" | "Debtor confirms their identity and is ready to discuss the account" |
| "Call ends" | "Debtor commits to a specific payment option and states the amount" |
| "Problem" | "Debtor disputes owing the debt or requests validation documentation" |
If the agent keeps routing to the wrong edge, make the condition more specific. Conditions like "user responds" or "conversation ends" are too broad and will route unpredictably.
## Extracting variables
Agent Node can extract structured data from the conversation after the node completes. Enable this in the node settings under "Enable Variable Extraction."
Once enabled, configure two things:
* **Extraction Prompt:** overall instructions telling the LLM how to approach the extraction.
* **Variables to Extract:** a list of variables, each with a name, a data type (`string`, `number`, `boolean`), and a per-variable hint describing what to capture.
For example:
```text theme={null}
Extraction Prompt:
Extract the payment outcome from this debt collection call.
Variables:
- amount_user_will_pay (string): Amount the user said they will pay.
- payment_method (string): How they said they will pay, e.g. card, bank transfer.
- sentiment (string): User tone: cooperative, hesitant, angry, refused.
```
Each extracted value is stored in `gathered_context`. It is not available in any node's Prompt - reference it in [Webhook node](./webhook) payloads as `{{gathered_context.variable_name}}`, or read it from the run record after the call completes.
## Using multiple Agent Nodes
Break complex conversations into phases. Each Agent Node handles one part of the flow. A debt collection workflow, for example, might chain three Agent Nodes: identity verification, offer presentation, and objection handling.
Nodes pass context forward automatically, but not into prompts. Variables extracted in one node are stored in `gathered_context` and merged with variables from later nodes as the call progresses. `gathered_context` is not available in any node's Prompt - it can only be referenced in [Webhook node](./webhook) payloads and in the run record after the call completes. If a later Agent Node needs to react to something extracted earlier, that logic has to live in the prompt's own instructions, not in a `{{gathered_context...}}` reference.
## Common mistakes
**No outgoing edges.** Every Agent Node needs at least one edge. A dead-end node has no exit path and will trap the call.
**Putting global instructions in the Agent prompt.** Rules that apply across the entire workflow - persona, tone, compliance guardrails - belong in the [Global Node](./global), not repeated in every Agent Node.
**Vague edge conditions.** The LLM picks the edge that best matches the conversation state. Overly broad conditions cause unpredictable routing between nodes.
## Next Steps
Terminate the conversation with a closing message.
Write shared instructions that apply to every node.
Understand how `gathered_context` is built and where it can be referenced.
Evaluate agent performance automatically after each call.
# API Trigger
Source: https://docs.dograh.com/voice-agent/api-trigger
Trigger outbound calls from external systems like n8n, Zapier, or your own backend
The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Dograh generates a unique endpoint URL that external systems can call to start a conversation.
This is useful when you want to trigger calls from your own backend, a CRM, or workflow tools like n8n and Zapier.
## Prerequisites
* A configured [telephony provider](/integrations/telephony/overview) — outbound calls will fail without one
* An [API key](/configurations/api-keys) for authentication
## Finding your trigger URL
When you add an API Trigger node to your workflow, Dograh assigns it a unique UUID. The trigger node exposes two URLs that share this UUID:
* A **production URL** for the published workflow
* A **test URL** for the latest draft
You can copy either URL from the trigger node's settings dialog.
```
POST https://your-dograh-instance/api/v1/public/agent/{uuid} # Production
POST https://your-dograh-instance/api/v1/public/agent/test/{uuid} # Test
```
If you are using the hosted version, replace `your-dograh-instance` with `api.dograh.com`.
### Test vs production
| Mode | URL | Runs |
| - | - | - |
| Production | `/api/v1/public/agent/{uuid}` | The published version of the agent. |
| Test | `/api/v1/public/agent/test/{uuid}` | The latest draft. Falls back to the published version if no draft exists. |
Use the test URL while iterating on changes so production traffic continues to hit the published version.
The production URL only executes a **published** workflow. If you update the workflow but do not publish it, the production trigger will continue to run the older published version.
Once you publish your draft, both URLs run the same definition.
A common pitfall is editing the workflow, saving the draft, and then calling the production trigger URL expecting the new behavior. That will not work until you publish the workflow. Use the test URL to verify draft changes before publishing.
The request body, headers, and response shape are identical for both URLs.
## Making a request
Authenticate by passing your API key in the `X-API-Key` header. The request body requires a `phone_number` and accepts optional `initial_context`, `telephony_configuration_id`, and `from_phone_number_id` fields.
```bash Production URL theme={null}
curl -X POST https://your-dograh-instance/api/v1/public/agent/{uuid} \
-H "Content-Type: application/json" \
-H "X-API-Key: dg_your_api_key" \
-d '{
"phone_number": "+14155550100",
"initial_context": {
"customer_name": "Jane",
"appointment_date": "March 15"
}
}'
```
```bash Test URL theme={null}
curl -X POST https://your-dograh-instance/api/v1/public/agent/test/{uuid} \
-H "Content-Type: application/json" \
-H "X-API-Key: dg_your_api_key" \
-d '{
"phone_number": "+14155550100",
"initial_context": {
"customer_name": "Jane",
"appointment_date": "March 15"
}
}'
```
Use the test URL when you want to verify draft changes before publishing.
### Response
A successful request returns a `workflow_run_id` that you can use to [retrieve run details](/api-reference/runs/get-run), recordings, and transcripts.
```json theme={null}
{
"status": "initiated",
"workflow_run_id": 12345,
"workflow_run_name": "WR-API-7823"
}
```
### Error responses
| Status | Cause |
| - | - |
| `400` | Telephony provider not configured, or call failed to initiate |
| `401` | Missing or invalid API key |
| `403` | API key does not have access to this agent |
| `404` | Trigger not found or not active |
## Initial context
`initial_context` is a JSON object containing any information you want your voice agent to access during the call. You can reference these values in your prompts using [template variables](/voice-agent/template-variables) — values enclosed in `{{` and `}}`.
For example, if your request includes:
```json theme={null}
{
"phone_number": "+14155550100",
"initial_context": {
"user": {
"name": "John"
}
}
}
```
You can reference the user's name in your agent prompt as `{{user.name}}` — in Agent prompts, `initial_context` fields are referenced directly by name (not prefixed with `initial_context.`). See [template variables](/voice-agent/template-variables) for the exact syntax in prompts versus webhook payloads.
See [Context & Variables](/core-concepts/context-and-variables) for more on how data flows through a call.
### Override the greeting for one call
Pass `greeting_override` inside `initial_context` to replace the Start Call node's saved greeting for one API-triggered call. A valid override takes precedence over the saved greeting. If you omit it, Dograh uses the saved greeting; if neither exists, the Start node follows its normal no-greeting behavior.
For a text greeting:
```json theme={null}
{
"phone_number": "+14155550100",
"initial_context": {
"greeting_override": {
"type": "text",
"text": "Hi, please confirm account {{account_id}}."
}
}
}
```
For a pre-recorded greeting, pass the recording's string ID from the Recordings page:
```json theme={null}
{
"phone_number": "+14155550100",
"initial_context": {
"greeting_override": {
"type": "audio",
"recording_id": "callback-welcome"
}
}
}
```
Dograh renders a text override after Pre-Call Data Fetch completes, so the override can reference variables returned by the fetch. The override follows the same playback restrictions as a saved greeting. In particular, static text greetings are not spoken by realtime speech-to-speech models; use an audio override for those configurations.
Pre-Call Data Fetch can also return `greeting_override`. Because fetched context is applied after trigger context, a valid fetched override replaces one supplied by the trigger.
## Choosing a telephony configuration and caller ID
By default, calls are placed through your organization's default outbound [telephony configuration](/integrations/telephony/overview). To route a specific call through a different configuration — for example, to dial out from a regional number — pass `telephony_configuration_id` in the request body.
```json theme={null}
{
"phone_number": "+14155550100",
"telephony_configuration_id": 42
}
```
The id is shown on each row in **Telephony configurations** (`https://app.dograh.com/telephony-configurations` for hosted or `http://localhost:3010/telephony-configurations` for local). The configuration must belong to the same organization as the API Trigger; otherwise the request returns `404`.
To use a specific caller ID from that configuration, also pass `from_phone_number_id`:
```json theme={null}
{
"phone_number": "+14155550100",
"telephony_configuration_id": 42,
"from_phone_number_id": 84
}
```
`from_phone_number_id` is the ID of a phone number configured under the selected telephony configuration. The number must be active and belong to that configuration; otherwise the request returns `400`. You can retrieve configured numbers with [List phone numbers](/api-reference/telephony-configs/phone-numbers/list).
For full endpoint details including all parameters and response fields, see the [API reference](/api-reference/runs/trigger).
# Editing a Workflow
Source: https://docs.dograh.com/voice-agent/editing-a-workflow
Learn the fundamentals of building workflows with nodes, pathways, and conversation flow in the voice agent builder.
## Overview
A workflow is a graph of connected nodes representing conversation stages, with pathways defining agent movement between stages.
## Global Node
Contains instructions applicable across the entire call:
* Company context
* Overall agent goal
* Tone and personality
* Common objection handling
## Node-Level Toggles
### Add Global Prompt
* Recommended to inject [Global Node](/voice-agent/global) instructions into most nodes
### Allow Interruption
* **Default "On"**: Bot stops and responds to user interruption
* **"Off"**: Bot continues speaking, ignoring user input
### Detect Voicemail
* Available only in Start Node
* Automatically disconnects if voicemail detected
## Variable Extraction
Supported in Agent and End Call Nodes:
* Extract structured variables
* Define name, type, and description
* Examples: customer name, budget, interest
## [Webhook Node](/voice-agent/webhook)
* Executed at call end
* Sends payload to specific endpoint
* Use for:
* Storing call data
* Triggering automation
* Syncing with CRMs
## Editing Workflows
* Selectively delete nodes/pathways
* Completely reset workflow
## Pathways and Tool Calls
* Define agent node movement
* Use [tool calls](/voice-agent/tools/http-api) to transition between nodes
* **"tool"** is a reserved keyword for function calls and actions
# End Call
Source: https://docs.dograh.com/voice-agent/end-call
You can use End Call node to configure how the Agent says its final message right before the call is terminated
## Video Tutorial
End Call is the terminal node in a workflow. It fires right before Dograh terminates the connection, giving your agent one last chance to speak. Every path through your workflow must eventually reach an End Call node.
## When it runs
End Call executes after all conversation logic is complete. The agent delivers its closing message, then the call drops.
You can have multiple End Call nodes in one workflow, each reached by a different edge condition. For example, one for a successful outcome and one for a wrong-number path. Each can have its own distinct Prompt.
## Fields
**Name**
Short identifier shown in the canvas and call logs. Use names that describe the ending context, for example "Successful close" or "Polite decline".
**Prompt**
System instructions for what the agent says before the call ends. You can make this conditional by describing different outcomes in the prompt.
For example:
```text theme={null}
If the caller committed to a payment, confirm the arrangement: the
exact amount and expected processing time. If no commitment was made,
thank them for their time and let them know they can call back to
discuss options. Always close professionally.
```
The Prompt cannot reference `gathered_context` - variables extracted by this or earlier nodes are not available in any node's Prompt. To act on extracted data, send it out via a [Webhook node](./webhook) instead.
**Add Global Prompt**
When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default.
**Enable Variable Extraction**
When on, an LLM extraction pass runs after this node's turn to capture structured data from the conversation into `gathered_context`.
## Common mistakes
**Leaving the Prompt empty.** An empty Prompt means the agent says nothing before the line drops. The caller experiences an abrupt silence.
**Routing all paths into one End Call when outcomes need different closing lines.** Multiple End Call nodes are supported. If a wrong-number path and a successful-commitment path need different closing lines, use two End Call nodes with distinct Prompts rather than cramming both into one.
**Agent Nodes that never route to End Call.** Any node without a downstream path to End Call leaves calls in an unresolvable state.
Check every Agent Node for a path to End Call before publishing. Nodes with no downstream connection to End Call will drop the call without a closing message.
## Next Steps
Automatically evaluate calls after they end.
Sync call outcomes to your CRM or external systems.
Configure the conversation logic that routes into End Call.
Learn where `gathered_context` can and cannot be referenced.
# Global Node
Source: https://docs.dograh.com/voice-agent/global
Global Node contains the common prompt that is prepended to the prompt of every node, in which `Add Global Prompt` is turned on.
## Video Tutorial
You should have only one Global node per Voice Agent.
![Add Global Prompt Selector]()
Global Node is a shared prompt layer for your entire workflow. Write your agent's persona, tone guidelines, and compliance rules once in the **Global Prompt** field. Any Agent Node or Start Call node with "Add Global Prompt" turned on will receive this content prepended to its own prompt before each LLM call.
## What goes in the Global Node
Use Global Node for instructions that apply across every step of the conversation:
* **Persona:** Who is the agent? What company do they represent?
* **Tone rules:** How formal or warm should they be?
* **Compliance guardrails:** What must the agent never say?
* **Objection handling:** How should the agent respond to pushback?
Avoid putting step-specific logic here. Instructions like "offer the settlement option after the debtor confirms their identity" belong in the Agent Node prompt, not in Global.
## How it works
Global Node does not run as a separate step in the call. It has no edges and cannot be connected to other nodes. The Global Prompt is silently prepended to each node's prompt where "Add Global Prompt" is enabled.
The LLM sees one combined prompt: the global content first, followed by the node-specific instructions. The caller never notices the seam.
## Enabling it on an Agent Node
Each Agent Node and Start Call node has an "Add Global Prompt" toggle in its settings panel. Nodes with the toggle off receive no global content for that step.
Turn the toggle off selectively when a specific node needs different behavior. An escalation node, for example, may need a more formal tone that should not inherit your default persona.
## Common mistakes
**Putting node-specific logic in the Global Node.** Global is for rules that always apply, not for conversation-specific decisions. Sequence and outcome logic belong in each Agent Node prompt.
**Leaving the Global Node prompt empty with toggles on.** A blank Global Node prepended to every prompt does nothing harmful, but it is also pointless. Either fill it in or leave the toggle off.
**Adding a second Global Node.** Each workflow supports exactly one. Adding a second throws an error.
## Next Steps
Configure how your agent opens the conversation.
Build the core conversation logic that inherits your global prompt.
# Voice Agent Builder
Source: https://docs.dograh.com/voice-agent/introduction
Dograh's voice agent builder lets you design a conversation as a graph of nodes and pathways. Learn the graph model, the available node types, and where to start.
![Create a Voice Agent]()
The Voice Agent Builder is a visual, graph-based editor for designing what your voice agent says and does during a call. Instead of writing one giant prompt, you break the conversation into **nodes** (stages of the conversation) connected by **pathways** (the routes the LLM can take between stages, based on how the conversation is going).
You can create a new agent from the [dashboard](https://app.dograh.com/workflow). Describe whether you need an "Inbound" or "Outbound" agent and your use case — this is sent to an LLM to generate a starting workflow with default prompts and pathways, which you can then edit.
## The graph model
A workflow is a directed graph:
* **Nodes** represent a stage of the conversation or an action (e.g. greet the caller, collect an address, transfer the call).
* **Pathways (edges)** connect nodes and represent the routes the LLM can take depending on what the caller says. The LLM decides at runtime which pathway to follow.
A workflow should have only one **Start Call** node and typically ends at an **End Call** node, with **Agent** nodes and other node types in between. See [Editing a Workflow](/voice-agent/editing-a-workflow) for how nodes, pathways, and node-level toggles fit together.
## Node types
| Node | What it does |
| - | - |
| [**Start Call**](/voice-agent/start-call) | Starts the call and configures the agent's greeting. Should have only one per workflow. |
| [**Agent**](/voice-agent/agent) | Holds the prompt that drives conversation at a given stage; connects to other nodes via pathways. |
| [**Global**](/voice-agent/global) | Common instructions (tone, objection handling) prepended to every node with "Add Global Prompt" enabled. |
| [**QA**](/voice-agent/qa) | Runs automated post-call quality analysis against criteria you define. |
| [**API Trigger**](/voice-agent/api-trigger) | Exposes an endpoint so external systems (n8n, Zapier, your backend) can start outbound calls. |
| [**End Call**](/voice-agent/end-call) | Configures the agent's final message before the call is terminated. A workflow can have multiple End Call nodes, each with a distinct Prompt. |
| [**Webhook**](/voice-agent/webhook) | Sends call results to an external system (CRM, Zapier, n8n) when a run ends. |
Beyond nodes, you can extend an agent with:
* [**Tools**](/voice-agent/tools/introduction) — let the LLM call external APIs, transfer calls, or invoke MCP servers mid-conversation.
* [**Knowledge Base**](/voice-agent/knowledge-base) — attach documents the agent can reference during a call.
* [**Pre-Call Data Fetch**](/voice-agent/pre-call-data-fetch) — enrich context with an HTTP call before the agent starts speaking.
* [**Pre-recorded Audio**](/voice-agent/pre-recorded-audio) — mix in real recordings alongside LLM-generated speech.
* [**Template Variables**](/voice-agent/template-variables) — reference `initial_context` and `gathered_context` values in prompts and payloads.
## Where to start
1. **New to Dograh?** Follow [Editing a Workflow](/voice-agent/editing-a-workflow) to learn the fundamentals of nodes and pathways.
2. **Want to test immediately?** Use a [Web Call](/core-concepts/calls-and-runs#web-calls) from the agent editor — no telephony setup required.
3. **Ready to go live?** Configure a [telephony provider](/integrations/telephony/overview) and add an [API Trigger](/voice-agent/api-trigger) or set up inbound routing.
4. **Need the call to hit your systems?** Add a [Webhook](/voice-agent/webhook) node to sync results to your CRM or automation tool.
5. **Want to embed the agent on a website?** See [Add to Website](/voice-agent/add-to-website).
## Related
* [Core Concepts: Workflows and Agents](/core-concepts/workflows-and-agents)
* [Core Concepts: Context & Variables](/core-concepts/context-and-variables)
* [Editing a Workflow](/voice-agent/editing-a-workflow)
# Knowledge Base
Source: https://docs.dograh.com/voice-agent/knowledge-base
Upload documents that your voice agent can reference during live conversations to provide accurate, context-aware responses.
The Knowledge Base lets you upload documents that your voice agents can reference during conversations. Instead of encoding all information into prompts, you can provide source documents and let the agent retrieve relevant content on the fly.
An embedding API key (configured in **AI Models Configuration → Embedding**) is required for **Chunked Search** mode. **Full Document** mode does not require embeddings.
![Embedding Configuration]()
## How It Works
1. You **upload** a document (PDF, DOCX, TXT, or JSON) to the Knowledge Base
2. You **choose a retrieval mode** — Full Document or Chunked Search
3. Dograh **processes** the document based on the selected mode
4. You **attach** the document to one or more workflow nodes
5. During a call, the agent **retrieves** information from the document and uses it to generate accurate responses
## Supported File Types
| Format | Extension |
| - | - |
| PDF | `.pdf` |
| Word | `.docx`, `.doc` |
| Text | `.txt` |
| JSON | `.json` |
Maximum file size: **5 MB**
## Uploading Documents
1. Go to **Knowledge Base Files** in the dashboard
2. Click **Upload New** or drag and drop a file
3. Choose a **retrieval mode** (see below)
4. Click **Upload & Process** — the document will be processed according to the selected mode
### Retrieval Modes
When uploading a document, you choose how the agent retrieves information from it:
The entire document text is provided to the agent whenever it queries the knowledge base. No chunking or embedding is performed.
**Best for:** menus, price lists, FAQs, short reference sheets, and any document where the agent needs access to all the information at once.
Full Document mode does not require an embedding API key.
The document is split into smaller chunks and indexed with vector embeddings. When the agent queries the knowledge base, only the most relevant chunks are returned.
**Best for:** large documents like policies, manuals, or contracts where only a portion is relevant to any given question.
## Attaching Documents to Nodes
Once a document is processed, you can attach it to any **Start Call** or **Agent** node in your workflow:
1. Open the node edit dialog
2. Scroll to the **Knowledge Base Documents** section
3. Select one or more documents for the agent to reference
The agent will only search documents attached to the current node, so attach only the documents relevant to that conversation step.
## Best Practices
* **Use Full Document for small reference files** — menus, price lists, and FAQs work best when the agent sees the entire document
* **Use Chunked Search for large documents** — policies, manuals, and contracts are too large to fit in context, so chunked retrieval finds the relevant sections
* **Keep documents focused** — a single topic per document produces better retrieval results than a large multi-topic file
* **Use clear, structured content** — headings, lists, and short paragraphs help the chunking process
* **Attach selectively** — only attach documents relevant to a specific node rather than attaching everything everywhere
* **Keep documents up to date** — re-upload when source information changes to avoid stale answers
# Pre-Call Data Fetch
Source: https://docs.dograh.com/voice-agent/pre-call-data-fetch
Fetch customer data from your CRM or ERP before the call starts, so your voice agent can greet callers by name and reference their account details.
Pre-Call Data Fetch allows you to enrich the call context with external data before the voice agent starts speaking. Configure it on the [**Start Call**](/voice-agent/start-call) node for every call, inbound calls only, or outbound calls only. While the response is loading, the caller hears a ring-back tone. Once the data arrives, it is merged into the call's [initial context](/core-concepts/context-and-variables#initial_context) and becomes available as template variables in your prompts and greetings.
## How It Works
1. A call arrives (inbound) or is initiated (outbound).
2. Dograh sends a **POST** request to your configured endpoint with a standardized payload.
3. The caller hears a ring-back tone while waiting for the response.
4. Your API responds with a JSON object containing an `initial_context` object.
5. The variables are merged into the call's initial context.
6. The voice agent starts with full access to the fetched data via `{{variable_name}}` syntax.
## Configuration
Open the [**Start Call**](/voice-agent/start-call) node editor and expand **Advanced Settings**. Choose a **Pre-Call Data Fetch** mode and configure the endpoint when the mode is not disabled:
| Field | Description |
| - | - |
| **Pre-Call Data Fetch** | **Disabled**, **Always**, **Inbound calls only**, or **Outbound calls only**. Calls without an inbound or outbound direction run the fetch only in **Always** mode. |
| **Endpoint URL** | The URL Dograh will send the POST request to. |
| **Authentication** | Optional credential for authenticating the request. Supports API key, bearer token, basic auth, and custom header. |
## Request Format
Dograh sends a `POST` request with the following JSON payload:
```json theme={null}
{
"event": "call_inbound",
"call_inbound": {
"agent_id": 123,
"from_number": "+12137771234",
"to_number": "+12137771235"
}
}
```
| Field | Description |
| - | - |
| `event` | Always `"call_inbound"`. |
| `call_inbound.agent_id` | The workflow (agent) ID. |
| `call_inbound.from_number` | The caller's phone number (`caller_number` from initial context). |
| `call_inbound.to_number` | The called phone number (`called_number` from initial context). |
The `Content-Type` header is set to `application/json`. If you configured a credential, the corresponding authentication header is included.
## Expected Response Format
Your API should return a **JSON object** with a `2xx` status code. The variables to inject into the call context should be placed inside the `initial_context` key:
```json theme={null}
{
"call_inbound": {
"initial_context": {
"customer_name": "Jane Doe",
"account_status": "active",
"loyalty_tier": "gold",
"open_tickets": 2
}
}
}
```
You can also place `initial_context` at the top level:
```json theme={null}
{
"initial_context": {
"customer_name": "Jane Doe",
"account_status": "active"
}
}
```
The legacy `dynamic_variables` key is still accepted as a drop-in alias for `initial_context`, so existing integrations keep working without any changes. Use `initial_context` for new integrations. If a response contains both keys, `initial_context` takes precedence.
After the response is received, you can reference these values anywhere template variables are supported:
* **Greeting**: `Hello {{customer_name}}, thank you for calling!`
* **Prompt**: `The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.`
If the response is not a valid JSON object, does not contain `initial_context` (or the legacy `dynamic_variables`), or the request fails or times out, the call proceeds normally without the additional context. The pre-call fetch never blocks or fails a call.
## Nested Variables
If your `initial_context` contains nested objects, you can access them using dot notation:
```json theme={null}
{
"call_inbound": {
"initial_context": {
"customer": {
"name": "Jane Doe",
"address": {
"city": "Los Angeles"
}
}
}
}
}
```
Access in prompts as `{{customer.name}}` and `{{customer.address.city}}`.
## Timeout
The request has a **10-second timeout**. If your API does not respond within this window, the call proceeds without the fetched data. Design your endpoint to respond as quickly as possible to minimize the ring-back tone duration.
## Testing with Test Calls
When a real phone call comes in, the `caller_number` and `called_number` context variables are automatically set by the telephony provider and included in the pre-call data fetch request as `from_number` and `to_number`. However, when you make a test call — either a **web call** (WebRTC) or a **phone test call** from the workflow editor — these variables are not available by default.
To simulate telephony data during testing:
1. Open your workflow and go to **Settings**.
2. Under **Context Variables**, add the following variables:
* `caller_number` — set to a phone number you want to simulate as the caller (e.g., `+12137771234`).
* `called_number` — set to the number that would be dialed (e.g., `+12137771235`).
3. Save the settings.
Now when you make a test call (web or phone), these values will be sent in the pre-call data fetch request to your endpoint, allowing you to test the full flow as if a real inbound call were coming in.
These context variables are only used during test calls from the workflow editor. On production inbound calls and campaign outbound calls, the actual telephony data is used and these values are ignored.
## Example Integration
A simple Node.js endpoint that looks up a customer by phone number:
```javascript theme={null}
app.post("/dograh/pre-call", async (req, res) => {
const { call_inbound } = req.body;
const customer = await db.customers.findOne({
phone: call_inbound.from_number,
});
if (!customer) {
return res.json({});
}
res.json({
call_inbound: {
initial_context: {
customer_name: customer.name,
account_status: customer.status,
loyalty_tier: customer.tier,
},
},
});
});
```
# Pre-recorded Audio
Source: https://docs.dograh.com/voice-agent/pre-recorded-audio
Build hybrid voice agents that combine pre-recorded audio with dynamic text generation for lower latency, reduced TTS costs, and natural-sounding conversations.
Custom recordings allow you to build **hybrid voice agents** that use your own pre-recorded audio for key parts of the conversation, while falling back to LLM-generated speech (via a cloned voice) for dynamic responses. This gives you the best of both worlds — the emotional depth of real human speech and the flexibility of AI-generated dialogue.
## Why use custom recordings?
* **Reduced TTS cost** — Pre-recorded audio is played directly, so you are not charged for TTS synthesis on those segments.
* **Emotional variance** — Real recordings carry natural intonation and emotion that TTS cannot fully replicate.
* **Lower latency** — Playing a pre-recorded clip is faster than synthesizing text at runtime.
## Prerequisites
* A TTS provider that supports **voice cloning** (e.g., Cartesia, ElevenLabs, or Deepgram).
* An API key for your chosen TTS provider, configured in [Voice settings](/configurations/voice).
## Step 1: Clone your voice
Clone your voice with your TTS provider so that dynamically generated speech sounds similar to your recordings. For example, with Cartesia:
1. Go to Cartesia and navigate to **Instant Clone**.
2. Record a short audio clip (up to 10 seconds) of your voice.
3. Give the clone a name and select your language.
4. Copy the **Voice ID** — you will need it in the next step.
You can use any TTS provider that supports voice cloning. The steps will vary by provider, but the key output is always a **Voice ID** tied to your cloned voice.
## Step 2: Configure the cloned voice in Dograh
1. Go to your agent's **Model Configuration** in the Dograh dashboard.
2. Under voice settings, select **Add Voice ID manually**.
3. Paste the Voice ID from your cloned voice.
4. Make sure the **provider** matches where you cloned your voice (e.g., Cartesia).
5. Enter the provider's API key if you haven't already.
6. Save the configuration.
## Step 3: Upload recordings
Navigate to the **Recordings** page in the Dograh dashboard. Recordings are shared across all agents in your organization. You can either upload pre-recorded audio files or record directly in the browser.
For each recording:
1. Click **Upload Recording**.
2. Choose an audio file or click **Record** to record in the browser.
3. Verify the transcription is correct — edit it if needed.
4. Click **Upload**.
You can rename a recording's ID at any time by clicking the edit icon next to it in the recordings list.
## Step 4: Build the workflow
Open your agent's workflow and write the conversation flow in natural language. To insert a recording, type **`@`** in the prompt editor — this will show a list of all available recordings in your organization.
For any user question that falls outside your recordings, the agent automatically generates a dynamic response using the LLM, which is then synthesized using your cloned voice via TTS.
## Tips for best results
* **Record in a quiet environment** to improve audio quality and consistency with the cloned voice.
* **Use pro cloning services** (when available) and provide more sample audio for a higher-quality voice clone.
* **Keep recordings concise** — short, focused clips work best for specific conversation moments.
* **Review call recordings** after testing to identify where the transition between pre-recorded and dynamic audio can be improved.
# QA
Source: https://docs.dograh.com/voice-agent/qa
QA node allows you to run post-call quality analysis on your Voice Agent runs
## Video Tutorial
The QA node runs an LLM quality review on the call transcript after each conversation ends. Use it to score agent performance, flag compliance issues, and surface patterns across calls, without listening to recordings manually.
## When it runs
QA Node runs post-call only. It is not part of the live call flow - it reads the completed transcript after the conversation ends. It has no edges and cannot connect to any other node in the workflow.
This means QA does not affect call behavior. It only measures it.
## Where it sits on the canvas
Add QA Node anywhere on the canvas. It does not need to connect to other nodes - most builders place it off to the side to make clear it is a standalone evaluator. The node runs automatically for every eligible call once the workflow is published.
## Configuring the System Prompt
The core configuration is a single **System Prompt**: instructions to the reviewer LLM that describe how to evaluate each call. The LLM reads the transcript and returns a structured JSON result.
The default prompt already covers common quality dimensions out of the box:
* **Tags**: named issues detected in the transcript. The default tag set includes `DEAD_AIR`, `USER_FRUSTRATED`, `ASSISTANT_IN_LOOP`, `ASSISTANT_REPLY_IMPROPER`, `USER_NOT_UNDERSTANDING`, `HEARING_ISSUES`, `UNCLEAR_CONVERSATION`, `USER_REQUESTING_FEATURE`, `ASSISTANT_LACKS_EMPATHY`, and `USER_DETECTS_AI`
* **Call quality score**: 1-10 rating
* **Overall sentiment**: positive, neutral, or negative
* **Summary**: 1-2 sentence description of the call segment
You can replace the default System Prompt with your own instructions when you need domain-specific evaluation. Write the prompt as instructions to the QA reviewer LLM, and specify the JSON structure you want it to return.
For compliance use cases, for example:
```text theme={null}
You are a compliance reviewer for a debt collection workflow.
Review the transcript and return a JSON object with the following fields:
- "identity_verified": true or false — did the agent confirm the caller's identity before discussing the account?
- "options_presented": true or false — did the agent offer all three payment options before accepting a decision?
- "tone_score": 1-5 — how calm and professional was the agent throughout?
- "summary": one sentence describing the call outcome.
```
Be specific about what counts as a pass or a valid score. Include the exact behaviors you want the LLM to look for. Vague instructions produce inconsistent results across calls.
## Additional settings
| Setting | Default | What it does |
| - | - | - |
| Enabled | On | Toggle to disable QA without removing the node |
| Use Workflow's LLM | Off | When on, uses the same LLM configured for the workflow instead of the default QA model |
| Minimum Call Duration (seconds) | 15 | Calls shorter than this are skipped |
| Include Voicemail Calls | Off | When off, voicemail calls are skipped |
| Sample Rate (%) | 100 | Run QA on a percentage of calls rather than all of them |
## Viewing QA Results
After a call completes, the QA analysis runs automatically. You can view the results on the **Run Detail** page for each individual run.
Open a run and scroll to the **QA Analysis** section. The result shows the full JSON output your QA System Prompt requested - tags, scores, sentiment, and summary for the default prompt, or whatever structure you defined.
## Common mistakes
**Expecting QA to affect the live call.** QA Node is read-only at runtime. It evaluates what happened; it does not change what happens.
**Connecting QA Node to other nodes.** QA has no edges. Drawing a connection from QA to another node is not possible - edges will snap back when you try.
**Writing a vague System Prompt.** "Was the agent good?" produces unhelpful scores. Define specific, observable behaviors and the exact JSON fields you want back.
**Not specifying output format.** The LLM follows your instructions, but if you do not specify a return format, the output may be inconsistent across calls. Always describe the exact JSON structure in the System Prompt.
## Next Steps
Configure the conversation logic that QA evaluates.
Send call outcomes to external systems after the call ends.
Learn how `gathered_context` is built during the call.
Configure the final message before the call drops.
# Start Call
Source: https://docs.dograh.com/voice-agent/start-call
You can use Start Call node to Start the call and configure how Agent greets the user when the conversation starts.
## Video Tutorial
You should have only one Start Call node per Voice Agent.
Start Call is the entry point for every conversation. It fires the moment a call connects and controls the first thing your agent says. Every workflow must have exactly one.
## When it runs
Start Call executes before any Agent Node. No other node can precede it in the call flow.
After Start Call completes, the conversation moves to the next node - typically your first Agent Node. If the caller hangs up immediately or reaches a wrong-number condition, Start Call can route directly to End Call instead.
## Fields
**Name**
Short identifier shown in the canvas and call logs. Has no runtime effect on what the agent says.
**Greeting Type**
Whether the greeting is spoken via TTS from text or played from a pre-recorded audio file. Defaults to "Text (TTS)".
**Greeting Text**
Optional fixed line spoken via TTS the moment the call connects, before the AI's conversational turn begins. Supports `{{template_variables}}`. Leave empty to skip the greeting and let the Prompt handle the opening.
For example:
```text theme={null}
Hi {{initial_context.debtor_name}}, this is Alex from Apex Recovery Solutions.
```
See [Pre-recorded Audio](./pre-recorded-audio) to use a recording file instead of TTS text.
**Prompt** (required)
System instructions for the AI's opening conversational turn. Runs after Greeting Text (if set). Supports `{{initial_context.field_name}}` and variables from Pre-Call Data Fetch.
For example:
```text theme={null}
After greeting the caller, confirm you are speaking with
{{initial_context.debtor_name}}. If they confirm, move to Debt Disclosure.
If they say wrong number, move to End Call.
```
If a variable referenced in Greeting Text or Prompt is missing from the API request payload, the agent speaks the raw placeholder out loud - for example, "Hi `{{initial_context.debtor_name}}`" - instead of the caller's name. Test with a complete payload before publishing.
**Allow Interruption**
When on, the caller can interrupt the agent mid-utterance. Off by default on Start Call.
**Add Global Prompt**
When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default.
**Delayed Start**
When on, the agent waits before speaking after the call connects. Useful for outbound calls where the called party needs a moment to settle. Duration can be set between 0.1 and 10 seconds.
**Enable Variable Extraction**
When on, an LLM extraction pass runs after this node's turn to capture structured data from the conversation into `gathered_context`.
**Tools**
Functions the agent can call during the opening turn. Add via the "HTTP & Tools" tab (HTTP API and built-in tools) or the "MCP" tab (MCP server tools).
**Knowledge Base Documents**
Documents the agent can reference during this step. Attach via "Manage Documents."
**Pre-Call Data Fetch**
Choose whether Dograh makes a POST request before **all**, **inbound**, or **outbound** calls, or leave the fetch **disabled**. Dograh merges the JSON response into the call context as template variables before rendering the greeting and Start-node prompt.
## Outgoing edges
Start Call can have multiple outgoing edges, each with a user-defined label and a condition written in plain language. The LLM reads the conversation and picks the edge whose condition best matches.
Each edge needs two things:
* **Label:** a short name shown on the canvas (you define this)
* **Condition:** the instruction that tells the LLM when to take this edge
A typical Start Call has two edges:
```text theme={null}
Label: "caller confirmed"
Condition: "The caller confirmed they are the right person and are ready to continue."
Label: "wrong number"
Condition: "The caller says this is the wrong number, asks not to be called, or refuses to confirm their identity."
```
You can add more edges if the opening turn needs to branch further.
## Common mistakes
**Leaving Greeting Text empty with no Prompt.** If both Greeting Text and Prompt are empty, the agent says nothing at the start of the call. The caller hears silence.
**Confusing Node Name with the agent's spoken name.** Node Name is a canvas label for your own reference. The name the agent introduces itself as comes from the Greeting Text or Prompt content, or the persona you define in the [Global Node](./global).
**Adding a second Start Call node.** Each workflow has one entry point. A second Start Call node will throw an error.
## Next Steps
Build the core conversation logic that follows the greeting.
Set persona and tone rules that apply across all nodes.
Learn how `initial_context` variables flow through a call.
Configure the agent's final message before the call drops.
# Template Variables
Source: https://docs.dograh.com/voice-agent/template-variables
You can use Template Variables in your prompts for your Agent nodes, or when constructing the payload for the Webhook Node
### Template Rendering
You reference template variables with `{{double_brace}}` syntax. The data comes from [`initial_context`](/core-concepts/context-and-variables#initial_context) — set via the [API Trigger](/voice-agent/api-trigger), a [campaign](/core-concepts/campaigns) sheet, or a [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch) that enriches the context when the call starts — and, in Webhook payloads only, from [`gathered_context`](/core-concepts/context-and-variables#gathered_context) (variables extracted during the call).
**The syntax depends on where you use it:**
| Where | `initial_context` | `gathered_context` |
| - | - | - |
| Agent node prompts | `{{field_name}}` (referenced directly) | Not available |
| Webhook Node payloads | `{{initial_context.field_name}}` | `{{gathered_context.field_name}}` |
#### Agent node prompts
In an Agent node prompt, reference each `initial_context` field **directly by name**. Nested values are supported with dot notation.
Example: if the initial context is
```json theme={null}
{
"initial_context": {
"user": {
"name": "John"
}
}
}
```
write your prompt to access the user's name as below:
Prompt: `You are Alice, who is talking to {{user.name}}.`
Variables extracted during the call (`gathered_context`) are **not** available in Agent prompts — a prompt can only reference `initial_context` fields. To act on extracted data, send it to a [Webhook Node](/voice-agent/webhook).
#### Webhook Node payloads
When constructing a [Webhook Node](/voice-agent/webhook) payload, the context objects are nested under their names, so reference them with the `initial_context.` and `gathered_context.` prefixes:
Payload value: `{{initial_context.user.name}}` or `{{gathered_context.call_disposition}}`
### Using Template Variables for Testing
Template variables defined in your workflow **Settings > Context Variables** are included in test calls (both web and phone) made from the workflow editor. This is useful for simulating data that would normally come from telephony or an API trigger.
![Template Variables panel in workflow Settings, showing a customer_name variable and fields to add new key/value pairs]()
For example, you can set `caller_number` and `called_number` as context variables to test [Pre-Call Data Fetch](/voice-agent/pre-call-data-fetch#testing-with-test-calls) without needing a real inbound call.
Browser voice tests are treated as inbound calls by default. To simulate an outbound call with web, set the `direction` template-context variable to `outbound`.
These context variables are only used during test calls from the workflow editor. On production inbound calls and campaign outbound calls, the actual telephony data is used and these values are ignored.
### Nodes
Dograh Voice Agents are composed of various nodes. These nodes can provide instructions to the voice agent, help you setup a [trigger](/voice-agent/api-trigger) where you can trigger the voice agent to call someone, or help you setup a [webhook](/voice-agent/webhook), where you can update the results of the call in your CRM or trigger a downstream workflow in n8n. In the next steps, we will be documenting the nodes that you can use in building the voice agent.
# Call Transfer
Source: https://docs.dograh.com/voice-agent/tools/call-transfer
Transfer live telephony calls using static destinations, ordered context mappings, or dynamic resolution.
The Call Transfer tool lets your AI agent transfer an active telephony call to a phone number or SIP endpoint. You can configure a fixed destination, select one with ordered context rules, use a template from call context, or resolve the destination at transfer time by calling your HTTP endpoint.
Use this tool when the caller should speak to a human operator, department, escalation queue, support queue, or another phone system.
To hand the caller to **another Dograh agent** rather than to a phone number, use [Transfer to Agent](/voice-agent/tools/transfer-agent) instead. It carries conversation history as a labeled transcript across the handoff and works on web calls as well as telephony.
## Supported providers
Call transfer is available for telephony calls using Twilio, Telnyx, or Asterisk ARI providers.
Web calls do not support call transfer.
## How call transfer works
When the LLM decides a transfer is needed, it calls the Call Transfer tool. Dograh resolves the destination, validates the transfer setup, and then starts the provider transfer.
For a successful transfer:
1. The agent calls the Call Transfer tool.
2. Dograh resolves the destination from static configuration, ordered context mappings, or a dynamic HTTP resolver.
3. Dograh optionally plays a pre-transfer message.
4. Dograh starts dialing the destination through the telephony provider.
5. The caller hears hold music while the destination leg is connecting.
6. When the destination answers, Dograh connects the caller and ends the AI agent's involvement.
By default, the receiving person joins without a conversation summary. For Twilio calls, you can enable a spoken introduction before the two parties are connected.
## Transfer introduction
In your Call Transfer tool, enable **Play a transfer introduction to both parties**. This setting is off by default and supports Twilio calls using your configured TTS provider. Other telephony providers, external PBX transfers, and realtime speech-to-speech agents skip the introduction and use their usual transfer behavior.
The default instructions ask for a short summary of the caller's request, essential details, and language preference. Edit **Introduction instructions** to change what is included or request a language, such as Brazilian Portuguese. Your configured TTS voice must support that language.
Dograh uses the current conversation, including history from earlier agents, and generates audio with the active agent's TTS configuration. After the destination answers, each party hears the same recording on their own line. Speaking does not interrupt playback. They can talk to each other once both have finished hearing it; playback may start at slightly different times on the two lines.
Preparation has an eight-second budget while the caller hears hold music. Introductions are limited to 25 words and 15 seconds of audio. If preparation fails or exceeds its budget, the transfer proceeds without the introduction. If Twilio cannot fetch or play the audio, a fallback connects the parties without it.
Twilio fetches the recording from your publicly reachable Dograh backend using a temporary URL. The recording expires after five minutes; no public storage bucket is required.
Both the caller and whoever answers the destination hear the introduction. For a ring group, that can be any member who picks up. Include only details you intend to share with both parties.
## Destination source
You must choose one destination source for each Call Transfer tool.
### Static / Template
Use this when the transfer destination is already known before the transfer happens.
Static destinations can be:
* A fixed E.164 phone number, such as `+1234567890`
* A SIP endpoint, such as `PJSIP/sales-queue`
* A template value from context, such as `{{initial_context.transfer_destination}}`
This is the simplest option for fixed support lines, fixed departments, or cases where the destination is provided before the call starts.
### Context Mapping
Use this when a finite set of context values should select the transfer destination. You can add multiple rules and order them. Dograh evaluates the rules from top to bottom and uses the first route whose value matches, ignoring case and surrounding whitespace.
For each rule, enter a context field and one or more value-to-destination mappings. An unprefixed field such as `department` reads `gathered_context.department` first and falls back to `initial_context.department` when the gathered value is absent. You can use `gathered_context.department` or `initial_context.department` when you want to read only one context.
Mapped and fallback destinations can be:
* A VICIdial in-group, such as `sales`
* A SIP endpoint, such as `PJSIP/1001`
* An E.164 PSTN number, such as `+1234567890`
* A context template, such as `{{initial_context.transfer_destination}}`
Dograh performs final variable extraction before evaluating context mappings. If no rule matches, it uses the optional fallback destination. If there is no fallback, or a selected destination template resolves to an empty value, the transfer fails before dialing and the agent can continue the call.
### Dynamic HTTP Resolver
Use this when the destination must be decided during the conversation.
Dograh sends a `POST` request to your resolver endpoint before starting the transfer. Your endpoint returns the destination and may return a custom message to play before dialing.
Common use cases:
* Route by region, timezone, or language
* Look up the right account team in your customer system
* Route by customer tier or account status
* Route by issue type, language, or department
* Use business logic from your backend instead of hardcoding numbers in Dograh
## Dynamic resolver request
The resolver request body is a flat JSON object.
Dograh builds it from:
* **LLM parameters**: values the agent extracts from the conversation when it calls the transfer tool
* **Preset parameters**: values Dograh injects from fixed values or templates such as `{{initial_context.account_id}}` or `{{gathered_context.billing_issue_type}}`
If both define the same key, preset parameters take precedence.
Example request body:
```json theme={null}
{
"account_id": "acct_123",
"plan": "enterprise",
"billing_issue_type": "invoice_dispute"
}
```
Dograh does not send the full conversation transcript to the resolver. Add the specific values you need as LLM parameters or preset parameters.
## Dynamic resolver response
Your resolver must return a JSON object with `transfer_context.destination`.
`transfer_context.custom_message` is optional.
```json theme={null}
{
"transfer_context": {
"destination": "+1234567890",
"custom_message": "Please wait while I connect you with our enterprise billing team."
}
}
```
Follow this response shape exactly. Dograh reads specific keys from the resolver response. For dynamic transfer resolution, an invalid response does not fall back silently: the transfer fails before dialing.
Field behavior:
* `destination`: Required. E.164 phone number or SIP endpoint.
* `custom_message`: Optional. If returned, this message is played before the provider transfer starts.
If the resolver fails, times out, returns invalid JSON, or omits `transfer_context.destination`, the transfer fails gracefully and the agent can continue handling the caller.
## Dynamic resolver configuration
When using a dynamic resolver, configure:
* **Resolver URL**: HTTPS or HTTP endpoint Dograh calls with `POST`
* **Resolver Timeout**: How long Dograh waits for the resolver response
* **Resolver Wait Message**: Optional message spoken while Dograh waits, such as "One moment while I find the right team."
* **LLM Parameters**: Values the agent should extract from the conversation, such as `billing_issue_type` or `requested_department`
* **Preset Parameters**: Values injected by Dograh from context or fixed values
* **Custom Headers**: Static headers sent to your resolver endpoint
* **Credential**: Optional saved credential used to authenticate the resolver request
The dynamic resolver uses `POST` only. If you need custom backend behavior, implement it behind your resolver endpoint and return the expected `transfer_context` shape.
## Pre-transfer messages
Call Transfer supports a common pre-transfer message setting for static, context-mapped, and dynamic destinations.
For static transfers:
1. Dograh resolves the static or template destination.
2. Dograh plays the configured pre-transfer message, if any.
3. Dograh starts the provider transfer.
For dynamic transfers:
1. Dograh may play the resolver wait message while calling your resolver.
2. If the resolver returns `custom_message`, Dograh plays that message.
3. If the resolver does not return `custom_message`, Dograh uses the configured pre-transfer message.
4. Dograh starts the provider transfer.
Resolver `custom_message` overrides the configured pre-transfer message for that transfer attempt.
## Transfer timeout
Transfer timeout is the maximum time Dograh waits for the destination to answer after the provider transfer starts.
This timeout applies to static, context-mapped, and dynamic transfers.
The resolver timeout is separate. It controls only how long Dograh waits for your HTTP resolver before dialing starts.
## Destination formats
### Twilio and Telnyx
Use E.164 phone numbers:
```text theme={null}
+1234567890
```
The number must be reachable from your telephony provider.
### Asterisk ARI
Use SIP endpoints:
```text theme={null}
PJSIP/sales-queue
SIP/1001
```
Asterisk ARI transfers only work with SIP endpoints configured on your Asterisk server. External phone numbers require PSTN trunk configuration in your Asterisk setup.
## Example: route enterprise billing calls
Use this setup when the agent identifies a billing issue and your backend decides whether to route the caller to standard billing, enterprise billing, or collections.
Configure LLM parameters:
```json theme={null}
[
{
"name": "billing_issue_type",
"type": "string",
"description": "The billing issue the caller needs help with, such as invoice_dispute, payment_failed, refund_request, or plan_change.",
"required": true
},
{
"name": "requested_department",
"type": "string",
"description": "The department the caller is asking for, if they explicitly mention one.",
"required": false
}
]
```
Configure preset parameters:
```json theme={null}
[
{
"name": "account_id",
"type": "string",
"value_template": "{{initial_context.account_id}}",
"required": true
},
{
"name": "plan",
"type": "string",
"value_template": "{{initial_context.plan}}",
"required": true
}
]
```
Your resolver receives:
```json theme={null}
{
"billing_issue_type": "invoice_dispute",
"requested_department": "billing",
"account_id": "acct_123",
"plan": "enterprise"
}
```
Your resolver returns:
```json theme={null}
{
"transfer_context": {
"destination": "+18005550199",
"custom_message": "Please wait while I connect you with our enterprise billing team."
}
}
```
## Best practices
* Keep resolver latency low. Aim for 2-3 seconds.
* Use a resolver wait message if the resolver may take noticeable time.
* Send only the parameters your resolver needs.
* Prefer preset parameters for values already available in `initial_context` or `gathered_context`.
* Put the most specific context-mapping rules first and configure a fallback only when it is safe for every unmatched value.
* Make LLM parameter descriptions explicit so the agent knows what to extract.
* Test both successful transfer and resolver failure paths before going live.
* Keep destination validation and routing logic in your backend when routing depends on account data or business rules.
## Troubleshooting
### The transfer tool is not called
Check that the tool is attached to the correct node and that the node prompt clearly tells the agent when to transfer.
### Static transfer fails with no destination
Static mode requires a configured destination. Use a fixed destination or a template that resolves to a non-empty value.
### Dynamic transfer fails before dialing
Check the resolver response. It must include:
```json theme={null}
{
"transfer_context": {
"destination": "+1234567890"
}
}
```
Also verify the resolver URL, authentication headers, credential, and timeout.
### Resolver receives missing parameters
Confirm the parameter is configured as either:
* an LLM parameter, if the agent should extract it from the conversation
* a preset parameter, if Dograh should inject it from context
For known context values, prefer preset parameters like `{{initial_context.account_id}}` or `{{gathered_context.billing_issue_type}}`.
### Destination does not connect
Verify that the phone number or SIP endpoint is valid and reachable from the configured telephony provider.
# End Call
Source: https://docs.dograh.com/voice-agent/tools/end-call
Allow your AI agent to terminate calls when conversations reach a natural conclusion or specific conditions are met.
The End Call tool enables your AI agent to terminate calls programmatically when conversations reach a natural conclusion, specific conditions are met, or when instructed by the caller.
## How It Works
The End Call tool provides a clean way to terminate conversations:
1. **Agent Decision**: Your AI agent determines the call should end based on conversation context
2. **Optional Message**: Agent can provide a closing message before ending the call
3. **Clean Termination**: Call is terminated gracefully through the telephony provider
4. **Call Disposition**: Call disposition is updated in the system
## Configuration
### Basic Settings
* **End Message**: Optional closing message played before termination
* **Reason**: Optional reason code for call termination tracking
## Agent Usage
Your AI agent can end calls during conversations:
```
end_call(message="Thank you for calling. Have a great day!", reason="conversation_complete")
```
Common scenarios:
* Conversation has reached natural conclusion
* User explicitly requests to end the call
* Agent has completed all requested tasks
* Call timeout or error conditions
# HTTP API
Source: https://docs.dograh.com/voice-agent/tools/http-api
Create REST API tools that your AI agent can invoke during conversations to integrate with external systems.
HTTP API tools allow you to attach extrernal REST API calls directly to workflow nodes, enabling your voice agents to call any internal or external system during live conversations based on LLM judgment and your prompts. This works similar to function calling on any agentic platform and is 100% open source and fully customizable.
## Video Tutorial
## What is an HTTP API Tool?
An HTTP API Tool is a REST API definition that the LLM can invoke at runtime.
**Typical use cases:**
* Call your own backend endpoints
* Trigger n8n automations
* Sync data with a CRM
* Fetch data from external APIs (weather, pricing, availability, etc.)
* Write/update/read data using Rest API
**The LLM decides:**
* which tool to call
* when to call it
* what parameters to send
**All based on:**
* Your prompts: node-level instructions in simple english (or any language)
* Tool name
* Tool description
* Parameter definitions
## Defining an HTTP API Tool ### 1. Tool Name * Must be clear and action-oriented. * **Examples:** `capture_lead_interest`, `fetch_weather`, 'create\_crm\_contact', etc ### 2. Tool Description * Extremely important * This is how the LLM decides **when** to use the tool. * Write it in plain, explicit English. **Bad:** "API to capture data" **Good:** "This tool is to capture interest. Use this tool when the user clearly expresses interest in the product or wants to be contacted"![Tool Description Example]()
### 3. Endpoint Configuration
* Full URL (**must include `http://` or `https://`**)
* Supports **REST** methods
Common mistake: forgetting https\:// in the URL.
### 4. Authentication & Headers * Add custom authentication * Add custom headers * Works with internal services and third-party APIs
### 5. Parameters Each parameter must have: * Name * Type * Description * Required/Optional flag **Parameter descriptions matter more than types.** Guidelines: * Start with string parameters when possible * Be explicit in what the value represents * Mark only truly mandatory fields as required Example: * interest (string): "Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false."![Parameter Example]()
### Send the workflow run ID
Every call and text chat has a reserved `initial_context.workflow_run_id` that external context cannot override. To send it, add a **Preset Parameter**:
| Field | Value |
| - | - |
| Name | `workflow_run_id` |
| Type | `number` |
| Value template | `{{initial_context.workflow_run_id}}` |
| Required | Yes |
The preset is sent in the request body for POST/PUT/PATCH or query parameters for GET/DELETE. With a custom body template, include `{{workflow_run_id}}` where needed. For UI tool tests, enter a sample numeric value.
### Body format
POST, PUT, and PATCH requests send a JSON body (`application/json`) by default. Some APIs only accept form-encoded bodies and reject JSON. For those, set **Body Format** on the Parameters tab to **Form-encoded** (`body_format: "form"` in the API). Parameters are then sent as `application/x-www-form-urlencoded` fields:
* A list value repeats the field name once per item, e.g. `To=a&To=b`.
* An object value is sent as a JSON string, because form fields cannot nest.
A body template works the same way in either format. Its top-level keys become the form fields.
### What the agent receives
The agent gets the response's `status_code` and parsed body as `data`. `status` is `success` for responses below 400, and `error` for any 4xx or 5xx response, so a rejected request is never reported to the agent as a success. Timeouts and connection failures also come back with `status: "error"` and an `error` message.
## Attaching Tools to Workflow Nodes * You can attach **multiple tools to a single node** * All the tools that you have created will be available for selection in the node * Tools are only callable when attached to that node * The LLM will choose which one to call Inside the node, guide the LLM using **simple English instructions**. Example: "If the user shows interest in speaking to sales or wants a callback, immediately call the capture\_lead\_interest tool and set interest to true." This instruction is often the deciding factor for correct tool usage. This instruction is often the **deciding factor** for correct tool usage.![Parameter Example]()
## Tool Invocation Logic (How the LLM Thinks) The LLM considers: * User's spoken intent * Node prompt instructions * Tool name and description * Parameter descriptions If these align clearly, the tool is called automatically. Poor naming or vague descriptions lead to: * Missed tool calls * Wrong parameters * Hallucinated values
## Key Best Practices * Name tools clearly * Write detailed, action-based descriptions * Keep parameters simple at first * Always include http/https in URLs * Use plain English in node instructions * Attach only relevant tools to each node **Well-defined tools + clear prompts = reliable, production-grade voice agents.** # Tools Source: https://docs.dograh.com/voice-agent/tools/introduction Extend your voice agent's capabilities by giving it tools to perform actions during live conversations. Tools let your AI agent take actions during a conversation — transfer calls, hand the caller to another agent, end calls, call external APIs, or invoke remote MCP servers — based on the context of the conversation and your prompt instructions. When a tool is attached to a workflow node, the LLM decides **when** to invoke it and **what parameters** to pass, based on the user's spoken intent and your node-level instructions. ## Tool Types Dograh provides two categories of tools: ### Built-in Tools Pre-configured tools that handle common telephony operations out of the box: * [**Call Transfer**](/voice-agent/tools/call-transfer) — Transfer the active call to a phone number or SIP endpoint * [**Transfer to Agent**](/voice-agent/tools/transfer-agent) — Hand the live call to another Dograh agent, carrying conversation history as a labeled transcript * [**End Call**](/voice-agent/tools/end-call) — Terminate the call when the conversation is complete ### Custom Tools Tools you define to integrate with any external system: * [**HTTP API**](/voice-agent/tools/http-api) — Call any REST API endpoint during a conversation (e.g., CRM updates, data lookups, triggering automations) * [**MCP Tool**](/voice-agent/tools/mcp-tool) — Connect an external MCP server and expose its remote tools to the LLM during a conversation ## How Tools Work 1. You **define** a tool with a name, description, and parameters 2. You **attach** the tool to one or more workflow nodes 3. During a call, the LLM reads your node prompt, the tool description, and the caller's intent to decide whether to invoke the tool 4. The tool executes and returns a result that the agent can use to continue the conversation ## Best Practices * **Attach only relevant tools to each node** — fewer tools means more reliable invocations * **Write clear tool descriptions** — the LLM uses these to decide when to call the tool * **Guide the LLM in your node prompt** — explicitly describe when a tool should be used * **Test tool behavior** — verify your agent invokes tools at the right moments using web or phone calls # MCP Tool Source: https://docs.dograh.com/voice-agent/tools/mcp-tool Connect an external MCP server to your voice agent so the LLM can call remote tools during a live conversation.
This page is about using an external MCP server as a **tool inside a voice agent**. If you want Claude, Cursor, or another coding agent to control Dograh itself over MCP, see [Dograh MCP Server](/integrations/mcp).
MCP tools let a Dograh voice agent call tools exposed by a remote [Model Context Protocol](https://modelcontextprotocol.io/) server during a live conversation. Dograh discovers the remote tool catalog, turns those tools into LLM-callable functions, and forwards invocations to the MCP server over authenticated Streamable HTTP.
## What to configure
An MCP tool in Dograh has four important pieces:
* **Name**: the server label shown in Dograh
* **Description**: tells the LLM when this MCP server is relevant
* **URL**: the remote MCP server endpoint (`http://` or `https://`)
* **Credential**: the auth Dograh should send when connecting to that server
You can also set a **tool filter** to allow only specific remote MCP tools to be exposed.
## Authentication
Most hosted MCP servers expect:
```http theme={null}
Authorization: Bearer
```
So before creating the MCP tool, create a credential in Dograh with:
* **Credential Type**: `Bearer Token`
* **Token**: the access token issued by your MCP server
Then select that credential on the MCP tool.
If the remote MCP server documentation says to use Bearer auth, choose **Bearer Token** in the credential dialog. Dograh will translate that into the exact `Authorization: Bearer ` header on the MCP connection.
Dograh also supports other credential types, but **Bearer Token** is the default thing to try for third-party MCP servers unless their docs say otherwise.
## How it works
The runtime path is:
1. When you save or refresh the MCP tool, Dograh opens a short-lived authenticated MCP session and fetches the remote tool catalog.
2. Dograh stores that catalog as the tool's discovered tools so the UI can show you which remote functions exist.
3. When a call starts, Dograh opens one live MCP session per attached MCP server and reuses your selected credential for that session.
4. For each node, Dograh exposes only the MCP tools allowed by the server-level filter and the node-level selection.
5. Dograh namespaces those remote tools into ordinary LLM function definitions so they can safely coexist with HTTP API tools, call transfer, end call, and other tools.
6. During the conversation, the LLM sees only the tool name, description, and argument schema. It does **not** see the secret.
7. When the LLM calls one of those tools, Dograh forwards the invocation to the MCP server over the active authenticated session, receives the result, and feeds that result back into the agent turn.
In short: **Dograh handles discovery, authentication, session management, tool registration, and result plumbing; the LLM only decides when to call the tool and with which arguments.**
## Creating an MCP tool
1. Go to **Tools** and create a new tool.
2. Choose **MCP Server**.
3. Enter a clear name and a description that explains when the LLM should use this server.
4. Paste the MCP server URL.
5. Select the credential. In most cases this should be a **Bearer Token** credential.
6. Save the tool and confirm that Dograh discovered the remote tools.
If the server exposes many tools, use filtering to keep only the ones your agent actually needs.
## Attaching it to a node
After the MCP tool is created:
1. Open the workflow node where the tool should be available.
2. Add the MCP tool from the node's tool list.
3. Select only the remote MCP functions that should be callable on that node.
4. In the node prompt, tell the LLM exactly when to use those functions.
The tighter the node-level selection and prompt guidance, the more reliable MCP tool usage becomes.
## Best practices
* Use one MCP server per logical integration when possible.
* Keep the tool description explicit about **when** the LLM should use that server.
* Expose only the minimum remote functions needed for each node.
* Prefer a **Bearer Token** credential unless the MCP server specifies another auth scheme.
* Test discovery first, then test a real phone/web call to confirm the LLM invokes the right MCP function with the right arguments.
If the remote MCP server is temporarily unavailable, Dograh degrades gracefully and the call can continue without those MCP tools rather than crashing the entire conversation.
# Transfer to Agent
Source: https://docs.dograh.com/voice-agent/tools/transfer-agent
Hand a live call from one Dograh agent to another, carrying conversation history so the caller can continue where they left off.
The Transfer to Agent tool hands the caller from the agent they are talking to over to another Dograh agent, without dropping the call. The caller stays on the same call throughout: they hear a short handover line, then a ringer, then the next agent picks up.
Use this tool to split one phone number across several focused agents — a router that picks a language or a department, a specialist that handles billing, a closer that takes payment — instead of building one large agent that tries to do everything.
## Transfer to Agent vs. Call Transfer
Both tools move the caller somewhere else, but they are not interchangeable.
| | Transfer to Agent | [Call Transfer](/voice-agent/tools/call-transfer) |
| - | - | - |
| Destination | Another Dograh agent, by `workflow_id` | A phone number or SIP endpoint |
| Who answers | A Dograh agent | A human, queue, or external phone system |
| Context | A labeled transcript of the previous agents' conversation | Optional spoken introduction on Twilio; otherwise no conversation context is passed |
| Availability | Any cascade call, including web calls | Telephony only (Twilio, Telnyx, Asterisk ARI) |
If the caller should end up talking to a person, use Call Transfer. If they should end up talking to another one of your agents, use this tool.
## How it works
1. The agent calls the Transfer to Agent tool.
2. The current agent speaks the configured handover message in its own voice.
3. The caller hears a ringer while Dograh prepares the destination agent.
4. Dograh labels the available conversation as history from the previous agent, including anything the caller said during the handoff.
5. The destination agent takes over at its **Start Call** node. By default it plays that node's greeting. With **Play greeting** turned off, it skips the greeting and opens with a reply based on the conversation history.
After a transfer is accepted, Dograh suppresses the source agent's next generation while the handover message and ringer play. If the transfer is refused, the agent can explain the result and continue helping the caller.
## What the destination agent receives
The destination receives one historical message containing the available conversation, with a heading such as `Conversation with previous agent "Reception":`. Caller and agent speech are labeled separately. This applies to every handoff, with **no minimum number of turns** and no LLM summary call during the transfer.
Earlier agents' history stays in the same transcript across repeated transfers. Speech added while the destination is being prepared is included and marked as happening during the transfer. The destination is told that this is historical context and that the transfer is already complete.
The source agent's prompts, tool calls, and tool results are filtered out. Spoken text accompanying a tool call, such as the handover announcement, is retained. Later node transitions preserve the inherited transcript when summarizing the current agent's own conversation.
Because context travels with the caller, the destination agent should not re-ask for information the caller already gave. Say so in its prompt.
## Configuration
A Transfer to Agent tool has three settings. Everything else about how a handoff sounds is fixed.
* **Agent** (`workflow_id`, required) — the id of the Dograh agent to transfer to. It must belong to the same organization.
* **Handover message** (`message`) — spoken by the current agent, in its own voice, just before the handover. Supports [template variables](/voice-agent/template-variables). Maximum 500 characters. Defaults to "Let me connect you with the right person. One moment please." Leave it empty to hand over without saying anything.
* **Play greeting** (`play_greeting`, default `true`) — whether the destination agent opens with its Start Call greeting. Turn it off when the destination should continue the conversation rather than introduce itself, for example an agent that greets callers on its own phone number but is also a transfer target. It then opens with a reply generated from the conversation history.
Set the handover message in the language the destination agent speaks. The default is English, which will sound wrong in front of a Portuguese or Spanish agent.
### One tool per destination
Each Transfer to Agent tool points at exactly one agent. An agent that can hand the caller to three places gets three tools, and the model chooses between them the way it chooses between any other tools — by their names and descriptions.
Name each tool after its destination and describe precisely when it should fire:
```
Name: Transfer to Billing
Description: Hand the call to the billing agent. Call this only once the
caller has said their question is about an invoice, a charge,
or a refund. Do not call it for delivery or account questions.
```
If the model picks the wrong destination, fix the tool descriptions before you touch the prompt — the description is what it routes on.
## Availability
Agent transfer works on every cascade call, including web calls, which is where it differs most from Call Transfer.
It is **not** available on speech-to-speech (realtime) agents. The tool still registers there, but it refuses and tells the agent to keep helping the caller itself, so the call degrades into a normal conversation rather than failing silently.
## Creating one
```json theme={null}
{
"name": "Transfer to Billing",
"category": "transfer_agent",
"description": "Hand the call to the billing agent once the caller says their question is about an invoice, a charge, or a refund.",
"definition": {
"type": "transfer_agent",
"config": {
"workflow_id": 117,
"message": "Let me put you through to our billing team. One moment."
}
}
}
```
The destination agent must exist before you create the tool, because the tool stores its id. When you are building a set of agents programmatically, create the destination agents first, then the tools, then the agent that routes between them.
## Prompting the routing agent
* Tell the agent that a turn is either spoken words or a tool call, never both.
* Do not tell it to announce the transfer; the tool's handover message already does that.
* Give each destination an explicit, mutually exclusive firing condition.
* End the prompt with success criteria naming which tool fires for which outcome, and stating that exactly one of them should ever fire.
See [tool call guidance](/voice-agent/tools/introduction#best-practices) for the general rules.
## Troubleshooting
### `destination_not_found` when creating the tool
The `workflow_id` does not exist in your organization. A transfer can only hand the call to your own agents. Check the id on the destination agent's settings page.
### The agent says transferring is unavailable
The call is running on a speech-to-speech agent, where agent transfer is not supported. Switch the agent to a cascade model configuration, or use [Call Transfer](/voice-agent/tools/call-transfer) to reach a human instead.
### The transfer is refused as already under way
Two transfer tools fired for the same call. Tighten the firing conditions in the tool descriptions so only one can match, and state in the prompt that exactly one transfer may happen.
### The transfer is refused as misconfigured
The tool's `workflow_id` is missing or is not an integer. Re-create the tool with a valid agent id.
### The destination agent re-asks something the caller already answered
Check that the destination agent's prompt tells it to use the conversation history from previous agents. Add an instruction that the caller has already spoken to a colleague and should not be asked to repeat themselves.
# Webhook
Source: https://docs.dograh.com/voice-agent/webhook
Webhook node allow you to sync the result of Voice Agent runs to your external systems, like CRM or to other workflow orchestrator like Zapier or n8n.
## Video Tutorial
You can have multiple Webhook Nodes for a single Voice Agent, if you want to sync the result of the call at multiple places.
### Creating the Webhook Payload
The payload can contain a valid JSON, and you can reference context variables while constructing it using double-brace syntax — for example `{{workflow_run_id}}`, [`{{initial_context.*}}`](/core-concepts/context-and-variables#initial_context), and [`{{gathered_context.*}}`](/core-concepts/context-and-variables#gathered_context), including the [final call outcome](../developer/call-dispositions) `{{gathered_context.call_disposition}}`.
For the full list of available variables, authentication options, and receiver examples, see the [Webhook Payloads developer reference](/developer/webhooks).
An example of the payload is given below
```json theme={null}
{
"call_id": "{{workflow_run_id}}",
"first_name": "{{initial_context.first_name}}",
"rsvp": "{{gathered_context.rsvp}}",
"disposition": "{{gathered_context.call_disposition}}",
"duration": "{{cost_info.call_duration_seconds}}",
"recording_url": "{{recording_url}}",
"transcript_url": "{{transcript_url}}"
}
```
## Defining an HTTP API Tool ### 1. Tool Name * Must be clear and action-oriented. * **Examples:** `capture_lead_interest`, `fetch_weather`, 'create\_crm\_contact', etc ### 2. Tool Description * Extremely important * This is how the LLM decides **when** to use the tool. * Write it in plain, explicit English. **Bad:** "API to capture data" **Good:** "This tool is to capture interest. Use this tool when the user clearly expresses interest in the product or wants to be contacted"
### 4. Authentication & Headers * Add custom authentication * Add custom headers * Works with internal services and third-party APIs
### 5. Parameters Each parameter must have: * Name * Type * Description * Required/Optional flag **Parameter descriptions matter more than types.** Guidelines: * Start with string parameters when possible * Be explicit in what the value represents * Mark only truly mandatory fields as required Example: * interest (string): "Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false."
## Attaching Tools to Workflow Nodes * You can attach **multiple tools to a single node** * All the tools that you have created will be available for selection in the node * Tools are only callable when attached to that node * The LLM will choose which one to call Inside the node, guide the LLM using **simple English instructions**. Example: "If the user shows interest in speaking to sales or wants a callback, immediately call the capture\_lead\_interest tool and set interest to true." This instruction is often the deciding factor for correct tool usage. This instruction is often the **deciding factor** for correct tool usage.
## Tool Invocation Logic (How the LLM Thinks) The LLM considers: * User's spoken intent * Node prompt instructions * Tool name and description * Parameter descriptions If these align clearly, the tool is called automatically. Poor naming or vague descriptions lead to: * Missed tool calls * Wrong parameters * Hallucinated values
## Key Best Practices * Name tools clearly * Write detailed, action-based descriptions * Keep parameters simple at first * Always include http/https in URLs * Use plain English in node instructions * Attach only relevant tools to each node **Well-defined tools + clear prompts = reliable, production-grade voice agents.** # Tools Source: https://docs.dograh.com/voice-agent/tools/introduction Extend your voice agent's capabilities by giving it tools to perform actions during live conversations. Tools let your AI agent take actions during a conversation — transfer calls, hand the caller to another agent, end calls, call external APIs, or invoke remote MCP servers — based on the context of the conversation and your prompt instructions. When a tool is attached to a workflow node, the LLM decides **when** to invoke it and **what parameters** to pass, based on the user's spoken intent and your node-level instructions. ## Tool Types Dograh provides two categories of tools: ### Built-in Tools Pre-configured tools that handle common telephony operations out of the box: * [**Call Transfer**](/voice-agent/tools/call-transfer) — Transfer the active call to a phone number or SIP endpoint * [**Transfer to Agent**](/voice-agent/tools/transfer-agent) — Hand the live call to another Dograh agent, carrying conversation history as a labeled transcript * [**End Call**](/voice-agent/tools/end-call) — Terminate the call when the conversation is complete ### Custom Tools Tools you define to integrate with any external system: * [**HTTP API**](/voice-agent/tools/http-api) — Call any REST API endpoint during a conversation (e.g., CRM updates, data lookups, triggering automations) * [**MCP Tool**](/voice-agent/tools/mcp-tool) — Connect an external MCP server and expose its remote tools to the LLM during a conversation ## How Tools Work 1. You **define** a tool with a name, description, and parameters 2. You **attach** the tool to one or more workflow nodes 3. During a call, the LLM reads your node prompt, the tool description, and the caller's intent to decide whether to invoke the tool 4. The tool executes and returns a result that the agent can use to continue the conversation ## Best Practices * **Attach only relevant tools to each node** — fewer tools means more reliable invocations * **Write clear tool descriptions** — the LLM uses these to decide when to call the tool * **Guide the LLM in your node prompt** — explicitly describe when a tool should be used * **Test tool behavior** — verify your agent invokes tools at the right moments using web or phone calls # MCP Tool Source: https://docs.dograh.com/voice-agent/tools/mcp-tool Connect an external MCP server to your voice agent so the LLM can call remote tools during a live conversation.