> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Making Outbound Calls

> Learn how to make outbound calls using your phone numbers and Voice Agents

## Overview

The outbound calling feature allows you to place test calls directly from the Hamsa dashboard using your configured phone numbers and Voice Agents. This is ideal for testing agent behavior, validating configurations, and demonstrating agent capabilities.

<Info>
  **Outbound calls enable you to:**

  * Test Voice Agents before production deployment
  * Validate phone number configurations
  * Demonstrate agent capabilities to stakeholders
  * Pass custom parameters for personalized conversations
  * Configure webhooks for call event notifications
</Info>

<Info>
  **Individual Calls vs Batch Calls:**

  * **Individual Calls** (this page): Make single test calls from the dashboard - perfect for testing and demonstrations
  * **[Batch Calls](/agents/batch-calls/introduction)**: Execute batch calls to multiple recipients - ideal for production use
  * Both use the same phone numbers, but serve different purposes
</Info>

## Prerequisites

Before making outbound calls, ensure:

**Phone Number Configuration:**

* Phone number is added to the system
* Number is assigned to a Voice Agent
* Provider credentials are valid (Twilio or SIP)

**Voice Agent:**

* Agent exists and is properly configured
* Agent is assigned to the phone number
* Agent has been tested in browser

**Project Configuration:**

* Active project is selected
* API key is configured in project settings
* Sufficient concurrency available in your plan

**Other:**

* Valid destination phone number
* Network connectivity

<Info>
  **Supported Providers:**

  * Both Twilio and SIP trunk support outbound calls
  * Ensure your provider account has sufficient balance or connectivity
</Info>

## Making a Basic Outbound Call

### Step 1: Access Outbound Call Feature

1. **Navigate to Phone Numbers**
   * Go to Dashboard → Phone Numbers
   * View list of configured phone numbers

2. **Select Phone Number**
   * Click on the phone number you want to use
   * Ensure it's assigned to a Voice Agent
   * Details panel opens

3. **Click Make Outbound Call**
   * In the details header, click "Make Outbound Call" button
   * Button is enabled only when:
     * Phone number is assigned to an agent
     * Agent exists in the system
     * API key is configured
     * Provider supports outbound calls

### Step 2: Configure Call Details

**Destination Phone Number:**

* Enter in E.164 format (e.g., +12025551234)
* Must include country code
* Must start with '+'
* No spaces or special characters

**Validation:**

* System validates format
* Invalid numbers show error message
* Must be a valid phone number

### Step 3: Initiate Call

1. **Review Settings**
   * Verify destination number
   * Check source number
   * Confirm assigned agent

2. **Click "Make Call"**
   * Call is initiated immediately
   * Modal closes automatically
   * System displays success notification

3. **Answer Call**
   * Answer the phone at the destination number
   * Voice Agent begins conversation
   * Interact with agent as needed

### Step 4: Monitor Call

1. **View in Call History**
   * Navigate to Call History
   * Find your call in the list
   * Shows status: IN\_PROGRESS → COMPLETED

2. **Review Call Details**
   * Click the call to see details
   * View conversation transcript
   * Check call logs
   * Review outcomes

## Advanced Outbound Call Options

### Custom Parameters

Pass dynamic variables to personalize the agent's conversation.

**Use Cases:**

* Customer name for personalized greeting
* Order number for order status calls
* Appointment details for reminders
* Account information for verification

**How to Add:**

1. In the outbound call modal
2. Scroll to "Custom Parameters" section
3. Click "Add Parameter"
4. Enter key and value:
   * Key: Variable name (e.g., 'customer\_name')
   * Value: Variable value (e.g., 'John Smith')
5. Add multiple parameters as needed
6. Remove parameters by clicking delete icon

**Example:**

| Key               | Value      |
| ----------------- | ---------- |
| customer\_name    | John Smith |
| order\_number     | ORD-12345  |
| appointment\_date | 2026-01-25 |
| appointment\_time | 2:00 PM    |

**In Voice Agent Prompt:**

```
You are a helpful assistant. You are calling {customer_name} 
about order {order_number}. The appointment is scheduled for 
{appointment_date} at {appointment_time}.
```

<Info>
  **Parameter Requirements:**

  * Keys must be referenced in the Voice Agent's prompt or flow
  * Unused parameters are ignored (no error)
  * Values can be strings, numbers, or basic types
  * No validation on parameter format
</Info>

### Webhook Configuration

Configure webhooks to receive real-time call event notifications.

**Supported Events:**

* Call initiated
* Call answered
* Call in progress
* Call completed
* Call failed

**How to Configure:**

1. **Enable Webhooks**
   * In outbound call modal
   * Toggle "Enable Webhook" switch

2. **Enter Webhook URL**
   * Must be HTTPS URL
   * Must be publicly accessible
   * Must return 200 status for delivery
   * Example: `https://api.example.com/call-events`

3. **Configure Authentication (Optional)**
   * **API Key**: Simple key-based authentication
     * Add header: `X-API-Key: your-api-key`
   * **Bearer Token**: JWT or OAuth token
     * Add header: `Authorization: Bearer your-token`
   * **Basic Auth**: Username and password
     * Add header: `Authorization: Basic base64(user:pass)`

4. **Test Webhook**
   * Use webhook testing tools
   * Verify your endpoint receives events
   * Check event payload structure

**Webhook Payload Example:**

