Ctrlk
Kontakt
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 are 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 affects in particular integrations that retrieve call events, start calls, process voicemails, or configure sipgate.io.

SMS and fax functions generally remain available via the REST API.

All REST API endpoints mentioned in this article refer to the base URL https://api.sipgate.com/v2. A complete overview of the endpoints can be found in the Swagger documentation.

Determine account type

The account type is visible in the web interface. To do so, open the profile menu in the top right by clicking your user avatar.

With OAuth2, the account type can also be determined from the claim featureScope in the JWT of the bearer token:

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 adjusted?

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 call

/sessions/calls

/calls

Group faxes

/groupfaxlines

/{userId}/faxlines

The endpoints for groups, phonelines, group faxes, and classic voicemails are not available in Neo accounts.

History and channel events

In Neo, calls are no longer provided via the classic history endpoints. Use instead:

The endpoint returns the call events of a channel. Voicemails as well as manual and automatic call recordings are provided through the field recordings of the respective event.

For pagination, the parameters limit and position are available. The positionposition value from a response can be used as a cursor in the next request.

SMS and fax events remain available via the history endpoints in Neo as well. Unlike Classic, however, the history endpoints in Neo only return events that belong to the user whose credentials were used to authenticate the API request. This restriction applies to all event types available via History. An account-wide event view like in Classic is no longer available.

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.

Additionally, for channel inbox events: GET /channels/{channelId}/events returns events only if the authenticated API user is a member of the queried channel. An admin role alone does not grant access.

In particular, check integrations that evaluate events account-wide, archive them, or synchronize them with third-party systems.

Channels

Channels replace the previous groups and phonelines in Neo. The REST API provides, among other things, the following functions:

Endpoint
Function

GET /channels

Retrieve channels of the account

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 devices of a member

DELETE /channels/{channelId}

Delete channel

Additional settings such as ring order, queue, greeting, as well as ring and after-call time are GET /channels provided, but are currently only readable via the REST API.

Start and control calls

For click-to-dial, Classic and Neo use different endpoints:

  • Classic: POST /sessions/calls

  • Neo: POST /calls

In 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 functions 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

supports the optional query parameter type. It accepts a comma-separated list of the following values:

The response also includes 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.

Use in Neo:

The endpoints under /groupfaxlines and the fax functions under /groups are available only with Classic PBX. Fax events remain retrievable in Neo via the history endpoints.

sipgate.io Push API

The Push API is compatible with Classic and Neo.

  • In Classic, webhooks can be configured for extensions.

  • In Neo, configuration is done for channels.

  • Webhook URLs must use HTTPS.

  • Self-signed certificates are not accepted.

The global configuration can be read and changed via the following endpoints:

In the field whitelist Classic extension IDs are passed in Classic, and channel IDs in Neo.

Push API versions

Version
Status
Behavior

1

Stable

Original Push API contract

2

Beta

Adds channelId in the webhook requests

Version 1 remains unchanged. Version 2 is in beta and adds channelId. It is not generally recommended and should only be used if this information is needed. From version 2 onward, new optional request parameters can be added. Integrations should therefore ignore unknown parameters.

When writing the sipgate.io settings, the version can be selected via pushApiVersion . Each webhook also contains 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 for some actions. An integration must be adjusted if it in particular:

  • Generates announcements with <Say> creates,

  • Starts recordings with <Record> starts,

  • <Device>-targets in <Dial>-responses uses,

  • maxDigits or timeout with 0, negative or invalid values,

  • delivers webhook or audio file URLs via HTTP redirect.

Unsupported Classic actions

Classic
Behavior in Neo
Replacement

<Say>

Not supported

Play audio file with <Play> play

<Record>

Not supported

Control recording via REST API

<Device> as <Dial>-target

Response is invalid and will not be executed

Specify target as <Number> specify

Provide voice prompts with <Play> provide

Generate spoken content as an audio file and play it with <Play> . The file must be provided as a mono WAV with 16-bit PCM and 8 kHz at a publicly reachable HTTPS URL:

Control recordings via the REST API

The action <Record> is replaced under Neo by the recording function of the REST API. Start and stop recordings of active calls via PUT /calls/{callId}/recording (see the Start and control calls section). Retrieve completed recordings via the channel events (GET /channels/{channelId}/events, see the History and channel events section).

Channel events are available only in Neo. If your integration processes both Classic and Neo accounts during the transition period, you need both paths: in Classic, continue to use <Record> along with the associated events, and in Neo use the REST API and the channel events.

Forwarding with <Dial>

In Neo, address forwarding destinations via the phone number:

Pay attention to the attributes of <Dial>:

  • callerId in E.164 format without a leading +, for example 4921112345678.

  • anonymous exclusively with true or false. With anonymous="true" a simultaneously set callerId is suppressed.

  • If the action contains <Voicemail />, forwarding occurs exclusively to voicemail. Other call destinations are not dialed, callerId and anonymous are not evaluated. Therefore use <Voicemail /> as the sole target.

DTMF queries with <Gather>

Use exclusively positive integers for maxDigits and timeout 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.

Timeouts are rounded up to full seconds: 1 to 1000 milliseconds result in one second, 1001 to 2000 milliseconds in two seconds. Whenever possible, use multiples of 1000 milliseconds.

Terminate calls: <Reject> and <Hangup>

<Reject> 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 <Hangup />:

Use direct URLs

The Push API follows no HTTP redirects in Neo. Responses with status 301, 302, 303 or 307 are not followed. Use URLs for webhooks and audio files that directly deliver the desired result.

Behavior for unplayable audio files

If an audio file cannot be retrieved due to an HTTP, network, or TLS error, Neo continues with the next action. If a <Gather> used within <Play> cannot be played, the Gather continues without the announcement, keeps collecting DTMF input, and can then invoke the onData-webhook.

Stored callback URLs

Once set, onAnswer- and onHangup-URLs do not have to be repeated in every further response. If you omit the respective attribute, the stored URL remains active for the rest of the call flow.

Stored URLs can be replaced: a onAnswer- or onHangup-URL in a successful onData-response by setting the attribute again, a onHangup-URL additionally in a valid onAnswer-response.

Check before a migration

An integration must be adjusted if it in particular:

  • retrieves groups or phonelines,

  • centrally retrieves events of multiple or all account users,

  • processes calls or voicemails via History,

  • is supposed to retrieve channel inbox events without the API user's membership,

  • calls via /sessions/calls starts,

  • uses classic voicemail endpoints,

  • uses Push API callflows with <Say>, <Record>, <Device>-targets, invalid Gather values, or HTTP redirects,

  • processes group faxes or

  • configures sipgate.io based on extension IDs.

After the adjustment, the integration should take the account type into account and use the appropriate Classic or Neo endpoints depending on featureScope that.

PreviousAPI
NextWhat is the sipgate API and what functions does it offer?

Last updated