From c650ccc5dd5b1d69d553812d3094e9fcf7104c70 Mon Sep 17 00:00:00 2001 From: Rushil Date: Wed, 15 Jul 2026 18:37:52 +0530 Subject: [PATCH] docs: add video-embedded getting-started pages for API Trigger, Webhook, Telephony, Tools & KB (#535) * docs: add video-embedded getting-started pages for API Trigger, Webhook, Telephony, Tools & Knowledge Base Four new tutorial pages inserted after Your First Agent in 5 Minutes, each pairing a walkthrough video with a step-by-step practical guide sourced from the recorded demo: Trigger Calls Automatically (API Trigger), Send Call Data Back Automatically (Webhook), Connect Your Phone Number (Twilio telephony), and Give Your Agent Real Data (HTTP tools + KB). * docs: address greptile review feedback on PR #535 * docs: link Twilio Verified Caller IDs page directly * Restructure the documents * docs: embed agent builder walkthrough video on first-agent page * docs: match link text to renamed Connect with Telephony title * docs: warn that default outbound telephony config is required for API Trigger --------- Co-authored-by: Abhishek Kumar --- docs/docs.json | 11 ++- .../add-tools-and-knowledge-base.mdx | 95 +++++++++++++++++++ docs/getting-started/connect-telephony.mdx | 57 +++++++++++ docs/getting-started/first-agent.mdx | 8 ++ .../send-call-data-with-webhooks.mdx | 60 ++++++++++++ .../trigger-calls-from-your-backend.mdx | 72 ++++++++++++++ 6 files changed, 302 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/add-tools-and-knowledge-base.mdx create mode 100644 docs/getting-started/connect-telephony.mdx create mode 100644 docs/getting-started/send-call-data-with-webhooks.mdx create mode 100644 docs/getting-started/trigger-calls-from-your-backend.mdx diff --git a/docs/docs.json b/docs/docs.json index 61cac8da..7060f1d7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -21,13 +21,22 @@ "group": "Introduction", "pages": [ "getting-started/index", - "getting-started/first-agent", "getting-started/prerequisites", "getting-started/troubleshooting" ] } ] }, + { + "group": "Build your First Agent", + "pages": [ + "getting-started/first-agent", + "getting-started/trigger-calls-from-your-backend", + "getting-started/send-call-data-with-webhooks", + "getting-started/connect-telephony", + "getting-started/add-tools-and-knowledge-base" + ] + }, { "group": "Core Concepts", "pages": [ diff --git a/docs/getting-started/add-tools-and-knowledge-base.mdx b/docs/getting-started/add-tools-and-knowledge-base.mdx new file mode 100644 index 00000000..bcdae1dd --- /dev/null +++ b/docs/getting-started/add-tools-and-knowledge-base.mdx @@ -0,0 +1,95 @@ +--- +title: "Use External Tools, Knowledge" +description: "Make your agent do something during the call, not just talk. Connect it to live data and your company documents." +--- + +You've made the agent reachable through real phone calls. Now let's make it useful during the call. + +Your agent can hold a conversation. But can it check an order, or answer a policy question correctly? That's what this page is about. + +There are two ways to connect real information to your agent. A **tool** is for anything live, data that changes, or an action that needs to happen, like checking an order or looking up availability. A **Knowledge Base** is for anything written down, like your return policy or an FAQ, that doesn't change from call to call. + + + +Here's the setup used in the video: an order support agent named Maya, for a store called QuickMart. A customer can ask what's in their cart, and Maya calls an API to check it. A customer can also ask a policy question, and Maya answers from a document you uploaded. + +## Step 1: Create the tool + +Open the node where most of the conversation happens, in this case Maya's main support node. Scroll down and click **Create a Tool**, then choose **External HTTP API**. Name it `get_cart_details`. + + +The description matters more than anything else here. It's what the agent reads to decide when to call the tool. Write it plainly: *"Use this tool when the caller asks about cart details. It returns the cart's products, quantities, total, and discounted total."* + + +For the endpoint, this demo uses [dummyjson.com](https://dummyjson.com), a public sample API. Copy this exact URL and test it yourself, no backend required: + +``` +GET https://dummyjson.com/carts/1 +``` + +No auth, no parameters. It's a GET request because you're fetching information, not changing anything. In your own setup, this would point at your CRM or order system instead. + +Save the tool. + +## Step 2: Attach the tool to the node + +Creating the tool isn't enough by itself. Go back to Maya's node and select `get_cart_details` under Tools, then save. + + +A tool only becomes available once it's attached to the node that needs it. If you skip this, the tool exists but the agent will never call it. + + +## Step 3: Upload a Knowledge Base document + +Click **Upload Document**, or go straight to **Knowledge Base Files**. Pick the document you want the agent to read from, a return policy, a shipping FAQ, whatever your customers actually ask about. + +Dograh asks how it should retrieve from this document: + +- **Full Document** works best for small files, where the agent can see the whole thing at once. It does not require an embeddings model. +- **Chunked Search** is for large documents, where the agent should only pull the relevant section. Configure an embeddings model before selecting this mode; otherwise document processing or retrieval will fail. + +A short policy document is a Full Document case. Upload it, then wait for the status to say **Completed**. + +## Step 4: Attach the document to the node + +Same rule as the tool. Go back to Maya's node, scroll to **Knowledge Base Documents**, and attach the file. + + +Uploading isn't enough on its own. The document has to be attached to the node where the agent should use it. + + +## Step 5: Tell the agent when to use each + +In the node's prompt, spell out which mechanism handles which question. Don't leave it to guesswork: + +``` +If the caller asks about cart contents, order items, quantities, total, or discounts, +use the get_cart_details tool before answering. + +For questions about returns, refunds, or cancellations, +use the attached Knowledge Base document. +``` + +Save the node. + +## Step 6: Test it + +Start a Web Call and try both: + +- *"Hi Maya, what's inside my cart?"* Watch the transcript. Maya decides the tool is relevant, calls the API, and answers from the response instead of guessing. +- *"What's the return policy?"* Maya retrieves the answer from the document and responds from that context. + +That's the difference that matters: for cart details, Maya uses the tool because the data changes call to call. For the return policy, she uses the Knowledge Base because that answer lives in a document and doesn't change. Tools connect your agent to systems. Knowledge Base connects it to documents. Together, your agent starts to feel connected to your actual business, not just reciting a script. + +## Next Steps + +You've now got the full loop: calls trigger automatically, data flows in and out, your number is connected, and the agent can act on live data and your own documents. + +- **Full tool reference**: parameter types, authentication, and best practices in [HTTP API Tools](/voice-agent/tools/http-api). +- **Full Knowledge Base reference**: chunking behavior and embedding setup in [Knowledge Base](/voice-agent/knowledge-base). diff --git a/docs/getting-started/connect-telephony.mdx b/docs/getting-started/connect-telephony.mdx new file mode 100644 index 00000000..8b613de1 --- /dev/null +++ b/docs/getting-started/connect-telephony.mdx @@ -0,0 +1,57 @@ +--- +title: "Connect with Telephony" +description: "Hook up Twilio so Dograh can make and receive real calls, not just browser test calls." +--- + +You've covered API Trigger and Webhooks. Both of those work on real calls, which means you need a real phone number connected first. This page walks through Twilio specifically, since it's the fastest way to get a number and test with free trial credits. + + + +## Step 1: Create a Twilio account and buy a number + +Sign up at Twilio. You'll land on their dashboard with free trial credits you can use for testing. Go to **Phone Numbers** and click **Buy a number**, pick any number you like. + +## Step 2: Copy your Account SID + +Back on the Twilio dashboard, copy your **Account SID**. + +## Step 3: Add the configuration in Dograh + +Open **Telephony** in Dograh, click **Add Configuration**, and select **Twilio** as the provider. Name it something you'll recognize later, your workflow name works well. Paste the Account SID. + +Go back to Twilio, copy your **Auth Token**, and paste it in. Keep that token private. + +If you want this configuration to be the default for test calls and campaigns, enable that here. For a basic setup, leave answering machine detection off, then click **Create**. + + +Enable **Set as default for outbound calls** on your telephony configuration. If no default is set, API Trigger will return a `400: Telephony provider not configured for this organization` error even after a successful setup. + + +## Step 4: Add your phone number + +Once the configuration exists, go to manage phone numbers and add the number you bought. Copy it from Twilio and paste it in as-is, country **US**. The label is optional, leave it blank if you want. Select your inbound workflow, in this demo, a debt collection agent. Keep it active, and enable default caller ID if you want test calls to always show that number. + +## Step 5: Verify your number + +Before testing from a Twilio trial account, verify the destination number you plan to call, such as your personal phone number. This is separate from the Twilio number you purchased for use as the caller ID. In Twilio, go to the [Verified Caller IDs page](https://www.twilio.com/console/phone-numbers/verified) and add the destination number. + +## Step 6: Test it + +Once verified, trigger a call the same way you did in [Trigger Calls using API](/getting-started/trigger-calls-from-your-backend), from Postman or your backend. Dograh places the outbound call through Twilio. The phone rings, the agent answers, and the connection is live. + + +On a trial account, Twilio plays a default message before connecting to your agent. Press any key to skip it and go straight to the agent. + + +Inbound calls work the same way in reverse, routed through Twilio's webhook into your Dograh workflow. + +## Next Steps + +- **Make your agent do more on the call**: [Use External Tools, Knowledge](/getting-started/add-tools-and-knowledge-base) covers tools and a Knowledge Base. +- **Other providers**: Vonage, Plivo, Cloudonix, and SIP-based setups are covered in [Telephony Integration](/integrations/telephony/overview). diff --git a/docs/getting-started/first-agent.mdx b/docs/getting-started/first-agent.mdx index d2d95cd7..b1af5c11 100644 --- a/docs/getting-started/first-agent.mdx +++ b/docs/getting-started/first-agent.mdx @@ -5,6 +5,14 @@ description: "Build and talk to a working voice agent in five minutes using Web This is the fastest path to a working voice agent. You'll create an agent, get a generated conversation flow, and talk to it in your browser — no phone number, no telephony provider, no configuration. + + Using the hosted platform, go to [app.dograh.com](https://app.dograh.com). Self-hosting locally? Use `http://localhost:3010` instead, and follow [Getting Started](/getting-started) first to get the platform running. diff --git a/docs/getting-started/send-call-data-with-webhooks.mdx b/docs/getting-started/send-call-data-with-webhooks.mdx new file mode 100644 index 00000000..63f7743e --- /dev/null +++ b/docs/getting-started/send-call-data-with-webhooks.mdx @@ -0,0 +1,60 @@ +--- +title: "Sync Data using Webhook" +description: "Get everything Dograh learned during the call back into your system the moment it ends." +--- + +The last page covered sending data into a call with API Trigger and `initial_context`. Now the opposite side: how Dograh sends what it learned back out to your system once the call ends. + +That extracted data lives in `gathered_context`. So the full picture is: `initial_context` is what your backend sends into the call, `gathered_context` is what Dograh extracts from it. A **Webhook** node is how you get `gathered_context` back out. + + + +## Step 1: Add the node + +Click **Add node**, scroll down, and you'll find the **Webhook** node. Add it and open it up. + +## Step 2: Set the endpoint + +First thing you'll see is the endpoint URL. Paste your backend's webhook URL here. Still testing? Use a free URL from [webhook.site](https://webhook.site), copy your unique URL there and paste it into Dograh. + +Set the method to **POST**. If your backend needs auth, add a bearer token or API key right here too. + +## Step 3: Build the payload template + +This is the important part, it decides exactly what JSON Dograh sends. Include both kinds of context: `initial_context` fields like debtor name, client name, and debt amount, and `gathered_context` fields like amount to pay, payment method, and sentiment. + +```json +{ + "debtor_name": "{{initial_context.debtor_name}}", + "client_name": "{{initial_context.client_name}}", + "debt_amount": "{{initial_context.debt_amount}}", + "amount_user_will_pay": "{{gathered_context.amount_user_will_pay}}", + "payment_method": "{{gathered_context.payment_method}}", + "sentiment": "{{gathered_context.sentiment}}" +} +``` + + +Variable names in your payload have to match your context fields exactly. If a variable cannot be resolved, its field remains in the payload with an empty string value. + + +## Step 4: Save and publish + +Save the webhook node, then publish the agent. + +## Step 5: Test it + +Run a test call. When it ends, go back to your webhook receiver. You'll see one request with both `initial_context`, the data you sent into the call, and `gathered_context`, what Dograh extracted from the conversation, sitting in the same JSON payload. + +That's the complete loop: your backend sends `initial_context` into Dograh, Dograh runs the call and extracts `gathered_context`, and the webhook node sends the final structured data back to your backend. For production, swap the webhook.site URL for your real backend URL. + +## Next Steps + +- **Connect a real phone number**: [Connect with Telephony](/getting-started/connect-telephony) covers hooking up Twilio so these calls go out for real. +- **Full variable list and authentication options**: see the [Webhook reference](/voice-agent/webhook) and the [Webhook Payloads developer reference](/developer/webhooks). diff --git a/docs/getting-started/trigger-calls-from-your-backend.mdx b/docs/getting-started/trigger-calls-from-your-backend.mdx new file mode 100644 index 00000000..0e562d1d --- /dev/null +++ b/docs/getting-started/trigger-calls-from-your-backend.mdx @@ -0,0 +1,72 @@ +--- +title: "Trigger Calls using API" +description: "Kick off a call the moment a lead lands in your CRM or spreadsheet, no manual dialing." +--- + +If your team is manually dialing leads one by one, or your CRM needs to kick off a call the moment a lead comes in, this is how you automate that with Dograh. + +Say you've got leads or accounts sitting in a CRM or a Google Sheet. Each row has details like customer name, company name, amount due. The **API Trigger** node lets you take that row of data and turn it into a personalized call, automatically. + + + +## Step 1: Add the node + +Click **Add node** and add an **API Trigger** node, the topmost option in the list. This node starts the call and passes your data into the agent as `initial_context`. + +That's the part that matters: instead of the agent asking basic setup questions on the call, like "what's your name" or "how much do you owe", it already knows. In this demo, the opening node greets the caller with `{{debtor_name}}`, and the next node references `{{client_name}}` and `{{debt_amount}}`. None of that is hardcoded into the agent. It all comes from the API call. + + +Every node has a docs link in the top right corner. If you get stuck or want to go deeper on any node type, open the docs straight from there. + + +## Step 2: Check the prerequisites + +Before you trigger anything: + +1. [Connect with Telephony](/getting-started/connect-telephony) for outbound calls. +2. Go to the developer portal and generate an API key. You'll need it in the request header. + +## Step 3: Find your trigger URL + +Open the API Trigger node. You'll see two URLs: + +- **Test URL** runs your latest draft. +- **Production URL** runs your published agent. + +If you change the agent and want the production URL to reflect it, publish first, otherwise production keeps running the older version. While you're still testing, use the test URL. + +## Step 4: Send the request + +Trigger the call from Postman, or wherever your backend lives. In the body, send `phone_number` and `initial_context`: + +```bash +curl -X POST https://api.dograh.com/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": { + "debtor_name": "Rushil", + "client_name": "Quick Credit", + "debt_amount": "3500" + } + }' +``` + +The body can come from your CRM, a Google Sheet, or your own backend, wherever that row of data lives. + +## What you get + +Send the request, and the call goes out immediately. Because the agent already had the context before the call started, the conversation is short and specific from the first line: *"Hi, this is Alex from Apex Recovery Solutions. Am I speaking with Rushil? I'm calling about your Quick Credit account with an outstanding balance of $3,500."* No setup questions, straight to the point. + +## Next Steps + +- **Get that data back automatically**: the next step is [Sync Data using Webhook](/getting-started/send-call-data-with-webhooks), which takes whatever the agent learns on the call and sends it back to your system the moment it ends. +- **No phone number connected yet?** See [Connect with Telephony](/getting-started/connect-telephony) first, outbound calls need a telephony provider attached. +- **Full endpoint reference**: error codes, response shape, and choosing a specific telephony configuration are in [API Trigger](/voice-agent/api-trigger).