Last updated: 2025-10-05•Location: AI Agents > Voice Agent > External APIs Tab

AI Voice Agents - Overview Voice Agent Conditional Tools

Voice Agent External APIs

Overview

External API Tools allow your voice agent to fetch real-time data from external REST APIs during phone calls (or post data to them). When a caller asks for information that requires a database lookup or third-party system check, the AI can make an API call, retrieve the data, and respond immediately - all during the conversation.

Note: This feature is unique to voice agents and not available for text agents.

What External APIs Enable

Real-Time Data Lookups:

Order status checking
Account balance inquiries
Inventory availability
Ticket status in support systems
Custom CRM data
Real-time pricing
Appointment availability in external systems

Example Scenario:

Caller: "What's the status of my order #12345?" Agent: "Let me check that for you..." [Makes API call] API Returns: Order status "shipped" Agent: "Your order was shipped yesterday and should arrive tomorrow!"

All happens in real-time during the call.

Creating an External API Tool

Step 1: In the External APIs tab, click "Add API Tool"

Step 2: Configure the tool (see sections below)

Step 3: Test the API tool (to ensure the api actually responds how you expect)

Step 4: Save the agent

API Tool Configuration

General Settings

Name (Required)

Descriptive name the AI sees
Example: "Order Status Lookup", "Inventory Check", "Account Balance"

Description

Tell the AI what this tool does and when to use it
Example: "Use this to check the status of a customer's order by order number"
Be clear about when it's appropriate to call this API

Endpoint Configuration

Endpoint URL (Required)

Full URL to the API endpoint
Example: "https://api.yourcrm.com/orders"
For GET/DELETE: Parameters added as query string automatically
For POST/PUT/PATCH: Endpoint URL is used as-is, parameters sent in JSON body

HTTP Method

GET - Retrieve data (parameters sent as query string)
POST - Send data (parameters sent as JSON body)
PUT - Update data (parameters sent as JSON body)
PATCH - Partial update (parameters sent as JSON body)
DELETE - Remove data (parameters sent as query string)
Most lookups use GET or POST

Headers

Add any required HTTP headers:

Common Headers:

Content-Type: application/json
Accept: application/json
X-API-Key: your-key (if not using auth config)

Add Header:

Enter header name
Enter header value
Click add

Authentication

Authentication Type:

None

No authentication required
Public API or custom header authentication

Bearer Token

Uses bearer token in Authorization header
Token: Your API token/key

API Key

Custom API key header
Key Name: Header name (e.g., "X-API-Key")
Key Value: Your API key

Basic Auth

Username and password authentication
Username: Your username
Password: Your password/token

Parameters

Define parameters the AI can pass to the API.

How Parameters Are Sent:

GET and DELETE requests:

Parameters sent as query parameters in the URL
Example: https://api.example.com/orders?order_id=12345&[email protected]
brayv.ai automatically constructs the query string

POST, PUT, and PATCH requests:

Parameters sent in request body as JSON
Content-Type: application/json (automatic)
Example body: {"order_id": "12345", "customer_email": "[email protected]"}
brayv.ai automatically constructs the JSON body

For Each Parameter:

Name (Required)

Parameter name expected by the API
Example: "order_id", "customer_email", "zip_code"

Type

string, number, boolean, array, object

Description (Required)

Tell AI what this parameter is
Example: "the customer's order number. No whitespace, only digits. Example: '234098'"
Example: "the customer's email address. No whitespace, Example: '[email protected]'"

Required

Toggle if this parameter is mandatory
API call won't be made if required parameter missing

Default Value (Optional)

Default if AI doesn't provide value
Example: "active" for a status parameter

Where Parameters Come From:

The AI extracts parameters from:

