> For the complete documentation index, see [llms.txt](https://docs.pascom.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pascom.net/en/setup/endpoints/hardware-phones-ringtone.md).

# Ringtones for Hardware Phones

Configure custom ringtones for your hardware phones based on caller or call routing.

With distinctive ringtones (**Distinctive Ringing**), you can define which ringtone melody or alert tone a hardware phone plays for incoming calls. This allows your employees to immediately recognize by the ringtone whether a call is from an important **VIP customer**, a specific **queue**, or an internal colleague.

## How It Works

PASCOM uses the SIP standard header `Alert-Info` to control ringtones.

1. In PASCOM, define a **Set Ringtone** action before call setup (e.g., in a call router, for a user, or in a team/queue).
2. Enter a unique identifier in this action (e.g., `VIP` or `CustomRingtone`).
3. During an incoming call, PASCOM transmits this value in the SIP header `Alert-Info` to the phone: `<http://www.notused.com>;info=CustomRingtone;x-line-id=0`.
4. The hardware phone matches the transmitted text against its internal ringtone table and plays the assigned ringtone.

{% hint style="info" %}
If no action is defined or the field remains empty, PASCOM automatically falls back to its default behavior (distinguishing between internal calls, external calls, and intercom).
{% endhint %}

## Step 1: Configure the Action in PASCOM

The **Set Ringtone** action is available wherever call actions are supported:

* **Call Routers**
* **Users**
* **Queues / Teams**

{% hint style="warning" %}
Ringtone actions can **only be executed before the call**. Therefore, always insert the action in the **Before** tabs (e.g., *External/Before* or *Internal/Before*).
{% endhint %}

### Add Action

1. Open the desired object for editing (e.g., a user or a call router).
2. Click **Add** and select the action **Set Ringtone**.
3. Enter the desired identifier in the text field (e.g., `CustomRingtone` or `VIP`). Allowed characters are letters (`a-z`, `A-Z`), digits (`0-9`), periods (`.`), hyphens (`-`), and underscores (`_`).
4. Save the action by clicking **Save**.
5. Apply the changes by clicking the **green checkmark** in the top-right job bar.

{% hint style="success" %}
Pay close attention to exact spelling (case-sensitive). The text entered here must match the configuration on the hardware phone exactly.
{% endhint %}

## Step 2: Configure the Hardware Phone

To ensure the hardware phone plays the correct ringtone when receiving the `Alert-Info` header, a matching mapping rule must be configured on the phone.

You can configure this setting either centrally via the PASCOM **Base Configuration** of the endpoint or directly via the phone's web interface.

### Device Settings Overview

The following table displays the configuration and provisioning parameters for major phone manufacturers:

| Device                     | Used Header (PASCOM)                                                                                                                                                                    | Provisioning / Configuration                                                                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Yealink Desktop Phones** | <p><code><[http://www.notused.com>\\](https://docs.pascom.net/en/setup/endpoints/http:/www.notused.com>\\);</code><br><code>info=CustomRingtone;</code><br><code>x-line-id=0</code></p> | <p><code>distinctive\_ring\_tones.alert\_info.1.text = CustomRingtone</code><br><code>distinctive\_ring\_tones.alert\_info.1.ringer = Ring3.wav</code></p>                       |
| **Snom Desktop Phones**    | <p><code><[http://www.notused.com>\\](https://docs.pascom.net/en/setup/endpoints/http:/www.notused.com>\\);</code><br><code>info=CustomRingtone;</code><br><code>x-line-id=0</code></p> | <p><code>\<internal\_ringer\_text idx="0">CustomRingtone\</internal\_ringer\_text></code><br><code>\<internal\_ringer\_file idx="0">Ringer3\</internal\_ringer\_file></code></p> |
| **Grandstream**            | <p><code><[http://www.notused.com>\\](https://docs.pascom.net/en/setup/endpoints/http:/www.notused.com>\\);</code><br><code>info=CustomRingtone;</code><br><code>x-line-id=0</code></p> | <p><code>\<P1488>CustomRingtone\</P1488></code><br><code>\<P1489>3\</P1489></code></p>                                                                                           |
| **Fanvil Desktop Phones**  | <p><code><[http://www.notused.com>\\](https://docs.pascom.net/en/setup/endpoints/http:/www.notused.com>\\);</code><br><code>info=CustomRingtone;</code><br><code>x-line-id=0</code></p> | <p><code>\<alertInfo index="3"></code><br>  <code>\<Text>CustomRingtone\</Text></code><br>  <code>\<RingType>3.wav\</RingType></code><br><code>\</alertInfo></code></p>          |

***

## Detailed Setup by Manufacturer

### Yealink

On Yealink phones, this feature is controlled via **Distinctive Ring Tones**.

#### Configuration via Base Configuration

Add the following lines to the PASCOM Base Configuration of your Yealink phone (**Devices** > **Basic Configurations**):

```ini
# Enables distinctive ring tones for the account
distinctive_ring_tones.alert_info.1.text = CustomRingtone
distinctive_ring_tones.alert_info.1.ringer = Ring3.wav
```

#### Configuration via Phone Web Interface

1. Open the Yealink phone web interface and sign in.
2. Navigate to **Account** > **Advanced**.
3. Set **Distinctive Ring Tones** to **Enabled**.
4. Under **Alert Info**, enter the desired text (e.g., `CustomRingtone`) and select the corresponding internal ringtone (e.g., `Ring3.wav`).
5. Save the configuration by clicking **Confirm**.

***

### Snom

Snom phones support up to 10 distinct Alert-Info mappings using an index (`idx="0"` to `idx="9"`).

#### Configuration via Base Configuration

In the **Configuration** tab of the Snom Base Configuration, add the following XML elements:

```xml
<!-- Mapping index 0 -->
<internal_ringer_text idx="0" perm="">CustomRingtone</internal_ringer_text>
<internal_ringer_file idx="0" perm="">Ringer3</internal_ringer_file>
```

* **internal\_ringer\_text**: The keyword entered in the PASCOM action.
* **internal\_ringer\_file**: The desired phone ringtone (`Ringer1` to `Ringer10`).

***

### Grandstream

Grandstream endpoints evaluate the header via Matching Rules.

#### Configuration via Base Configuration

Enter the corresponding P-values into the Grandstream Base Configuration:

```xml
<!-- Matching Rule Text -->
<P1488>CustomRingtone</P1488>
<!-- Ringtone selection: 0=system default, 1=Custom Ring Tone 1, 2=Custom Ring Tone 2, 3=Custom Ring Tone 3 -->
<P1489>3</P1489>
```

#### Configuration via Phone Web Interface

1. Sign in to the Grandstream phone web interface.
2. Go to **Account** > **Call Settings**.
3. Locate the **Matching Rule** / **Distinctive Ring Tone** section.
4. Enter the matching text (e.g., `CustomRingtone`) in the rule and assign the desired ringtone.
5. Save your changes by clicking **Save and Apply**.

***

### Fanvil

Fanvil phones evaluate the `Alert-Info` text via media settings.

#### Configuration via Base Configuration

Add the following XML block to the Base Configuration:

```xml
<alertInfo index="3">
  <Text>CustomRingtone</Text>
  <RingType>3.wav</RingType>
</alertInfo>
```

#### Configuration via Phone Web Interface

1. Sign in to the Fanvil phone web interface.
2. Navigate to **Phone Settings** > **Media Settings** > **Alert Info Ring Settings**.
3. Enter the matching text under **Text** (e.g., `CustomRingtone`).
4. Select the desired sound file under **RingType** (e.g., `3.wav`).
5. Click **Apply**.

***

## Practical Example: Setting Up a VIP Ringtone

A common use case is providing an audible distinction for calls from important clients:

1. **Create condition**: Under **Call Routing** > **Action Conditions**, create a condition that checks whether the caller number belongs to a VIP customer. For more information on actions, see [here](/en/setup/acd/actions.md).
2. **Insert action into call routing**: In the call router or queue, add a Before action of type **Set Ringtone** and assign the newly created VIP condition to it.
3. **Enter text**: Set the value to `VIP`.
4. **Configure phone**: On the hardware phone (or in the Base Configuration), map the text `VIP` to a distinctive ringtone (e.g., `Ring5.wav`).
5. **Apply changes**: Save all settings and apply the telephony configuration.

As soon as a VIP customer calls, PASCOM detects the condition, sends the header `info=VIP` to the phone, and the phone rings with the selected VIP ringtone.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pascom.net/en/setup/endpoints/hardware-phones-ringtone.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.