> ## 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.
# Recipients & Status
> Manage recipients, track call statuses, and understand call outcomes
## Overview
Each batch call contains one or more recipients. The system tracks individual call statuses for each recipient, providing detailed visibility into batch call execution.
## Recipient Call Statuses
Recipients move through various call statuses during batch call execution:
| Status | Meaning | Description |
| ---------------- | --------------------------- | ------------------------------------ |
| **PENDING** | Waiting | Recipient is waiting to be processed |
| **QUEUED** | In queue | Call is queued waiting for capacity |
| **IN\_PROGRESS** | Call in progress | Call is currently active |
| **COMPLETED** | Call completed successfully | Call finished successfully |
| **FAILED** | Call failed | Call encountered an error |
| **NO\_ANSWER** | Recipient did not answer | Recipient did not answer the call |
Statuses are updated in real-time as calls progress. Use the Reload action to refresh recipient statuses.
## Status Lifecycle
### Typical Flow
```
PENDING → QUEUED → IN_PROGRESS → COMPLETED
↓
FAILED
↓
NO_ANSWER
```
**Flow Explanation:**
1. **PENDING**: Recipient added, waiting to be processed
2. **QUEUED**: Call queued waiting for available capacity
3. **IN\_PROGRESS**: Call is actively in progress
4. **COMPLETED**: Call finished successfully
5. **FAILED**: Call encountered an error (alternative to COMPLETED)
6. **NO\_ANSWER**: Recipient did not answer (alternative to COMPLETED)
### Status Transitions
**Normal Completion:**
* PENDING → QUEUED → IN\_PROGRESS → COMPLETED
**Failure Paths:**
* IN\_PROGRESS → FAILED (call error)
* IN\_PROGRESS → NO\_ANSWER (no answer)
**Retry Behavior:**
* FAILED → PENDING (when batch call is retried)
* NO\_ANSWER → PENDING (when batch call is retried)
## Viewing Recipients
### Recipients List
The recipients list shows all recipients in the batch call:
**Displayed Information:**
* Phone number
* Name (if provided)
* Current status
* Dynamic variables (if any)
**List Features:**
* Sort by status
* Filter by status
* Search by phone number or name
* View call details (for COMPLETED and FAILED)
### Status Filtering
Filter recipients by status:
* **All** - Show all recipients
* **PENDING** - Waiting to be processed
* **QUEUED** - In queue
* **IN\_PROGRESS** - Currently active
* **COMPLETED** - Successfully completed
* **FAILED** - Failed calls
* **NO\_ANSWER** - No answer
### Status Counts
The recipients view displays counts for each status:
* Total recipients
* Count per status
* Progress percentage
* Visual status distribution
## Call Details Drawer
### Availability
Call details are available only for:
* **COMPLETED** recipients
* **FAILED** recipients
Call details provide comprehensive information about the call outcome, including duration, transcript, and error information.
### Accessing Call Details
1. Navigate to batch call recipients list
2. Find a COMPLETED or FAILED recipient
3. Click on the recipient row
4. Call details drawer opens
### Information Shown
**For COMPLETED Calls:**
* Call duration
* Start time
* End time
* Call transcript (if available)
* Agent responses
* User interactions
* Dynamic variables used
**For FAILED Calls:**
* Failure reason
* Error message
* Attempt time
* Failure type
* Retry eligibility
## Retry Behavior
### When Batch Calls Are Retried
Batch Calls can be retried when:
* Batch Call status is FAILED
* Batch Call status is CANCELLED
* Batch Call status is COMPLETED (with failures)
### Which Recipients Are Retried
**Retried:**
* **FAILED** recipients
* **NO\_ANSWER** recipients
**Skipped:**
* **COMPLETED** recipients (not retried)
Retry uses the same batch call ID and only attempts calls for recipients that failed or didn't answer. Successfully completed calls are preserved and not retried.
### Retry Process
1. Batch Call is retried (via Retry action)
2. Status changes to RUNNING
3. FAILED and NO\_ANSWER recipients change to PENDING
4. COMPLETED recipients remain COMPLETED
5. Batch Call processes retry recipients
## Dynamic Variables
### Overview
Dynamic variables are additional data passed to the agent for each recipient. They enable per-recipient personalization.
### How Variables Work
**In CSV:**
| phone\_number | name | plan | language |
| ------------- | ---- | ----- | -------- |
| +12025551234 | John | Pro | EN |
| +12025551235 | Jane | Basic | ES |
**In Batch Call:**
* `plan` and `language` are dynamic variables
* Passed as key-value pairs to the agent
* Available for agent to reference
### Variable Usage
**Important:**
* Variables are only used if the Voice Agent explicitly references them
* If a variable is not used by the agent, it is ignored
* No error is raised if variables are unused
* Call behavior is unaffected by unused variables
**Example:**
```
Agent prompt: "Hello {{name}}, you have a {{plan}} plan."
Variables: name="John", plan="Pro"
Result: "Hello John, you have a Pro plan."
```
### Viewing Variables
**In Recipients List:**
* Dynamic variables shown as columns
* Editable during CSV validation
* Read-only after batch call creation
**In Call Details:**
* Variables shown in call information
* Values used during call displayed
* Helps verify personalization
## Recipient Management
### Adding Recipients
**During Creation:**
* Upload CSV file
* Validate recipients
* Fix rejected rows
* Confirm to add
**After Creation:**
* Recipients cannot be added after batch call creation
* Create new batch call for additional recipients
### Editing Recipients
**Before Batch Call Start:**
* Edit during CSV validation
* Fix rejected rows
* Update dynamic variables
**After Batch Call Start:**
* Recipients cannot be edited
* Data is locked for consistency
### Removing Recipients
**Before Batch Call Start:**
* Remove rejected rows during validation
* Don't add to batch call
**After Batch Call Start:**
* Recipients cannot be removed
* All recipients are processed
## Status Monitoring
### Real-Time Updates
**Automatic Updates:**
* Statuses update in real-time
* No manual refresh needed
* Changes appear automatically
**Manual Refresh:**
* Use Reload action to force refresh
* Fetches latest data from server
* Updates all recipient statuses
### Progress Tracking
**Visual Indicators:**
* Progress bar showing completion
* Status counts and percentages
* Color-coded status indicators
**Metrics:**
* Total recipients
* Completed count
* Failed count
* No answer count
* Pending count
* In progress count
## Troubleshooting
### Recipients Stuck in PENDING
**Possible Causes:**
* Batch Call is PAUSED
* Batch Call is SCHEDULED (not started)
* All capacity used
* Time range constraints
**Solutions:**
* Check batch call status
* Verify time range settings
* Wait for capacity
* Resume if paused
### High Failure Rate
**Possible Causes:**
* Invalid phone numbers
* Network issues
* Agent configuration problems
* System errors
**Solutions:**
* Review failure reasons
* Check phone number validity
* Verify agent configuration
* Contact support if persistent
### Status Not Updating
**Possible Causes:**
* Real-time updates delayed
* Browser cache issues
* Network problems
**Solutions:**
* Use Reload action
* Refresh page
* Check network connection
* Wait a few moments
## Next Steps
* **[Managing Batch Calls](./managing-batch-calls)** - Control batch call execution
* **[Creating Batch Calls](./creating-batch-calls)** - Learn how to add recipients
* **[Best Practices](./best-practices)** - Optimize recipient management
## Related Documentation
Control batch call execution and status
Learn how to upload and validate recipients
Optimize recipient management