Agent Tools

​

System Tools

​

End Call

​

When to Use

• Calls that have reached their natural conclusion
• Customer explicitly ends the conversation
• Maximum conversation time is reached
• Call objective has been completed

​

Configuration

1. Navigate to the Tools tab
2. Locate End Call under System Tools
3. Toggle the switch to enable
4. Click Configure to customize behavior
5. Set End Call Rules Override to define when the agent should end calls:

End the call when:
- The customer says goodbye or indicates they're done
- The appointment has been confirmed
- The customer explicitly asks to end the call
- You've provided all requested information and there are no further questions
- The conversation has exceeded 5 minutes

6. Click Save

​

How It Works

1. Invoke the end_call function
2. Speak a brief closing message
3. Terminate the call gracefully

​

Transfer

​

When to Use

• Customer requests to speak with a human representative
• Issue requires specialized expertise beyond the agent’s scope
• Escalation to management or specific departments
• Routing to on-call support staff

​

Configuration

1. Navigate to the Tools tab
2. Locate Transfer under System Tools
3. Toggle the switch to enable
4. Click Configure to set up transfer routes
5. Select Transfer Mode:
   • Cold Transfer — the agent transfers the call immediately and disconnects
   • Warm Transfer — the agent places the caller on hold, calls the recipient to brief them, then connects the parties
6. Add transfer routes:

• To number: +12025559999 (destination phone number in E.164 format)
• Condition: Transfer to sales team for pricing questions or to close deals

7. Click Save

​

Cold Transfer

​

Warm Transfer

1. The caller is placed on hold — they hear a hold message and optional hold music
2. The agent calls the recipient at the transfer destination number
3. The agent briefs the recipient with a summary of the conversation so far
4. The caller is connected to the recipient

​

Configuring via API

curl -X PATCH https://api.revring.ai/v1/agents/{agentId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transferEnabled": true,
    "transferMode": "warm",
    "transferRoutes": [
      {
        "to_number": "+12025559999",
        "condition": "Transfer to support team for technical issues"
      }
    ],
    "warmTransferConfig": {
      "holdMessage": "Please hold while I connect you with our support team.",
      "holdMusicEnabled": true,
      "summaryPrompt": "Focus on the customer's main concern and any account details mentioned.",
      "introMessage": "You're now connected. They're up to speed on your request."
    }
  }'

​

Voicemail Detection

​

When to Use

• Outbound calling campaigns where live conversations are preferred
• Appointment reminders or confirmations
• Sales or follow-up calls
• Any scenario where leaving a message is optional

​

Configuration

1. Navigate to the Tools tab
2. Locate Voicemail Detection under System Tools
3. Toggle the switch to enable
4. Click Configure to set behavior
5. Choose Voicemail Action:
   • Hangup: Immediately end the call when voicemail is detected (saves costs)
   • Leave Message: Speak a pre-recorded message before hanging up
6. If you selected “Leave Message”, configure Voicemail Message:

Hi, this is a message from Acme Corp. We tried reaching you regarding your appointment. Please call us back at 1-800-555-0123. Thank you.

7. Click Save

​

How It Works

• Hangup action: Call ends immediately, marked as “voicemail” in logs
• Leave message action: Agent speaks the configured message, then hangs up

​

Press Digits (DTMF)

​

When to Use

• Navigating automated phone menus (e.g., “Press 1 for sales, press 2 for support”)
• Entering account numbers or PINs via keypad
• Interacting with external IVR systems during outbound calls

​

Configuration

1. Navigate to the Tools tab
2. Locate Press Digits under System Tools
3. Toggle the switch to enable
4. Optionally set a Custom Instructions Override to customize when the agent uses this tool
5. Click Save

​

Configuring via API

curl -X PATCH https://api.revring.ai/v1/agents/{agentId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "playKeypadTouchToneEnabled": true,
    "playKeypadTouchToneDescriptionOverride": "Use this to press digits when navigating phone menus."
  }'

​

Advanced Settings

​

Block All Interruptions

​

When to Use

• Delivering important legal disclaimers or disclosures that must be heard in full
• Reading back critical information (order numbers, confirmation codes)
• Playing scripted messages that should not be cut short

​

Configuration

1. Navigate to the Advanced tab
2. Toggle Block All Interruptions to on
3. Click Save

​

Configuring via API

curl -X PATCH https://api.revring.ai/v1/agents/{agentId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "disableInterruptions": true
  }'

​

Custom Tools

​

Use Cases

• CRM lookups: Fetch customer information during calls
• Order status: Check order or shipment status
• Appointment booking: Create or modify appointments in your calendar system
• Payment processing: Initiate payments or check account balances
• Inventory checks: Verify product availability
• Custom business logic: Any operation specific to your workflow

​

Creating a Custom Tool