```json theme={null}
{
  "event": "call.completed",
  "call_id": "call_abc123xyz",
  "timestamp": "2026-01-22T10:30:00Z",
  "from_number": "+12025551234",
  "to_number": "+12025555678",
  "duration": 125,
  "status": "COMPLETED",
  "cost": 0.015,
  "conversation": {
    "transcript": "...",
    "summary": "..."
  }
}
```

<Warning>
  **Webhook Security:**

  * Always use HTTPS endpoints
  * Implement authentication
  * Validate webhook signatures if available
  * Rate limit your webhook endpoint
  * Log webhook events for debugging
</Warning>

## Use Cases

### Testing Voice Agent Configuration

**Scenario**: Verify agent behavior before production

**Steps:**

1. Configure Voice Agent with desired prompts and tools
2. Assign agent to test phone number
3. Make outbound call to your own phone
4. Interact with agent to test:
   * Greeting and introduction
   * Question answering
   * Tool executions
   * Call flow logic
   * Error handling
5. Review call in Call History
6. Iterate on agent configuration as needed

**Benefits:**

* Low-risk testing environment
* Immediate feedback
* No impact on production calls
* Easy iteration

### Demonstrating Agent Capabilities

**Scenario**: Show stakeholders what the agent can do

**Steps:**

1. Prepare demonstration script
2. Configure agent with relevant knowledge base
3. Set up outbound call to stakeholder's phone
4. Add custom parameters for personalized demo
5. Place call during presentation
6. Show live interaction
7. Review Call History together

**Benefits:**

* Live demonstration
* Real phone experience
* Builds confidence
* Immediate feedback

### Appointment Reminders

**Scenario**: Automated appointment reminder calls

**Steps:**

1. Create appointment reminder Voice Agent
2. Assign to outbound phone number
3. Prepare appointment details as parameters
4. Make call with parameters:
   * patient\_name: 'Jane Doe'
   * appointment\_date: '2026-01-25'
   * appointment\_time: '2:00 PM'
   * doctor\_name: 'Dr. Smith'
5. Agent delivers personalized reminder
6. Configure webhook to track confirmations

**Benefits:**

* Automated reminders
* Personalized experience
* Reduced no-shows
* Cost-effective

### Order Status Updates

**Scenario**: Proactive customer communication

**Steps:**

1. Create order update Voice Agent
2. Configure with order tracking knowledge
3. Make call with order parameters:
   * customer\_name: 'John Smith'
   * order\_number: 'ORD-12345'
   * tracking\_number: 'TRACK-789'
   * delivery\_date: '2026-01-24'
4. Agent provides order status
5. Webhook captures customer response

**Benefits:**

* Proactive communication
* Improved customer satisfaction
* Reduced support inquiries
* Scalable solution

## Limitations and Considerations

### Call Limitations

**Provider Limits:**

* Subject to provider's rate limits
* Geographic restrictions may apply
* Cost per call varies by destination
* Some countries may be blocked

**Platform Limits:**

* Concurrent calls limited by your plan
* API key required for all calls
* Outbound call history tracked
* Cost deducted from your account

**Provider-Specific:**

**Twilio:**

* Uses Twilio account balance
* Subject to Twilio's compliance rules
* May require caller ID verification
* Some regions require local numbers

**SIP Trunk:**

* Depends on trunk configuration
* May require carrier approval
* Custom routing rules apply
* Authentication must be configured

## Troubleshooting

### Cannot Make Outbound Call

**Button Disabled:**

Check if:

* Phone number is assigned to a Voice Agent
* Voice Agent exists and is not deleted
* API key is configured in project settings
* You have sufficient permissions

**Solutions:**

* Assign Voice Agent if unassigned
* Verify agent exists in Voice Agents section
* Configure API key in project settings
* Check provider type
* Contact administrator for permissions

### Call Fails to Connect

**Possible Causes:**

* Invalid destination number format
* Destination number blocked by provider
* Insufficient balance (Twilio)
* Network connectivity issues
* SIP trunk misconfiguration

**Solutions:**

* Verify E.164 format (+country code)
* Check provider account status
* Ensure sufficient balance
* Test with known working number
* Review SIP trunk configuration
* Check Call History for error details

### Agent Not Responding

**Possible Causes:**

* Voice Agent configuration issues
* LLM API errors
* Knowledge base not processing
* Tool integration failures

**Solutions:**

* Test agent in browser first
* Check agent configuration
* Verify LLM API key is valid
* Review knowledge base status
* Check tool configurations
* Review call logs in Call History

### Webhook Not Receiving Events

**Possible Causes:**

* Invalid webhook URL
* URL not publicly accessible
* Firewall blocking requests
* Authentication failing
* Endpoint returning errors

**Solutions:**

* Verify URL is correct and HTTPS
* Test with webhook testing tools
* Check firewall rules
* Verify authentication credentials
* Monitor endpoint logs
* Return 200 status code

## Related Documentation

<CardGroup cols={2}>
  <Card title="Introduction" href="./introduction">
    Overview of Phone Numbers features
  </Card>

  <Card title="Managing Phone Numbers" href="./managing-numbers">
    Add and configure phone numbers
  </Card>

  <Card title="Batch Calls" href="/agents/batch-calls/introduction">
    Use your phone numbers for batch calls
  </Card>

  <Card title="Creating Batch Calls" href="/agents/batch-calls/creating-batch-calls">
    Learn how to use phone numbers in batch calls
  </Card>

  <Card title="Call History" href="/agents/call-history/introduction">
    Track and monitor all calls
  </Card>
</CardGroup>