> For the complete documentation index, see [llms.txt](https://help.sipgate.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.de/cloud-telefonanlage/anbindungen-und-integrationen/api/was-aendert-sich-mit-dem-neuen-system-in-der-sipgate-rest-api-und-bei-sipgateio.md).

# Was ändert sich mit dem neuen System in der sipgate REST API und bei sipgate.io?

Alle Änderungen der sipgate REST API und sipgate.io nach der Umstellung auf das neue sipgate Neo System im Überblick.

Seit September 2025 werden neue sipgate Accounts mit sipgate Neo angelegt. Bereits bestehende Classic-Accounts werden schrittweise migriert.

Mit sipgate Neo ändert sich das Modell für Telefonie: **Channels ersetzen Gruppen und persönliche Telefonanschlüsse (Phonelines)**. Das betrifft insbesondere Integrationen, die Anrufereignisse abrufen, Anrufe starten, Voicemails verarbeiten oder sipgate.io konfigurieren.

SMS- und Faxfunktionen bleiben grundsätzlich über die REST API verfügbar.

Alle in diesem Artikel genannten REST-API-Endpunkte beziehen sich auf die Basis-URL `https://api.sipgate.com/v2`. Eine vollständige Übersicht der Endpunkte finden Sie in der [Swagger-Dokumentation](https://api.sipgate.com/v2/doc).

## Account-Typ ermitteln

Der Account-Typ ist in der Weboberfläche sichtbar. Öffnen Sie dazu oben rechts das Profilmenü, indem Sie auf Ihren Benutzer-Avatar klicken.

Bei OAuth2 kann der Account-Typ außerdem anhand des Claims `featureScope` im JWT des Bearer-Tokens ermittelt werden:

| `featureScope` | Account-Typ |
| -------------- | ----------- |
| `CLASSIC`      | Classic PBX |
| `NEO_PBX`      | Neo PBX     |

Personal Access Tokens sind keine JWTs und enthalten diesen Claim nicht.

## Welche Endpunkte müssen angepasst werden?

| Bisherige Verwendung           | Classic PBX            | Neo PBX                          |
| ------------------------------ | ---------------------- | -------------------------------- |
| Gruppen abrufen und bearbeiten | `/groups`              | `/channels`                      |
| Persönliche Telefonanschlüsse  | `/{userId}/phonelines` | `/channels`                      |
| Anrufe aus der History abrufen | `/history`             | `/channels/{channelId}/events`   |
| Voicemails abrufen             | `/voicemails`          | Aufzeichnungen in Channel-Events |
| Anruf starten                  | `/sessions/calls`      | `/calls`                         |
| Gruppenfaxe                    | `/groupfaxlines`       | `/{userId}/faxlines`             |

Die Endpunkte für Gruppen, Phonelines, Gruppenfaxe und klassische Voicemails sind in Neo-Accounts nicht verfügbar.

## History und Channel-Events

Bei Neo werden Anrufe nicht mehr über die klassischen History-Endpunkte bereitgestellt. Verwenden Sie stattdessen:

```http
GET /channels/{channelId}/events
```

Der Endpunkt liefert die Anrufereignisse eines Channels. Voicemails sowie manuelle und automatische Anrufaufzeichnungen werden über das Feld `recordings` des jeweiligen Events angeboten.

Für die Seitennavigation stehen die Parameter `limit` und `position` zur Verfügung. Der `position`-Wert aus einer Antwort kann in der nächsten Anfrage als Cursor verwendet werden.

Bei Accounts, die von Classic zu Neo migriert wurden, können Anrufereignisse vorübergehend weiterhin in der klassischen History erscheinen. Neue Integrationen sollten sich nicht auf dieses Übergangsverhalten verlassen.

SMS- und Faxereignisse bleiben auch bei Neo über die History-Endpunkte verfügbar. Anders als bei Classic liefern die History-Endpunkte unter Neo jedoch nur Ereignisse des Benutzers, mit dessen Zugangsdaten der API-Request authentifiziert wurde. Diese Einschränkung gilt für alle über die History verfügbaren Ereignistypen. Eine accountweite Ereignisabfrage wie unter Classic ist nur Administratoren über den Query-Parameter `includeAllUsers` möglich; siehe dazu den folgenden Abschnitt.

Für Channel-Inbox-Events gilt zusätzlich: `GET /channels/{channelId}/events` liefert standardmäßig nur dann Events, wenn der authentifizierte API-Benutzer Mitglied des abgefragten Channels ist. Persönliche Channels sind ausschließlich für den zugehörigen Benutzer zugänglich; alle anderen Channels können zusätzlich von Administratoren abgerufen werden. Administratoren können die Beschränkung auf die eigene Mitgliedschaft mit dem Query-Parameter `includeAllUsers` aufheben; siehe dazu den folgenden Abschnitt.

### Ereignisse aller Benutzer abrufen (nur Administratoren)

Standardmäßig liefern die History-Endpunkte nur die Ereignisse des Benutzers, mit dessen Zugangsdaten der API-Request authentifiziert wurde – unabhängig von dessen Rolle. Administratoren können diese Einschränkung aufheben, indem sie beim Abruf der History den Query-Parameter `includeAllUsers` mit dem Wert `true` setzen. Der Parameter steht für `GET /history`, `GET /history/export` und `GET /channels/{channelId}/events` zur Verfügung.

Dabei gelten folgende Voraussetzungen:

* Der authentifizierte API-Benutzer muss die Administrator-Rolle besitzen.
* Die aktuelle Leistungsbeschreibung muss für den Account akzeptiert sein. Die Leistungsbeschreibung kann auch über die REST API abgerufen und von einem Administrator akzeptiert werden: `GET /tacs/product/sipgatebusiness` liefert den Text, `POST /tacs/product/sipgatebusiness` mit dem Feld `tacAccepted` nimmt die Zustimmung vor (Basis-URL `https://api.sipgate.com/v3`).

Ist der Parameter gesetzt, liefert die Abfrage die Ereignisse aller Benutzer des Accounts – bei migrierten Accounts also auch die Anrufereignisse anderer Benutzer, die während der Übergangszeit über die History verfügbar sind. Die übrigen Filter wie Zeitraum, Typ oder Rufnummer stehen unverändert zur Verfügung. Ohne den Parameter gilt für alle Benutzer – auch für Administratoren – das bisherige Verhalten.

Beim Abruf der Channel-Events (`GET /channels/{channelId}/events`) erweitert der Parameter den Zugriff für Administratoren: Auch ohne den Parameter können Administratoren auf alle nicht-persönlichen Channels zugreifen, unabhängig von einer eigenen Mitgliedschaft. Der Parameter hebt die letzte verbleibende Beschränkung auf: Mit `includeAllUsers=true` können Administratoren zusätzlich die Events persönlicher Channels abrufen, die sonst nur für den zugehörigen Benutzer zugänglich sind:

```http
GET /channels/{channelId}/events?includeAllUsers=true
```

Der erweiterte Zugriff wird bewusst pro Anfrage gesetzt und ist damit im Request erkennbar und nachvollziehbar. Die Verantwortung für den Umgang mit den abgerufenen Daten liegt beim Kunden. Fehlt die Administrator-Rolle oder ist die Leistungsbeschreibung nicht akzeptiert, antwortet die API mit dem Status `403` und weist im Fehlerhinweis auf die erforderliche Zustimmung zur Leistungsbeschreibung hin. Dies gilt für die History-Endpunkte wie für die Channel-Events.

Prüfen Sie insbesondere Integrationen, die Events accountweit auswerten, archivieren oder mit Drittsystemen synchronisieren.

## Channels

Channels ersetzen in Neo die bisherigen Gruppen und Phonelines. Über die REST API stehen unter anderem folgende Funktionen zur Verfügung:

| Endpunkt                                           | Funktion                                   |
| -------------------------------------------------- | ------------------------------------------ |
| `GET /channels`                                    | Channels des Accounts abrufen              |
| `GET /channels/{channelId}/events`                 | Anrufereignisse und Aufzeichnungen abrufen |
| `PUT /channels/{channelId}/name`                   | Channel umbenennen                         |
| `PUT /channels/{channelId}/users`                  | Mitglieder setzen                          |
| `PUT /channels/{channelId}/users/{userId}/devices` | Geräte eines Mitglieds setzen              |
| `DELETE /channels/{channelId}`                     | Channel löschen                            |

Weitere Einstellungen wie Klingelreihenfolge, Warteschlange, Begrüßung sowie Klingel- und Nachbearbeitungszeit werden von `GET /channels` ausgegeben, sind derzeit über die REST API jedoch nur lesbar.

## Anrufe starten und steuern

Für Click-to-Dial verwenden Classic und Neo unterschiedliche Endpunkte:

* Classic: `POST /sessions/calls`
* Neo: `POST /calls`

Bei Neo kann ein `channelId` angegeben werden. Wird er weggelassen, verwendet die API den Default-Channel des Geräts. Mit `additionalDevices` können weitere Geräte parallel klingeln.

Für aktive Neo-Anrufe werden folgende Funktionen unterstützt:

| Funktion                 | Endpunkt                             | Neo               |
| ------------------------ | ------------------------------------ | ----------------- |
| Anrufe auflisten         | `GET /calls`                         | Unterstützt       |
| Halten/Fortsetzen        | `PUT /calls/{callId}/hold`           | Unterstützt       |
| DTMF senden              | `POST /calls/{callId}/dtmf`          | Unterstützt       |
| Aufnahme starten/stoppen | `PUT /calls/{callId}/recording`      | Unterstützt       |
| Transfer                 | `POST /calls/{callId}/transfer`      | Unterstützt       |
| Anruf beenden            | `DELETE /calls/{callId}`             | Unterstützt       |
| Stummschalten            | `PUT /calls/{callId}/muted`          | Nicht unterstützt |
| Audiodatei abspielen     | `POST /calls/{callId}/announcements` | Nicht unterstützt |

## Devices

Der Endpunkt

```http
GET /{userId}/devices
```

unterstützt den optionalen Query-Parameter `type`. Er akzeptiert eine kommaseparierte Liste mit folgenden Werten:

```
all, app, register, mobile, external
```

Die Antwort enthält auch App-Extensions.

## Fax

Gruppenfaxanschlüsse werden in Neo nicht mehr verwendet. Bei einer Migration werden bestehende Gruppenfaxanschlüsse in globale Faxanschlüsse überführt.

Verwenden Sie bei Neo:

```http
GET /{userId}/faxlines
```

Die Endpunkte unter `/groupfaxlines` und die Faxfunktionen unter `/groups` sind nur mit Classic PBX verfügbar. Faxereignisse bleiben bei Neo über die History-Endpunkte abrufbar.

## sipgate.io Push API

Die Push API ist mit Classic und Neo kompatibel.

* In Classic können Webhooks für Extensions konfiguriert werden.
* In Neo erfolgt die Konfiguration für Channels.
* Webhook-URLs müssen HTTPS verwenden.
* Selbst signierte Zertifikate werden nicht akzeptiert.

Die globale Konfiguration kann über folgende Endpunkte gelesen und geändert werden:

```http
GET /settings/sipgateio
PUT /settings/sipgateio
```

Im Feld `whitelist` werden bei Classic Extension-IDs und bei Neo Channel-IDs übergeben.

### Push-API-Versionen

| Version | Status | Verhalten                                   |
| ------- | ------ | ------------------------------------------- |
| 1       | Stable | Ursprünglicher Push-API-Vertrag             |
| 2       | Beta   | Ergänzt `channelId` in den Webhook-Requests |

Version 1 bleibt unverändert. Version 2 befindet sich in der Beta-Phase und ergänzt `channelId`. Sie wird nicht allgemein empfohlen und sollte nur verwendet werden, wenn diese Information benötigt wird. Ab Version 2 können neue optionale Request-Parameter ergänzt werden. Integrationen sollten deshalb unbekannte Parameter ignorieren.

Die Version kann beim Schreiben der sipgate.io-Einstellungen über `pushApiVersion` gewählt werden. Jeder Webhook enthält außerdem die Header `X-Sipgate-Version` und `X-Sipgate-Lifecycle`.

### Callflows: Unterschiede zwischen Classic und Neo

Bei der Push API antwortet Ihr Server auf Webhook-Events mit XML-Responses (Callflows). Unter Neo gelten für einige Actions abweichende Regeln. Eine Integration muss angepasst werden, wenn sie insbesondere:

* Ansagen mit `<Say>` erzeugt,
* Aufzeichnungen mit `<Record>` startet,
* `<Device>`-Ziele in `<Dial>`-Responses verwendet,
* `maxDigits` oder `timeout` mit `0`, negativen oder ungültigen Werten angibt,
* Webhook- oder Audiodatei-URLs per HTTP-Redirect ausliefert.

#### Nicht unterstützte Classic-Actions

| Classic                      | Verhalten unter Neo                             | Ersatz                             |
| ---------------------------- | ----------------------------------------------- | ---------------------------------- |
| `<Say>`                      | Nicht unterstützt                               | Audiodatei mit `<Play>` abspielen  |
| `<Record>`                   | Nicht unterstützt                               | Aufzeichnung über REST API steuern |
| `<Device>` als `<Dial>`-Ziel | Response ist ungültig und wird nicht ausgeführt | Ziel als `<Number>` angeben        |

#### Sprachausgaben mit `<Play>` bereitstellen

Erzeugen Sie gesprochene Inhalte als Audiodatei und spielen Sie sie mit `<Play>` ab. Die Datei muss als Mono-WAV mit 16-Bit-PCM und 8 kHz unter einer öffentlich erreichbaren HTTPS-URL bereitgestellt werden:

```xml
<Response>
  <Play>
    <Url>https://example.com/audio/announcement.wav</Url>
  </Play>
</Response>
```

#### Aufzeichnungen über die REST API steuern

Die Action `<Record>` wird unter Neo durch die Aufzeichnungsfunktion der REST API ersetzt. Starten und stoppen Sie Aufzeichnungen aktiver Anrufe über `PUT /calls/{callId}/recording` (siehe Abschnitt Anrufe starten und steuern). Fertige Aufzeichnungen rufen Sie über die Channel-Events ab (`GET /channels/{channelId}/events`, siehe Abschnitt History und Channel-Events).

Channel-Events stehen nur unter Neo zur Verfügung. Verarbeitet Ihre Integration in der Übergangszeit sowohl Classic- als auch Neo-Accounts, benötigen Sie beide Wege: Unter Classic weiterhin `<Record>` samt zugehöriger Events, unter Neo die REST API und die Channel-Events.

#### Weiterleitungen mit `<Dial>`

Adressieren Sie Weiterleitungsziele unter Neo über die Rufnummer:

```xml
<Response>
  <Dial>
    <Number>4915799912345</Number>
  </Dial>
</Response>
```

Beachten Sie die Attribute von `<Dial>`:

* `callerId` im E.164-Format ohne führendes `+`, zum Beispiel `4921112345678`.
* `anonymous` ausschließlich mit `true` oder `false`. Bei `anonymous="true"` wird eine gleichzeitig gesetzte `callerId` unterdrückt.
* Enthält die Action `<Voicemail />`, wird ausschließlich zur Voicemail weitergeleitet. Weitere Rufnummernziele werden nicht angerufen, `callerId` und `anonymous` werden nicht ausgewertet. Verwenden Sie `<Voicemail />` deshalb als alleiniges Ziel.

#### DTMF-Abfragen mit `<Gather>`

Verwenden Sie für `maxDigits` und `timeout` ausschließlich positive Ganzzahlen. Werte wie `0`, negative Werte oder ungültige Zahlen machen die Response ungültig. Lassen Sie ein Attribut weg, gilt der Standardwert: eine Ziffer für `maxDigits`, 2000 Millisekunden für `timeout`.

```xml
<Gather
  onData="https://example.com/dtmf"
  maxDigits="3"
  timeout="5000">
</Gather>
```

Timeouts werden auf volle Sekunden aufgerundet: 1 bis 1000 Millisekunden ergeben eine Sekunde, 1001 bis 2000 Millisekunden zwei Sekunden. Verwenden Sie nach Möglichkeit Vielfache von 1000 Millisekunden.

#### Calls beenden: `<Reject>` und `<Hangup>`

`<Reject>` ist ausschließlich in der direkten Antwort auf ein `newCall`-Event gültig. Um einen Call in einem späteren Schritt zu beenden, zum Beispiel in einer Antwort auf ein DTMF-`onData`-Event, verwenden Sie `<Hangup />`:

```xml
<Response>
  <Hangup />
</Response>
```

#### Direkte URLs verwenden

Die Push API folgt unter Neo keinen HTTP-Weiterleitungen. Antworten mit Status `301`, `302`, `303` oder `307` werden nicht verfolgt. Verwenden Sie für Webhooks und Audiodateien URLs, die das gewünschte Ergebnis direkt ausliefern.

#### Verhalten bei nicht abspielbaren Audiodateien

Kann eine Audiodatei aufgrund eines HTTP-, Netzwerk- oder TLS-Fehlers nicht abgerufen werden, fährt Neo mit der nächsten Action fort. Kann ein innerhalb von `<Gather>` verwendetes `<Play>` nicht abgespielt werden, läuft das Gather ohne die Ansage weiter, sammelt weiterhin DTMF-Eingaben und kann anschließend den `onData`-Webhook aufrufen.

#### Gespeicherte Callback-URLs

Einmal gesetzte `onAnswer`- und `onHangup`-URLs müssen nicht in jeder weiteren Response wiederholt werden. Lassen Sie das jeweilige Attribut weg, bleibt die gespeicherte URL für den weiteren Callflow aktiv.

Gespeicherte URLs können ersetzt werden: eine `onAnswer`- oder `onHangup`-URL in einer erfolgreichen `onData`-Response durch erneutes Setzen des Attributs, eine `onHangup`-URL zusätzlich in einer gültigen `onAnswer`-Response.

## Vor einer Migration prüfen

Eine Integration muss angepasst werden, wenn sie insbesondere:

* Gruppen oder Phonelines abruft,
* Events mehrerer oder aller Account-Benutzer zentral abruft,
* Anrufe oder Voicemails über die History verarbeitet,
* Channel-Inbox-Events ohne Mitgliedschaft im jeweiligen Channel abrufen soll (Administratoren: `includeAllUsers`),
* Anrufe über `/sessions/calls` startet,
* klassische Voicemail-Endpunkte verwendet,
* Push-API-Callflows mit `<Say>`, `<Record>`, `<Device>`-Zielen, ungültigen Gather-Werten oder HTTP-Weiterleitungen verwendet,
* Gruppenfaxe verarbeitet oder
* sipgate.io anhand von Extension-IDs konfiguriert.

Nach der Anpassung sollte die Integration den Account-Typ berücksichtigen und je nach `featureScope` die passenden Classic- oder Neo-Endpunkte verwenden.


---

# 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 by asking a question.

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

```
GET https://help.sipgate.de/cloud-telefonanlage/anbindungen-und-integrationen/api/was-aendert-sich-mit-dem-neuen-system-in-der-sipgate-rest-api-und-bei-sipgateio.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 `automate deployments from our CI pipeline` 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.