1. Navigate to the Tools tab
2. Scroll to the Custom Tools section
3. Enter a Friendly Name for your tool (e.g., “Order Status Checker”)
4. Enter your Webhook URL (e.g., https://api.yourcompany.com/tools/check-order)
5. Click Add Tool

​

Defining the Tool Schema

1. Click Edit on your custom tool
2. In the Schema JSON field, enter your tool definition:

{
  "type": "function",
  "name": "check_order_status",
  "description": "Check the status of a customer's order by order ID",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The unique order ID (e.g., ORD-12345)"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

3. Toggle Enabled to activate the tool
4. Click Save

​

Schema Format Reference

• type: Always "function" at the root level (required)
• name: Unique identifier for the tool (lowercase, underscores allowed) (required)
• description: When the agent should use this tool (required)
• parameters: Object defining the tool’s input parameters (required)
  • type: Always "object" for the parameters root (required)
  • properties: Each parameter with its type and description (use {} for tools with no inputs)
  • required: Array of required parameter names (optional)

{
  "type": "function",
  "name": "get_current_weather",
  "description": "Get the current weather",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}

​

Advanced Webhook Settings

curl -X POST https://api.revring.ai/v1/agents/{agentId}/custom-tools \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check Order",
    "webhookUrl": "https://api.yourcompany.com/tools/check-order",
    "httpMethod": "POST",
    "headers": [
      { "key": "Authorization", "value": "Bearer your-token" }
    ],
    "queryParams": [
      { "key": "source", "value": "revring" }
    ],
    "sendRawRequestBody": false,
    "enabled": true,
    "schema": {
      "type": "function",
      "name": "check_order_status",
      "description": "Check order status by order ID",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "The order ID" }
        },
        "required": ["order_id"]
      }
    }
  }'

​

Webhook Request Format

{
  "callId": "dc582fd6-4e5c-4860-9ced-abc7390e62a9",
  "tool": "check_order_status",
  "arguments": {
    "order_id": "ORD-12345"
  }
}

{
  "order_id": "ORD-12345"
}

{
  "status": "out_for_delivery",
  "expected_delivery": "2025-11-24T17:00:00Z",
  "tracking_number": "1Z999AA10123456784"
}

Order ORD-12345 is currently out for delivery. Expected delivery today by 5 PM.

​

Response Format

• 200 OK status code
• JSON object or plain text response body
• Response within 8 seconds (recommended: under 3 seconds for best user experience)

{
  "appointments": [
    {
      "date": "2025-11-25",
      "time": "14:00",
      "type": "checkup"
    }
  ],
  "total_count": 3
}

Customer has 3 active appointments. Next appointment is tomorrow at 2 PM.

​

Best Practices for Custom Tools

​

Clear Descriptions

Check the status of a customer's order by order ID. Use this when the customer asks about their order, shipment, or delivery status.

Check order

​

Error Handling

{
  "error": "order_not_found",
  "message": "Order number not found in system"
}

I couldn't find that order number in our system. Could you verify the order number?

​

Performance

• Keep webhook response times under 3 seconds
• Implement timeouts and retries in your webhook code
• Cache frequently accessed data when possible
• Use async processing for complex operations (return immediately with a status message)

​

Security

• Validate requests are coming from RevRing (contact support for HMAC signing setup)
• Sanitize and validate all input parameters
• Use HTTPS for all webhook URLs
• Implement rate limiting to prevent abuse

​

Testing Custom Tools

1. Create a simple test tool that returns static data
2. Use the test panel to make a call
3. During the call, prompt the agent to use the tool:
   • “Can you check order ORD-12345 for me?”
4. Review the transcript to see:
   • Tool invocation with arguments
   • Your webhook’s response
   • How the agent incorporated the result into conversation

​

Viewing Tool Invocations

• Tool name: Which tool was invoked
• Arguments: What parameters were passed
• Status: Success (ok) or error
• Response: What your webhook returned

​

Tool Limitations

​

System Tool Constraints

• End Call: Once invoked, the call ends immediately - the agent cannot continue conversation
• Transfer: After transfer, the agent disconnects - the call continues with the transfer destination
• Voicemail Detection: Only works on outbound calls, not inbound calls

​

Custom Tool Constraints

• Response time: 8 second timeout - webhooks must respond within this window
• Concurrent invocations: Agents invoke tools sequentially, not in parallel

​

Managing Tools

​

Editing Tools

1. Navigate to the Tools tab
2. Click Edit on the tool in the table
3. Update friendly name, webhook URL, schema, or enabled status
4. Click Save

​

Deleting Tools

1. Navigate to the Tools tab
2. Click Delete on the tool in the table
3. Confirm the deletion

​

Disabling Tools Temporarily

1. Click Edit on the tool
2. Toggle Enabled to off
3. Click Save

​

Advanced Tool Patterns

​

Chaining Tools

1. Customer asks: “What’s my balance and when is my next payment due?”
2. Agent invokes get_account_balance → receives balance
3. Agent invokes get_next_payment_date → receives date
4. Agent combines both results in response

​

Conditional Tool Usage

Use the transfer_to_billing tool only when:
- Customer has billing questions you cannot answer
- Customer disputes a charge
- Customer wants to discuss payment plans

Do NOT transfer for simple balance inquiries - use the check_balance tool instead.

​

Tool Results in Follow-Up

Agent: “I checked your order ORD-12345, and it’s out for delivery today.” Customer: “Great! And what about my other order?” Agent: “Let me check that for you…” [invokes tool again with new order ID]

​

Troubleshooting

​

Next Steps