> 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/en/connections-and-integrations/api/was-aendert-sich-mit-dem-neuen-system-in-der-sipgate-rest-api-und-bei-sipgateio.md). # What changes with the new system in the sipgate REST API and with sipgate.io? An overview of all changes to the sipgate REST API and sipgate.io after the switch to the new sipgate Neo system. Since September 2025, new sipgate accounts have been created with sipgate Neo. Existing Classic accounts are being migrated gradually. With sipgate Neo, the telephony model changes: **Channels replace groups and personal phone lines (Phonelines)**. This particularly affects integrations that retrieve call events, start calls, process voicemails, or configure sipgate.io. SMS and fax features generally remain available through the REST API. All REST API endpoints mentioned in this article use the base URL `https://api.sipgate.com/v2`. You can find a complete overview of the endpoints in the [Swagger documentation](https://api.sipgate.com/v2/doc). ## Determine the account type The account type is visible in the web interface. To view it, open the profile menu in the top-right corner by clicking your user avatar. With OAuth2, you can also determine the account type from the `featureScope` claim in the bearer token's JWT: | `featureScope` | Account type | | -------------- | ------------ | | `CLASSIC` | Classic PBX | | `NEO_PBX` | Neo PBX | Personal access tokens are not JWTs and do not contain this claim. ## Which endpoints need to be updated? | Previous usage | Classic PBX | Neo PBX | | --------------------------- | ---------------------- | ------------------------------ | | Retrieve and edit groups | `/groups` | `/channels` | | Personal phone lines | `/{userId}/phonelines` | `/channels` | | Retrieve calls from history | `/history` | `/channels/{channelId}/events` | | Retrieve voicemails | `/voicemails` | Recordings in channel events | | Start a call | `/sessions/calls` | `/calls` | | Group fax lines | `/groupfaxlines` | `/{userId}/faxlines` | The endpoints for groups, Phonelines, group fax lines, and classic voicemails are not available in Neo accounts. ## History and channel events With Neo, calls are no longer provided through the classic history endpoints. Instead, use: ```http GET /channels/{channelId}/events ``` The endpoint returns a channel's call events. Voicemails, as well as manual and automatic call recordings, are provided through the `recordings` field of the respective event. For pagination, use the parameters `limit` and `position` available. The `position` value from a response can be used as a cursor in the next request. For accounts migrated from Classic to Neo, call events may temporarily continue to appear in the classic history. New integrations should not rely on this transitional behavior. SMS and fax events remain available through the history endpoints in Neo as well. However, unlike Classic, the history endpoints in Neo return only events for the user whose credentials authenticated the API request. This restriction applies to all event types available through history. An account-wide event query like the one in Classic is available only to administrators through the query parameter `includeAllUsers` ; see the following section. Channel inbox events have an additional restriction: `GET /channels/{channelId}/events` returns events by default only if the authenticated API user is a member of the queried channel. Personal channels are accessible only to their associated user; administrators can also access all other channels. Administrators can remove the restriction requiring their own membership with the query parameter `includeAllUsers` ; see the following section. ### Retrieve events for all users (administrators only) By default, the history endpoints return only events for the user whose credentials authenticated the API request, regardless of their role. Administrators can remove this restriction by setting the query parameter `includeAllUsers` to the value `true` . The parameter is available for `GET /history`, `GET /history/export` and `GET /channels/{channelId}/events` . The following requirements apply: * The authenticated API user must have the administrator role. * The current terms of service must be accepted for the account. The terms of service can also be retrieved through the REST API and accepted by an administrator: `GET /tacs/product/sipgatebusiness` returns the text, `POST /tacs/product/sipgatebusiness` with the field `tacAccepted` submits acceptance (base URL `https://api.sipgate.com/v3`). When the parameter is set, the query returns events for all users in the account—including, for migrated accounts, call events from other users that are available through history during the transition period. Other filters, such as time range, type, or phone number, remain unchanged. Without the parameter, the existing behavior applies to all users, including administrators. When retrieving channel events (`GET /channels/{channelId}/events`), the parameter extends access for administrators: even without the parameter, administrators can access all non-personal channels, regardless of whether they are members. The parameter removes the last remaining restriction: with `includeAllUsers=true` administrators can also retrieve events from personal channels, which are otherwise accessible only to their associated user: ```http GET /channels/{channelId}/events?includeAllUsers=true ``` Expanded access is deliberately enabled per request, making it visible and traceable in the request. The customer is responsible for handling the retrieved data. If the administrator role is missing or the terms of service have not been accepted, the API responds with status `403` and indicates in the error message that acceptance of the terms of service is required. This applies to both the history endpoints and channel events. In particular, review integrations that analyze, archive, or synchronize events across the account with third-party systems. ## Channels In Neo, channels replace the previous groups and phonelines. The REST API provides, among other things, the following functions: | Endpoint | Function | | -------------------------------------------------- | ----------------------------------- | | `GET /channels` | Retrieve the account's channels | | `GET /channels/{channelId}/events` | Retrieve call events and recordings | | `PUT /channels/{channelId}/name` | Rename channel | | `PUT /channels/{channelId}/users` | Set members | | `PUT /channels/{channelId}/users/{userId}/devices` | Set a member's devices | | `DELETE /channels/{channelId}` | Delete channel | Additional settings such as ring order, queue, greeting, and ring and wrap-up times are returned by `GET /channels` but are currently read-only via the REST API. ## Start and control calls Classic and Neo use different endpoints for click-to-dial: * Classic: `POST /sessions/calls` * Neo: `POST /calls` For Neo, a `channelId` can be specified. If omitted, the API uses the device's default channel. With `additionalDevices` additional devices can ring in parallel. The following features are supported for active Neo calls: | Function | Endpoint | Neo | | -------------------- | ------------------------------------ | ------------- | | List calls | `GET /calls` | Supported | | Hold/resume | `PUT /calls/{callId}/hold` | Supported | | Send DTMF | `POST /calls/{callId}/dtmf` | Supported | | Start/stop recording | `PUT /calls/{callId}/recording` | Supported | | Transfer | `POST /calls/{callId}/transfer` | Supported | | End call | `DELETE /calls/{callId}` | Supported | | Mute | `PUT /calls/{callId}/muted` | Not supported | | Play audio file | `POST /calls/{callId}/announcements` | Not supported | ## Devices The endpoint ```http GET /{userId}/devices ``` supports the optional query parameter `type`. It accepts a comma-separated list of the following values: ``` all, app, register, mobile, external ``` The response also contains app extensions. ## Fax Group fax lines are no longer used in Neo. During a migration, existing group fax lines are converted to global fax lines. For Neo, use: ```http GET /{userId}/faxlines ``` The endpoints under `/groupfaxlines` and the fax features under `/groups` are only available with Classic PBX. Fax events remain accessible in Neo through the history endpoints. ## sipgate.io Push API The Push API is compatible with Classic and Neo. * In Classic, you can configure webhooks for extensions. * In Neo, configuration is for channels. * Webhook URLs must use HTTPS. * Self-signed certificates are not accepted. You can read and modify the global configuration using the following endpoints: ```http GET /settings/sipgateio PUT /settings/sipgateio ``` In the `whitelist` field, pass extension IDs for Classic and channel IDs for Neo. ### Push API versions | Version | Status | Behavior | | ------- | ------ | ------------------------------------ | | 1 | Stable | Original Push API contract | | 2 | Beta | Adds `channelId` to webhook requests | Version 1 remains unchanged. Version 2 is in beta and adds `channelId`. It is not generally recommended and should only be used when this information is needed. Starting with version 2, new optional request parameters may be added. Integrations should therefore ignore unknown parameters. You can select the version when writing sipgate.io settings using `pushApiVersion` . Each webhook also includes the headers `X-Sipgate-Version` and `X-Sipgate-Lifecycle`. ### Callflows: Differences between Classic and Neo With the Push API, your server responds to webhook events with XML responses (callflows). In Neo, different rules apply to some actions. An integration must be adapted if it, in particular: * generates announcements using `` , * starts recordings using `` , * `` destinations in ``-responses, * `maxDigits` or `timeout` with `0`, specifies negative or invalid values, * serves webhook or audio file URLs via HTTP redirect. #### Unsupported Classic Actions | Classic | Behavior in Neo | Replacement | | ---------------------------------- | -------------------------------------------- | --------------------------------------------- | | `` | Not supported | audio file with `` play | | `` | Not supported | control recording via the REST API | | `` as ``-destination | response is invalid and will not be executed | Specify the destination as `` specify | #### provide speech output with `` provide Generate spoken content as an audio file and play it with `` The file must be provided as mono WAV with 16-bit PCM and 8 kHz at a publicly accessible HTTPS URL: ```xml https://example.com/audio/announcement.wav ``` #### Control recordings via the REST API The action `` is replaced in Neo by the REST API's recording feature. Start and stop recordings of active calls via `PUT /calls/{callId}/recording` (see the Start and control calls section). Retrieve completed recordings via channel events (`GET /channels/{channelId}/events`, see the History and channel events section). Channel events are only available in Neo. If your integration handles both Classic and Neo accounts during the transition period, you need both approaches: continue using `` and its associated events in Classic, and the REST API and channel events in Neo. #### Redirects with `` Address forwarding destinations in Neo using the phone number: ```xml 4915799912345 ``` Note the attributes of ``: * `callerId` in E.164 format without a leading `+`, for example `4921112345678`. * `anonymous` only with `true` or `false`. With `anonymous="true"` any simultaneously set `callerId` is suppressed. * If the action contains ``, calls are forwarded exclusively to voicemail. No other phone number destinations are called, `callerId` and `anonymous` are not evaluated. Therefore, use `` as the sole destination. #### DTMF prompts with `` For `maxDigits` and `timeout` use only positive integers. Values such as `0`, negative values, or invalid numbers make the response invalid. If you omit an attribute, the default value applies: one digit for `maxDigits`, 2000 milliseconds for `timeout`. ```xml ``` Timeouts are rounded up to whole seconds: 1 to 1000 milliseconds yields one second; 1001 to 2000 milliseconds yields two seconds. Where possible, use multiples of 1000 milliseconds. #### End calls: `` and `` `` is valid only in the direct response to a `newCall`event. To end a call in a later step, for example in a response to a DTMF-`onData` event, use ``: ```xml ``` #### Use Direct URLs The Push API does not follow HTTP redirects in Neo. Responses with status `301`, `302`, `303` or `307` are not followed. For webhooks and audio files, use URLs that directly serve the desired result. #### Behavior When Audio Cannot Be Played If an audio file cannot be retrieved due to an HTTP, network, or TLS error, Neo continues with the next action. If a `` used within it `` cannot be played, the Gather continues without the prompt, continues collecting DTMF input, and can then invoke the `onData` webhook. #### Stored Callback URLs Once set, `onAnswer` and `onHangup` URLs do not need to be repeated in every subsequent response. If you omit the respective attribute, the stored URL remains active for the rest of the call flow. Stored URLs can be replaced: an `onAnswer` or `onHangup` URL in a successful `onData` response by setting the attribute again, and an `onHangup` URL additionally in a valid `onAnswer` response. ## Check Before Migrating An integration needs to be adapted if it does any of the following in particular: * retrieves groups or phonelines, * centrally retrieves events for multiple or all account users, * processes calls or voicemails through History, * is intended to retrieve channel inbox events without membership in the respective channel (administrators: `includeAllUsers`), * starts calls through `/sessions/calls` , * uses legacy voicemail endpoints, * uses Push API call flows with ``, ``, `` destinations, invalid Gather values, or HTTP redirects, * processes group faxes, or * configures sipgate.io using extension IDs. After the changes, the integration should take the account type into consideration and, depending on `featureScope` use the appropriate Classic or Neo endpoints. --- # 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/en/connections-and-integrations/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 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.