> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/features/voice-ai/freshcaller-setup.md).

# Freshcaller Setup

Connect Freshcaller to Alhena Voice AI to route incoming calls to your AI agent.

{% hint style="info" %}
Freshcaller integration requires assistance from the Alhena team. [Contact support](/docs/troubleshooting/troubleshooting.md#contact-support) to get started — we will provide you with the custom Freshcaller app and your Alhena API key.
{% endhint %}

### How It Works

When a customer calls your Freshcaller number, Freshcaller routes the call to Alhena, where your Voice AI agent handles the conversation. If the caller needs to speak with a person, Alhena transfers the call back to Freshcaller with the AI conversation transcript so your team has full context.

***

### Prerequisites

* Active Freshcaller account
* Your Freshcaller API key
* Contact the Alhena team to receive:
  * The custom Freshcaller app package
  * Your Alhena API key

***

### Step 1: Install the Custom Freshcaller App

#### Upload the app

1. In Freshcaller, go to **Admin → Apps**.
2. Scroll to the bottom and click **Build it yourself**.
3. Click **New App → Custom App**.
4. Upload the `.zip` file provided by Alhena. Enter **Alhena Freshcaller** as the app name and description.
5. Click **Save and Publish**.

#### Install the app

1. Go to **Admin → Apps → Manage Apps**.
2. Under **Custom Apps**, click **Install** next to **Alhena Freshcaller**.
3. During installation, enter:
   * **Freshcaller API Key** — your Freshcaller account API key
   * **Alhena API Key** — provided by the Alhena team
   * **Alhena Domain** — `app.alhena.ai` or `eu.alhena.ai`, depending on your account region

***

### Step 2: Configure Your Phone Number's Call Action

Once the app is installed, a **Call Action** is automatically created in Freshcaller for routing calls to Alhena. You need to assign it to your phone number:

1. In Freshcaller, go to **Admin → Phone Numbers** and select the number you want Alhena to answer.
2. Under the number's settings, set the **Call Action** to the Alhena call action.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-77d81848325381e30ced33ecfa991fd7868031e3%2Fvoice-ai-freshcaller-call-action.png?alt=media" alt=""><figcaption><p>Assign the Alhena call action to your phone number</p></figcaption></figure>

***

### Step 3: Set a Transfer Queue

When Alhena transfers a call to a human agent, it needs to know which Freshcaller queue to route the caller to.

1. In the Alhena call action settings, configure the **Transfer Queue** — the Freshcaller queue that should receive calls when a human handoff is triggered.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-a08526d34d57d68591f567e7bda2e6e217c15738%2Fvoice-ai-freshcaller-handoff-queue.png?alt=media" alt=""><figcaption><p>Configure the transfer queue for human handoff</p></figcaption></figure>

***

### Step 4: Enable Freshcaller in Alhena Voice AI Settings

1. Go to **Integrations → Voice AI Settings**.
2. The **Freshcaller** toggle will appear after the Freshcaller app is installed in your account.
3. Toggle **Freshcaller** on.

<figure><img src="https://2864633804-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKZ3bWFAIdLAqpW2uafZ4%2Fuploads%2Fgit-blob-4be3f24dc0a11d1f4e1999d76f06e8baf260d001%2Fvoice-ai-freshcaller-enable-integration.png?alt=media" alt=""><figcaption><p>Enable Freshcaller in Voice AI settings</p></figcaption></figure>