mirror of
https://github.com/dograh-hq/dograh.git
synced 2026-06-07 07:55:16 +02:00
feat: add pre call fetch configuration (#222)
* feat: add pre call fetch configuration * docs: add NEW tags for pages about new features --------- Co-authored-by: Sabiha Khan <sabihak89@gmail.com>
This commit is contained in:
Abhishek
GitHub
parent
c4c4b591db
commit
ec2f322486
27 changed files with 646 additions and 66 deletions
|
|
@ -56,9 +56,11 @@
|
|||
"voice-agent/editing-a-workflow",
|
||||
"voice-agent/pre-recorded-audio",
|
||||
"voice-agent/template-variables",
|
||||
"voice-agent/pre-call-data-fetch",
|
||||
{
|
||||
"group": "Tools",
|
||||
"pages": [
|
||||
"voice-agent/tools/introduction",
|
||||
{
|
||||
"group": "Built-in Tools",
|
||||
"pages": [
|
||||
|
|
@ -74,6 +76,7 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
"voice-agent/knowledge-base",
|
||||
{
|
||||
"group": "Nodes",
|
||||
"pages": [
|
||||
|
|
|
|||
BIN
docs/images/embedding-configurations.png
Normal file
BIN
docs/images/embedding-configurations.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
53
docs/voice-agent/knowledge-base.mdx
Normal file
53
docs/voice-agent/knowledge-base.mdx
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
title: "Knowledge Base"
|
||||
description: "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.
|
||||
|
||||
<Warning>
|
||||
You must configure an embedding provider and API key in **AI Models Configuration → Embedding** before using the Knowledge Base. Document processing and retrieval depend on embeddings, so this feature will not work without a valid embedding configuration.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
## How It Works
|
||||
|
||||
1. You **upload** a document (PDF, DOCX, TXT, or JSON) to the Knowledge Base
|
||||
2. Dograh **processes** and chunks the document for efficient retrieval
|
||||
3. You **attach** the document to one or more workflow nodes
|
||||
4. During a call, the agent **searches** the document for relevant information based on the caller's questions 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. Wait for processing to complete — the document will be chunked and indexed automatically
|
||||
|
||||
## 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
|
||||
|
||||
- **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
|
||||
140
docs/voice-agent/pre-call-data-fetch.mdx
Normal file
140
docs/voice-agent/pre-call-data-fetch.mdx
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
title: "Pre-Call Data Fetch"
|
||||
description: "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."
|
||||
tag: "NEW"
|
||||
---
|
||||
|
||||
Pre-Call Data Fetch allows you to enrich the call context with external data before the voice agent starts speaking. When enabled on the **Start Call** node, Dograh sends an HTTP request to your API as soon as a call is initiated. 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 `dynamic_variables`.
|
||||
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** node editor and expand **Advanced Settings**. Toggle **Pre-Call Data Fetch** and configure:
|
||||
|
||||
| Field | Description |
|
||||
| --- | --- |
|
||||
| **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
|
||||
{
|
||||
"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 `dynamic_variables` key:
|
||||
|
||||
```json
|
||||
{
|
||||
"call_inbound": {
|
||||
"dynamic_variables": {
|
||||
"customer_name": "Jane Doe",
|
||||
"account_status": "active",
|
||||
"loyalty_tier": "gold",
|
||||
"open_tickets": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also place `dynamic_variables` at the top level:
|
||||
|
||||
```json
|
||||
{
|
||||
"dynamic_variables": {
|
||||
"customer_name": "Jane Doe",
|
||||
"account_status": "active"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.`
|
||||
|
||||
<Note>
|
||||
If the response is not a valid JSON object, does not contain `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.
|
||||
</Note>
|
||||
|
||||
## Nested Variables
|
||||
|
||||
If your `dynamic_variables` contain nested objects, you can access them using dot notation:
|
||||
|
||||
```json
|
||||
{
|
||||
"call_inbound": {
|
||||
"dynamic_variables": {
|
||||
"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.
|
||||
|
||||
## Example Integration
|
||||
|
||||
A simple Node.js endpoint that looks up a customer by phone number:
|
||||
|
||||
```javascript
|
||||
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: {
|
||||
dynamic_variables: {
|
||||
customer_name: customer.name,
|
||||
account_status: customer.status,
|
||||
loyalty_tier: customer.tier,
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
```
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: "Pre-recorded Audio"
|
||||
description: "Build hybrid voice agents that combine pre-recorded audio with dynamic text generation for lower latency, reduced TTS costs, and natural-sounding conversations."
|
||||
tag: "NEW"
|
||||
---
|
||||
|
||||
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.
|
||||
|
|
|
|||
39
docs/voice-agent/tools/introduction.mdx
Normal file
39
docs/voice-agent/tools/introduction.mdx
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
title: "Tools"
|
||||
description: "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, end calls, or call external APIs — 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
|
||||
- [**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)
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue