# Voice over IP

> Symcon documentation · English · generated on 2026-09-26  
> Index: https://www.symcon.de/en/llms.txt

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/

The VoIP module can set up/receive telephone connections, process DTMF signals, buffer connection-related data and play sounds.

> **Note:** The following devices are supported by IP-Symcon:
>
> __[Supported devices](voip.md) __

### Requirements

An active portal for telephony is required. This can be a Fritzbox or a service like Sipgate.

### Integration in IP-Symcon

For integration, a "VoIP" device can be added via Add object in the object tree.
Domain and user name for the telephone service must be specified in the instance configuration.
If required, AuthID and password must also be entered.

> **Note:** If the computer has several network cards or -interfaces (e.g. also virtual adapters such as VPN, Docker, Hyper-V) it may be necessary to define the IP address via which the VoIP connection is established. There is also the appropriate [special switch](../developer/special-switches.md) "VoIPInterface"

![Configuration](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/fcfd667dde-1790424938/voip-configuration.png)

To manage what should happen when a connection is active, a processing script must be added.

### Processing script

The processing script determines the behavior for each incoming connection. The [Systemvariables](../concepts/automations.md) are also important for this.

### Examples

#### Script for incoming calls (processing script)

```php
if($_IPS['SENDER'] == "VoIP") {
    // Only incoming calls are to be processed
    // $_IPS["INSTANCE"] is available since IP-Symcon 5.4
    if(VoIP_GetConnection($_IPS["INSTANCE"], $_IPS["CONNECTION"])["Direction"] == 1 /* Outbound */) {
        return;
    }
    switch($_IPS["EVENT"]) {
        case "Incoming":
            IPS_LogMessage("VoIP", "An incoming call");
            break;
        case "Connect":
            IPS_LogMessage("VoIP", "A connection was established");
            break;

        case "Disconnect":
            IPS_LogMessage("VoIP", "A connection was terminated");
            break;
        case "DTMF":
            IPS_LogMessage("VoIP", "A DTMF signal was received");

            switch($_IPS["DATA"]) {
                case '1':
                case '2':
                case '3':
                case '4':
                case '5':
                case '6':
                    IPS_LogMessage("VoIP", "One of the keys 1 to 6 was pressed");
                    break;
                case '#':
                    IPS_LogMessage("VoIP", "The # key was pressed");
                    break;
               default:
                    IPS_LogMessage("VoIP", "The ". $_IPS["DATA"] ." button was pressed");
                    break;
            }
            break;
        case "PlayFinish":
            IPS_LogMessage("VoIP", "A sound file was played");
            break;
       default:
            IPS_LogMessage("VoIP", "An unknown event was triggered");
            break;
    }
}
```

#### Outbound Call Script with TTS Module "AWS Polly" from the Module Store

```php
if($_IPS['SENDER'] == "Execute") {
    $id = VoIP_Connect(12345, "0451305005xx");
    //Wait a maximum of 10 seconds for someone to pick up
    for($i = 0; $i < 10; $i++) {
        IPS_Sleep(1000);
        $c = VoIP_GetConnection(12345, $id);
        if($c['Connected']) {
            // VoIP_Playwave() only supports WAV in the format: 16 Bit, 8000 Hz, Mono.
            VoIP_PlayWave(12345, $id, TTSAWSPOLLY_GenerateFile(23456, "IP-Symcon wishes you a wonderful day"));
            return;
        }
    }
    //Hang up if nobody picks up
    VoIP_Disconnect(12345, $id);
}
```

### Example setup on the FritzBox
The VoIP module can be used with the help of the FritzBox. A separate unused telephone number in the FritzBox is recommended for this and the following steps must be kept in mind.

> **Note:** If necessary, a new number must be set up under "Telephony" -> "Own number" -> "New number"

As a first step, a new telephony device must be added to the FritzBox under "Telephony" -> "Telephony Devices".
This must be added as a new "phone".

![Add telephony device](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/f84e5bdf4b-1790424938/voip-fritzbox-telefoniegeraethinzufuegen.png)

Since IP-Symcon acts as an IP telephone, this and then a separate telephone number must be selected. A descriptive name should be chosen for the telephony device.

![Select phone type](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/eba2722b45-1790424938/voip-fritzbox-telefoniegeraettyp.png)

Then a user name and password must be specified, these are later entered into the VoIP in IP-Symcon.

![Login data for the VoIP module](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/7b4fead334-1790424938/voip-fritzbox-login.png)

The telephony device to be set up must be confirmed and its setup then completed.

![Confirmation](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/03368b158c-1790424938/voip-fritzbox-bestaetigen.png)

![Conclude with OK](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/7deea175c7-1790424938/voip-fritzbox-abschliessen.png)

Now the telephony device can be taken over in IP-Symcon within the VoIP module.
If everything went well, the status "Registration was successful" is displayed.

![Configure VoIP module](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/2ff9974340-1790424938/voip-fritzbox-modulkonfiguration.png)

A test call can be made with the Processing-Script set up. In the [Messages](../components/management-console.md)  the following messages should appear when the number keys on the phone are pressed.