Conversation context (caller mentions order #12345)
Information the AI has access to at the start of the call (included in its instructions with variables, Example: the contact's phone number is {contact.phone})

Response Messages

Request Start Message

What agent says while making the API call
Default: "Let me check that for you."
Keep it natural: "One moment...", "Let me look that up..."

Request Failed Message

What agent says if API call fails
Default: "I'm having trouble accessing that information."

Example API Tool Configurations

Example 1: Order Status Lookup (GET)

General:

Name: "Order Status Lookup"
Description: "Check the status of a customer order. Use when customer asks about their order status and provides an order number."

Endpoint:

URL: "https://api.yoursystem.com/orders"
Method: GET

Auth:

Type: Bearer Token
Token: [Your API token]

Parameters:

Name: order_id
Type: string
Description: "the customer's order number"
Required: Yes

How It Works:

AI extracts order_id from conversation
Request sent: GET https://api.yoursystem.com/orders?order_id=12345
Response used to answer caller

Messages:

Start: "Let me check on that order for you..."
Failed: "I'm having trouble accessing our order system. Let me have someone call you back with that information."

Example 2: Inventory Check (POST)

General:

Name: "Product Availability"
Description: "Check if a product is in stock. Use when customer asks about availability of a specific product."

Endpoint:

URL: "https://api.inventory.com/check"
Method: POST

Auth:

Type: API Key
Key Name: X-API-Key
Key Value: [Your key]

Parameters:

Name: product_id
Type: string
Description: "the product SKU or ID"
Required: Yes
Name: location
Type: string
Description: "store location or zip code"
Required: No
Default: "main"

How It Works:

AI extracts product_id (and location if mentioned)
Request sent: POST https://api.inventory.com/check
Body: {"product_id": "ABC123", "location": "main"}
Content-Type: application/json (automatic)
Response used to answer caller

Messages:

Start: "Checking inventory..."
Failed: "I can't access our inventory system right now, but I can have someone check and call you back."

Example 3: Customer Account Lookup (GET)

General:

Name: "Account Information"
Description: "Look up customer account details by email or phone number"

Endpoint:

URL: "https://crm.yourcompany.com/api/customers"
Method: GET

Parameters:

Name: email
Type: string
Description: "the customer's email address from their contact record"
Required: No
Name: phone
Type: string
Description: "the customer's phone number"
Required: No

How It Works:

AI uses contact data (email or phone from contact record)
Request sent: GET https://crm.yourcompany.com/api/[email protected]&phone=5551234567
Response used to provide account information

Messages:

Start: "Let me pull up your account..."
Failed: "I'm having trouble accessing account information. Can I have someone call you back?"

Testing API Tools

In the API Tool Configuration:

Step 1: Click "Test" button

Step 2: Enter test parameter values

Step 3: Run test

Step 4: Review:

HTTP response code
Response data
Any errors
Response time

Step 5: Adjust configuration if needed

Before Going Live:

Test with valid data
Test with invalid data
Test with missing parameters
Verify error handling
Check response times

How External APIs Work During Calls

Normal Flow

Caller asks question requiring API data
AI recognizes it needs to use the tool
AI extracts required parameters from conversation or contact data
Agent says request start message
API call is made
Response received
AI interprets response data
Agent answers caller's question using the data
Call continues

Timing:

Most API calls: 1-3 seconds
Caller experiences brief pause (like human would take to look something up)
Keep timeout reasonable (5-10 seconds max)

If API Fails

API call times out or returns error
Agent says request failed message
Call continues
Agent can offer alternative (callback, manual lookup, etc.)

Parameter Passing Examples

GET Request Example

Configuration:

Endpoint: https://api.example.com/customers
Method: GET
Parameters: customer_id (string), include_orders (boolean)

Actual Request:

GET https://api.example.com/customers?customer_id=12345&include_orders=true

POST Request Example

Configuration:

Endpoint: https://api.example.com/orders
Method: POST
Parameters: customer_id (string), product_id (string), quantity (number)

Actual Request:

POST https://api.example.com/orders
Content-Type: application/json

{
  "customer_id": "12345",
  "product_id": "ABC789",
  "quantity": 2
}

DELETE Request Example

Configuration:

Endpoint: https://api.example.com/items
Method: DELETE
Parameters: item_id (string)

Actual Request:

DELETE https://api.example.com/items?item_id=67890

Best Practices

Keep Timeouts Short

Recommended: 2-5 seconds maximum

Longer waits feel awkward on phone calls
Caller may hang up
Can always offer callback if lookup takes longer

Provide Helpful Fallback Messages

Good Failed Message: ✅ "I'm having trouble accessing that right now. Can I have someone call you back with that information within the hour?"

Unhelpful: ❌ "Error" ❌ "That didn't work"

Secure Your APIs

External APIs are called from brayv.ai servers:

Use authentication
Don't expose sensitive endpoints publicly
Rate limit your APIs if needed
Monitor for unusual activity

Test Thoroughly

Test Scenarios:

Valid requests
Invalid parameters
Missing parameters
API timeout
API error responses
Slow API responses

Use for Read Operations Primarily

Good Use Cases:

GET requests to fetch data
Read-only lookups
Status checks

Be Careful With:

POST/PUT/DELETE requests
Operations that modify data
Irreversible actions

Clear Tool Descriptions

The AI uses your description to decide when to use the tool:

Be specific about when it's appropriate
Mention what parameters are needed
Example: "Use when customer provides an order number and wants to check status"

Common Use Cases

E-Commerce: Order Tracking

API Tool: Order Status Lookup When Used: Customer asks about their order Data Returned: Order status, tracking number, estimated delivery Agent Response: Provides current status and next steps

Support Desk: Ticket Status

API Tool: Support Ticket Lookup When Used: Customer asks about their support ticket Data Returned: Ticket status, assigned agent, resolution timeline Agent Response: Updates customer on ticket progress

Scheduling: External Calendar Check

API Tool: External Availability Lookup When Used: Checking availability in system not integrated with brayv.ai Data Returned: Available time slots Agent Response: Presents options to caller

Account Management: Balance Inquiry

API Tool: Account Balance Check When Used: Customer asks about balance or payment status Data Returned: Current balance, payment history Agent Response: Provides balance and payment options

Troubleshooting

Problem: API not being called during calls

Solution:

Check tool description is clear
Verify AI understands when to use it
Ensure required parameters are available
Add EXPLICIT guidance in the "Instructions" tab for when in the conversation, the AI should use this API tool. (E.g. "Immediately after the user confirms their order number, execute your Lookup Customer Order tool")
Test tool independently

Problem: API timing out

Solution:

Increase timeout (but keep under 15 seconds)
Verify API endpoint is accessible
Check API response time independently
Consider caching for slow endpoints
Use request failed message gracefully

Problem: Wrong parameters being passed

Solution:

Review parameter descriptions
Ensure parameter names match API expectations
Check parameter types are correct
Verify AI has access to needed data
Test with specific scenarios

Problem: AI not interpreting API response correctly

Solution:

Simplify API response structure
Return only necessary data
Use clear field names in response
Test with different response formats
Check API returns expected data types

Problem: Authentication failing

Solution:

Verify auth credentials are correct
Check token hasn't expired
Ensure auth type matches API requirements
Test authentication independently
Review API logs for auth errors

Related Features

AI Voice Agents Overview - Main voice agent guide
Voice Conditional Tools - Actions during calls
Voice Field Extractors - Save conversation data

Related Articles

Voice Agent External APIs

Overview

What External APIs Enable

Creating an External API Tool

API Tool Configuration

General Settings

Endpoint Configuration

Headers

Authentication

Parameters

Response Messages

Example API Tool Configurations

Example 1: Order Status Lookup (GET)

Example 2: Inventory Check (POST)

Example 3: Customer Account Lookup (GET)

Testing API Tools

How External APIs Work During Calls

Normal Flow

If API Fails

Parameter Passing Examples

GET Request Example

POST Request Example

DELETE Request Example

Best Practices

Keep Timeouts Short

Provide Helpful Fallback Messages

Secure Your APIs

Test Thoroughly

Use for Read Operations Primarily

Clear Tool Descriptions

Common Use Cases

E-Commerce: Order Tracking

Support Desk: Ticket Status

Scheduling: External Calendar Check

Account Management: Balance Inquiry

Troubleshooting

Problem: API not being called during calls

Problem: API timing out

Problem: Wrong parameters being passed

Problem: AI not interpreting API response correctly

Problem: Authentication failing

Related Features