> 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. 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 Events, die zu dem Benutzer gehören, mit dessen Zugangsdaten der API-Request authentifiziert wurde. Diese Einschränkung gilt für alle über die History verfügbaren Eventtypen. Eine accountweite Event-Sicht wie unter Classic steht nicht mehr zur Verfügung. 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. Für Channel-Inbox-Events gilt zusätzlich: `GET /channels/{channelId}/events` liefert nur dann Events, wenn der authentifizierte API-Benutzer Mitglied des abgefragten Channels ist. Eine Admin-Rolle allein gewährt keinen Zugriff. 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 | ## 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`. ## 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. ## 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 des API-Benutzers abrufen soll, * Anrufe über `/sessions/calls` startet, * klassische Voicemail-Endpunkte 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` 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=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.