diff --git a/api/routes/telephony.py b/api/routes/telephony.py index 0e423cb..5c57cc2 100644 --- a/api/routes/telephony.py +++ b/api/routes/telephony.py @@ -1728,7 +1728,6 @@ async def complete_transfer_function_call(transfer_id: str, request: Request): status=result["status"], action=result.get("action", ""), reason=result.get("reason"), - end_call=result.get("end_call", False), ) # Publish the event via Redis diff --git a/api/services/telephony/ari_manager.py b/api/services/telephony/ari_manager.py index 193ed9f..98dacfc 100644 --- a/api/services/telephony/ari_manager.py +++ b/api/services/telephony/ari_manager.py @@ -790,8 +790,6 @@ class ARIConnection: message="Transfer destination answered", status="success", action="destination_answered", - end_call=True, - timestamp=time.time(), ) await transfer_manager.publish_transfer_event(success_event) @@ -824,8 +822,6 @@ class ARIConnection: status="failed", action="transfer_failed", reason=reason, - end_call=False, - timestamp=time.time(), ) await transfer_manager.publish_transfer_event(failure_event) diff --git a/api/services/telephony/transfer_event_protocol.py b/api/services/telephony/transfer_event_protocol.py index 761d3f6..7e7815e 100644 --- a/api/services/telephony/transfer_event_protocol.py +++ b/api/services/telephony/transfer_event_protocol.py @@ -52,7 +52,6 @@ class TransferEvent: "conference_id": self.conference_name, "transfer_call_sid": self.transfer_call_sid, "original_call_sid": self.original_call_sid, - "end_call": self.end_call, "reason": self.reason, } return result diff --git a/api/services/workflow/pipecat_engine_custom_tools.py b/api/services/workflow/pipecat_engine_custom_tools.py index 0c2dfca..c915fb8 100644 --- a/api/services/workflow/pipecat_engine_custom_tools.py +++ b/api/services/workflow/pipecat_engine_custom_tools.py @@ -318,7 +318,6 @@ class CustomToolManager: "message": "I'm sorry, but call transfers are not available for web calls. Please try a telephony call.", "action": "transfer_failed", "reason": "webrtc_not_supported", - "end_call": True, } await self._handle_transfer_result( webrtc_error_result, function_call_params, properties @@ -332,7 +331,6 @@ class CustomToolManager: "message": "I'm sorry, but I don't have a phone number configured for the transfer. Please contact support to set up call transfer.", "action": "transfer_failed", "reason": "no_destination", - "end_call": True, } await self._handle_transfer_result( validation_error_result, function_call_params, properties @@ -354,7 +352,6 @@ class CustomToolManager: "message": "I'm sorry, but the transfer destination appears to be invalid. Please contact support to verify the transfer settings.", "action": "transfer_failed", "reason": "invalid_destination", - "end_call": True, } await self._handle_transfer_result( validation_error_result, function_call_params, properties @@ -369,7 +366,6 @@ class CustomToolManager: "message": "I'm sorry, but the transfer phone number appears to be invalid. Please contact support to verify the transfer settings.", "action": "transfer_failed", "reason": "invalid_destination", - "end_call": True, } await self._handle_transfer_result( validation_error_result, function_call_params, properties @@ -388,7 +384,6 @@ class CustomToolManager: "message": "I'm sorry, there's an issue with this call transfer. Please contact support.", "action": "transfer_failed", "reason": "no_organization_id", - "end_call": False, } await self._handle_transfer_result( validation_error_result, function_call_params, properties @@ -402,7 +397,6 @@ class CustomToolManager: "message": "I'm sorry, there's an issue with this call transfer. Please contact support.", "action": "transfer_failed", "reason": "provider_does_not_support_transfer", - "end_call": False, } await self._handle_transfer_result( validation_error_result, function_call_params, properties @@ -512,7 +506,6 @@ class CustomToolManager: "message": "I'm sorry, but the call is taking longer than expected to connect. The person might not be available right now. Please try calling back later.", "action": "transfer_failed", "reason": "timeout", - "end_call": True, } await self._handle_transfer_result( timeout_result, function_call_params, properties @@ -530,7 +523,6 @@ class CustomToolManager: "message": "I'm sorry, but something went wrong while trying to transfer your call. Please try again later or contact support if the problem persists.", "action": "transfer_failed", "reason": "execution_error", - "end_call": True, } await self._handle_transfer_result( diff --git a/docs/docs.json b/docs/docs.json index c6e8d42..37c8809 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -43,7 +43,24 @@ "voice-agent/introduction", "voice-agent/editing-a-workflow", "voice-agent/template-variables", - "voice-agent/tools", + { + "group": "Tools", + "pages": [ + { + "group": "Built-in Tools", + "pages": [ + "voice-agent/tools/call-transfer", + "voice-agent/tools/end-call" + ] + }, + { + "group": "Custom Tools", + "pages": [ + "voice-agent/tools/http-api" + ] + } + ] + }, { "group": "Nodes", "pages": [ diff --git a/docs/voice-agent/tools/call-transfer.mdx b/docs/voice-agent/tools/call-transfer.mdx new file mode 100644 index 0000000..064df3c --- /dev/null +++ b/docs/voice-agent/tools/call-transfer.mdx @@ -0,0 +1,57 @@ +--- +title: "Call Transfer" +description: "Enable your AI agent to transfer calls to phone numbers or SIP endpoints with built-in call transfer functionality." +--- + +The Call Transfer tool enables your AI agent to transfer active calls to phone numbers or SIP endpoints. When configured, your agent can seamlessly transfer callers to human operators, departments, or other systems while maintaining a professional experience. + +## Supported Providers + +Call transfer is available for telephony calls using Twilio or Asterisk ARI providers. Web calls do not support transfer functionality. + +## How It Works + +The Call Transfer tool performs **blind transfers** where no call context is shared with the destination. Here's what happens: + +1. **Agent Decision**: Your AI agent determines a transfer is needed and calls the transfer function +2. **Pre-transfer Message**: (Optional) Agent plays a custom message like "Let me transfer you to our sales team" +3. **Hold Experience**: Caller hears hold music while the transfer is processed +4. **Connection**: Once the destination answers, the caller is connected directly +5. **Agent Handoff**: The AI agent ends its involvement in the call + +## Configuration + +### Basic Settings + +- **Destination**: Phone number or SIP endpoint (see formats below) +- **Timeout**: How long to wait for destination to answer (default 30 seconds) +- **Pre-transfer Message**: Optional custom message played before transfer + +### Destination Formats + +**For Twilio:** +- **Phone numbers**: E.164 format: `+1234567890` +- Must be a valid reachable phone number + +**For Asterisk ARI:** +- **SIP endpoints only**: `PJSIP/extension` or `SIP/endpoint` +- **Examples**: `PJSIP/sales-queue`, `SIP/1001`, `PJSIP/conference-room` + + +Asterisk ARI transfers only work with SIP endpoints configured on your Asterisk server. External phone numbers require additional PSTN trunk configuration. + + +## Setup Requirements + +1. **Organization Setup**: Ensure your organization has a supported telephony provider configured +2. **Tool Enablement**: Add the Call Transfer tool to your agent's available tools +3. **Destination Validation**: + - **Twilio**: Verify phone numbers are reachable + - **ARI**: Verify SIP endpoints exist on your Asterisk server +4. **Testing**: Test transfers in your specific provider environment + +## Troubleshooting + +- **Destination not reachable**: Verify destination number/endpoint is valid and reachable +- **Tool not available**: Check that Call Transfer tool is added to the correct agent node +- **Transfer failures**: Handle transfer failure scenarios within your agent prompts \ No newline at end of file diff --git a/docs/voice-agent/tools/end-call.mdx b/docs/voice-agent/tools/end-call.mdx new file mode 100644 index 0000000..6586d43 --- /dev/null +++ b/docs/voice-agent/tools/end-call.mdx @@ -0,0 +1,37 @@ +--- +title: "End Call" +description: "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 + diff --git a/docs/voice-agent/tools.mdx b/docs/voice-agent/tools/http-api.mdx similarity index 81% rename from docs/voice-agent/tools.mdx rename to docs/voice-agent/tools/http-api.mdx index f330220..255c778 100644 --- a/docs/voice-agent/tools.mdx +++ b/docs/voice-agent/tools/http-api.mdx @@ -1,10 +1,9 @@ --- -title: "Tools" +title: "HTTP API" +description: "Create REST API tools that your AI agent can invoke during conversations to integrate with external systems." --- -Dograh AI lets you attach multiple tools (e.g. API calls) directly to workflow nodes. This allows your voice agents to call any internal or external system during a live conversation-based on LLM judgment and your prompts. - -This works similar to a tool call on any agentic platforms and is 100% open source and fully customizable. +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 @@ -19,9 +18,9 @@ This works similar to a tool call on any agentic platforms and is 100% open sour allowFullScreen > -## What Are Tools? +## What is an HTTP API Tool? -A tool is a REST API definition that the LLM can invoke at runtime. +An HTTP API Tool is a REST API definition that the LLM can invoke at runtime. **Typical use cases:** - Call your own backend endpoints @@ -44,7 +43,7 @@ A tool is a REST API definition that the LLM can invoke at runtime.
-## Defining Tools +## Defining an HTTP API Tool ### 1. Tool Name @@ -103,7 +102,7 @@ Guidelines: Example: - interest (string): - “Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false.” + "Set to true if the user clearly shows intent to buy or wants follow-up. Otherwise false." ![Parameter Example](/images/tool%20params.png) @@ -121,7 +120,7 @@ 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.” +"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. @@ -156,4 +155,4 @@ Poor naming or vague descriptions lead to: - Use plain English in node instructions - Attach only relevant tools to each node -**Well-defined tools + clear prompts = reliable, production-grade voice agents.** +**Well-defined tools + clear prompts = reliable, production-grade voice agents.** \ No newline at end of file