![Example of messages](https://www.symcon.de/media/pages/service/dokumentation/modulreferenz/geraete/voip/3101b88f68-1790424938/voip-fritzbox-meldungen.png)

## Device list

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/device-list/

### Supported Components
An excerpt of supported components.

* Fritzbox
* Sipgate

> **Note:** These are only the tested devices. Other devices may also work.

## VoIP_AcceptCall

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-acceptcall/

`bool VoIP_AcceptCall(int $InstanceID, int $ConnectionID)`

_Requires Symcon >= 5.4_

accepts a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

ID of the connection to be switched

**Example**

```php
// Accepts the connection with ID 3 of the instance with ID 12345
VoIP_AcceptCall(12345, 3)
```

## VoIP_Connect

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-connect/

`int VoIP_Connect(int $InstanceID, string $Number)`

_Requires Symcon >= 5.2_

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$Number` (string): Phone number to connect to

**Returns** (int): Returns the ID of the connection

Phone number to connect to

**Example**

```php
// Establishes a connection with the phone number 0451305005xx
VoIP_Connect(12345, "0451305005xx");
```

## VoIP_Disconnect

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-disconnect/

`bool VoIP_Disconnect(int $InstanceID, int $ConnectionID)`

_Requires Symcon >= 5.2_

terminates a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

ID of the connection to be switched

**Example**

```php
// Disconnects with ID 3 of the instance with ID 12345
VoIP_Disconnect(12345, 3);
```

## VoIP_GetConnection

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-getconnection/

`array VoIP_GetConnection(int $InstanceID, int $ConnectionID)`

_Requires Symcon >= 5.2_

returns information about a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched

**Returns** (array): Array with the following information

| Field        | Data type | Description                                                         |
| ------------ | --------- | ------------------------------------------------------------------- |
| ID           | integer   | ConnectionID                                                        |
| TimeStamp    | integer   | Time stamp of the call                                              |
| Number       | string    | Number with which a connection was established                      |
| Direction    | integer   | Call direction: 0 = Incoming call, 1 = Outgoing call                |
| Connected    | boolean   | Connection status: FALSE = not connected, TRUE = connected          |
| Disconnected | boolean   | Disconnection status: FALSE = not disconnected, TRUE = disconnected |

ID of the connection to be switched

**Example**

```php
// Returns information of the connection with ID 3.
print_r(VoIP_GetConnection(12345, 3));

// Sample output:
/*
Array
(
    [ID] => 3
    [TimeStamp] => 1566915689
    [Number] => 045130500511
    [Data] =>
    [Direction] => 1
    [Connected] => 1
    [Disconnected] =>
)
*/
```

## VoIP_GetData

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-getdata/

`string VoIP_GetData(int $InstanceID, int $ConnectionID)`

_Requires Symcon >= 5.2_

returns data of a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched

**Returns** (string): Content of the connection data as a string

ID of the connection to be switched

**Example**

```php
// Returns the content of the data of the connection with ID 3.
VoIP_SetData(12345, 3, "Hello World");
print_r(VoIP_GetData(12345, 3));

// Sample output
/*
Hello World
*/
```

## VoIP_PlayWave

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-playwave/

`bool VoIP_PlayWave(int $InstanceID, int $ConnectionID, string $Filename)`

_Requires Symcon >= 5.2_

plays a wave file

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched
- `$Filename` (string): Path and name of the file to be played

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

Path and name of the file to be played

**Example**

```php
// Plays the sound file "welcome.wav" on the connection with ID 3
VoIP_PlayWave(12345, 3, IPS_GetKernelDir() . "/media/welcome.wav");
```

## VoIP_RejectCall

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-rejectcall/

`bool VoIP_RejectCall(int $InstanceID, int $ConnectionID)`

_Requires Symcon >= 5.4_

rejects a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

ID of the connection to be switched

**Example**

```php
// Rejects the connection with the ID 3 of the instance with the ID 12345
VoIP_RejectCall(12345, 3)
```

## VoIP_SendDTMF

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-senddtmf/

`bool VoIP_SendDTMF(int $InstanceID, int $ConnectionID, string $DTMF)`

_Requires Symcon >= 5.3_

sends a sequence of characters as DTMF

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched
- `$DTMF` (string): Characters to be sent as DTMF

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

Characters to be sent as DTMF

**Example**

```php
// Sends the DTMF signals for "*123#" on the connection with ID 3
VoIP_SendDTMF(12345, 3, "*123#");
```

## VoIP_SetData

Source: https://www.symcon.de/en/service/documentation/module-reference/devices/voip/voip-setdata/

`bool VoIP_SetData(int $InstanceID, int $ConnectionID, string $Data)`

_Requires Symcon >= 5.2_

sets the data of a connection

**Parameters**

- `$InstanceID` (int): ID of the device to be switched
- `$ConnectionID` (int): ID of the connection to be switched
- `$Data` (string): Data for which connection is to be set

**Returns** (bool): If the command succeeds, it returns __TRUE__, otherwise __FALSE__.

Data for which connection is to be set

**Example**

```php
// Sets the content of the data of the connection with ID 3 to "Hello World"
VoIP_SetData(12345, 3, "Hello World");
```