> ## 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.

# Voice Agents

> Build intelligent AI voice agents for phone calls in Arabic and English

> Learn how to build, deploy, and scale AI voice agents with Hamsa.

## Overview

Hamsa [Voice Agents Platform](/agents/introduction) enables you to build intelligent conversational AI that handles phone calls naturally in Arabic and English. Create voice agents that can understand multiple Arabic dialects, respond appropriately, and take actions based on conversation context.

Your voice agents can:

* Handle inbound and outbound phone calls automatically
* Deploy on websites using our [Voice Agents SDK](https://www.npmjs.com/package/@hamsa-ai/voice-agents-sdk)
* Understand and respond in English and multiple Arabic dialects
* Access your company's knowledge base for accurate information
* Execute actions through custom tools and API integrations
* Transfer calls to human agents when needed
* Collect and validate data from callers
* Make intelligent decisions based on conversation flow

<CardGroup cols={2}>
  <Card title="Products" icon="duotone book-user" href="/agents/introduction">
    Step-by-step guide for building voice agents in Hamsa Platform.
  </Card>

  <Card title="Developers" icon="duotone code" href="/developers/quickstart">
    Learn how to integrate voice agents into your application via API.
  </Card>
</CardGroup>

## Agent types

Hamsa offers two distinct approaches for building voice agents:

### Single Prompt Agent

Perfect for straightforward use cases with linear conversation flows. Simply write a prompt describing your agent's behavior, and it handles the conversation naturally.

<Card title="Single Prompt Agent" icon="file-lines" href="/agents/single-prompt/overview">
  Simple, fast, and effective for basic customer support, lead qualification, and information gathering
</Card>

**Best for:**

* Simple information gathering
* Basic customer support
* Appointment booking and reminders
* Lead qualification
* Quick prototypes and MVPs

**Key features:**

* Setup in minutes
* Natural conversation flow
* Knowledge base integration
* Custom tools support
* Webhook notifications

### Flow Agent

Build sophisticated conversation flows with a visual node-based editor. Design complex multi-step processes with conditional logic, DTMF support, and advanced routing.

<Card title="Flow Agent" icon="diagram-nodes" href="/agents/flow-agent/overview">
  Advanced workflows with 8 node types, conditional logic, visual debugging, and DTMF support
</Card>

**Best for:**

* Multi-step processes with conditional logic
* Complex customer service workflows
* IVR menus and call routing
* Advanced call transfers
* Integration-heavy applications
* DTMF data collection

**Key features:**

* Visual flow designer
* 8 specialized node types
* Advanced variable system
* DTMF support (3 modes)
* Agent-to-agent transfers
* Real-time debugging

## Quick comparison

| Feature               | Single Prompt | Flow Agent                 |
| --------------------- | ------------- | -------------------------- |
| **Setup Time**        | Minutes       | Hours                      |
| **Visual Design**     | No            | Yes                        |
| **Conditional Logic** | Limited       | Unlimited                  |
| **DTMF Support**      | No            | Yes (3 features)           |
| **Variable System**   | Basic         | Advanced (16+ system vars) |
| **Agent Transfer**    | No            | Yes                        |
| **Call Routing**      | Simple        | Advanced                   |
| **Best For**          | Simple flows  | Complex workflows          |

## Platform capabilities

### Natural conversations in Arabic

Built specifically for Arabic markets, Hamsa voice agents understand and respond naturally in multiple Arabic dialects:

* **Dialect understanding**: Recognize Egyptian, Gulf, Levantine, North African, and other Arabic dialects
* **Natural responses**: Generate contextually appropriate responses in the caller's dialect
* **Code-switching**: Handle mixed Arabic-English conversations naturally
* **Cultural context**: Understand cultural nuances and expressions specific to each region

### Knowledge Base integration

Give your voice agents access to your company's information:

**Document Upload**

* Support for PDF, DOCX, TXT, HTML, and EPUB files
* Up to 21MB per file
* Automatic content extraction and indexing

**Website Scraping**

* Enter any domain URL to scan for content
* Real-time sitemap streaming with progress updates
* URLs grouped by subdomain for easy selection
* Select up to 100 URLs per knowledge base item
* Add custom URLs not found in sitemap
* Individual URL scraping status tracking

**Text Content**

* Add custom text entries (50-10,000 characters)
* Perfect for FAQs, policies, and quick reference content

**Agent Integration**

* Real-time information retrieval during calls
* Automatic relevance ranking
* Activate/deactivate items per agent

<Card title="Learn More" icon="book" href="/agents/knowledge-base/introduction">
  Explore knowledge base features
</Card>

### Custom Tools & integrations

Connect your voice agents to any external system:

* REST API integrations
* Web client-side tools
* Custom function calling
* Database queries
* CRM integrations
* Payment processing
* Appointment scheduling systems

<Card title="Learn More" icon="wrench" href="/agents/tools/introduction">
  Explore tools and integrations
</Card>

### Telephony features

Enterprise-grade telephony features:

* **Inbound calls**: Assign phone numbers to agents for incoming calls
* **Batch calls**: Launch automated calling campaigns
* **Call forwarding**: Transfer calls to human agents or other systems
* **DTMF support**: Handle keypad input for IVR menus (Flow Agents)
* **Call recording**: Automatic recording and storage of all calls
* **Real-time monitoring**: Monitor active calls in real-time

<Card title="Learn More" icon="phone" href="/agents/telephony/introduction">
  Explore telephony features
</Card>

### Monitoring & analytics

Comprehensive monitoring and analytics:

* **Live call monitoring**: Watch active calls in real-time with live transcripts
* **Call history**: Complete records of all conversations
* **Performance metrics**: Track success rates, call duration, and outcomes
* **Satisfaction scores**: Monitor customer satisfaction trends
* **Conversation analysis**: Review transcripts and identify improvement areas
* **System logs**: Debug with detailed execution logs

<Card title="Learn More" icon="chart-line" href="/agents/dashboard/overview">
  Explore dashboard and monitoring
</Card>

## Use cases

### Customer support

Handle common customer inquiries automatically in Arabic. Provide 24/7 support with agents that understand context and can escalate to humans when needed.

**Example applications:**

* Answer FAQs about products and services
* Check order status and account information
* Handle basic troubleshooting
* Schedule callbacks with human agents

### Lead qualification

Qualify leads automatically through natural conversations in Arabic. Collect information, assess interest levels, and route qualified leads to sales teams.

**Example applications:**

* Initial lead screening
* Information gathering
* Appointment scheduling
* Lead scoring and routing

### Appointment booking

Automate appointment scheduling for healthcare, services, or consultations. Handle booking, rescheduling, and reminders in Arabic.

**Example applications:**

* Medical appointment scheduling
* Service booking and confirmation
* Appointment reminders
* Rescheduling and cancellations

### Surveys & feedback

Conduct surveys and collect feedback through natural phone conversations in Arabic. Higher engagement than traditional IVR systems.

**Example applications:**

* Customer satisfaction surveys
* Post-service feedback
* Market research
* Product feedback collection

### Payment reminders

Send automated payment reminders with natural conversations. Handle common questions and provide payment options.

**Example applications:**

* Bill payment reminders
* Subscription renewal reminders
* Payment plan negotiations
* Payment confirmation

## Best practices

### Designing effective prompts

For Single Prompt Agents:

* Be specific about the agent's role and objectives
* Provide clear examples of desired behavior
* Define boundaries and escalation rules
* Include cultural and dialectal considerations
* Test with various scenarios

<Card title="Learn More" icon="pen" href="/agents/single-prompt/write-prompt">
  Prompt engineering guide
</Card>

### Building robust flows

For Flow Agents:

* Start with a clear flow diagram on paper
* Use Router nodes for complex decision logic
* Implement proper error handling
* Test all possible paths
* Use variables efficiently
* Add fallback options for unexpected inputs

<Card title="Learn More" icon="diagram-project" href="/agents/flow-agent/best-practices">
  Flow Agent best practices
</Card>

### Testing thoroughly

Before deployment:

* Test with different Arabic dialects
* Test edge cases and unexpected inputs
* Verify tool and API integrations
* Check knowledge base responses
* Test call transfers and escalations
* Monitor performance metrics

<Card title="Learn More" icon="vial" href="/agents/testing/introduction">
  Testing guide
</Card>

## Getting started

<Steps>
  <Step title="Choose your agent type">
    Decide between Single Prompt or Flow Agent based on complexity
  </Step>

  <Step title="Configure basic settings">
    Set up voice, language, LLM model, and behavior settings
  </Step>

  <Step title="Design conversation">
    Write prompts or design visual flow with nodes
  </Step>

  <Step title="Add integrations">
    Connect knowledge bases, tools, and webhooks
  </Step>

  <Step title="Test thoroughly">
    Test in browser and via phone with different scenarios
  </Step>

  <Step title="Deploy and monitor">
    Assign phone numbers, launch campaigns, and monitor performance
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Which agent type should I choose?">
    Choose Single Prompt Agent for simple, linear conversations (lead qualification, basic support). Choose Flow Agent for complex workflows requiring conditional logic, DTMF support, or multi-step processes (IVR systems, advanced routing).
  </Accordion>

  <Accordion title="Can agents handle multiple Arabic dialects?">
    Yes, both agent types automatically understand and respond in multiple Arabic dialects. The system detects the caller's dialect and responds appropriately.
  </Accordion>

  <Accordion title="How do I integrate with my existing systems?">
    Use custom tools to integrate with any REST API, webhooks for event notifications, and the Voice Agents API to programmatically manage agents. See our [integration guides](/developers/guides/api-integration) for details.
  </Accordion>

  <Accordion title="Can agents transfer calls to humans?">
    Flow Agents support call transfers to human agents or other AI agents. Use the Transfer Call node to forward calls to external numbers, or the Transfer to Agent node for agent-to-agent handoffs with conditional routing. Single Prompt Agents do not support call transfers.
  </Accordion>

  <Accordion title="How do I monitor agent performance?">
    Use the Dashboard to monitor live calls, view call history, analyze performance metrics, and track customer satisfaction. All conversations are recorded and transcribed for review.
  </Accordion>

  <Accordion title="What LLM models are supported?">
    Hamsa supports leading LLM providers including OpenAI (GPT-4.1, GPT-5), Gemini (2.5-Pro, 2.5-Flash), Groq, and DeepMyst. Choose the model that best fits your use case and budget. See [LLM configuration](/overview/features/llm-configuration) for details.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Build Your First Agent" icon="rocket" href="/overview/quickstart">
    Quick start guide for building your first voice agent
  </Card>

  <Card title="Single Prompt Agent" icon="file-lines" href="/agents/single-prompt/overview">
    Learn about Single Prompt Agents
  </Card>

  <Card title="Flow Agent" icon="diagram-nodes" href="/agents/flow-agent/overview">
    Explore Flow Agent capabilities
  </Card>

  <Card title="Voice Agents Web SDK" icon="code" href="/developers/sdks/voice-agents-web-sdk">
    SDK for embedding voice agents in web apps
  </Card>
</CardGroup>