sipgate and telephony

Show sipgate calls in real time, link them to people, dial with one click and provide the address book for the sipgate app.

vynst (inwendo ERP) connects to your phone system in three ways:

Way	Direction	For
sipgate.io push	sipgate → vynst	Every call appears in vynst as a call entry, with person, company and duration
sipgate login (OAuth)	vynst → sipgate	Click to call: staff dial a number directly from vynst
Address book export	vynst → sipgate app	The sipgate app shows the name from vynst for calls and links to the contact

Other phone systems, voice AI agents and systems that use vCon call the general call webhook.

All features need the Calls right (call). The settings are under Settings → Calls (Einstellungen → Anrufe).

Receiving calls from sipgate

In vynst, under Settings → Calls → sipgate.io (Einstellungen → Anrufe → sipgate.io), set a long, random token (iw_sipgate_io_valid_token).
In sipgate.io (webhooks in your sipgate account), enter this URL for incoming and outgoing calls:
```
https://your-instance.iw-erp.de/api/sip/sipgateio?token=<TOKEN>
```
Done. For a new call, vynst replies to sipgate with an XML response that points back to the same address for onAnswer and onHangup.

vynst handles the events as follows:

Event from sipgate	What vynst does
`newCall`	creates a call (`from`, `to`, `direction`) and looks up the number among people and companies
`answer`	records who picked up (`answeringNumber`)
`hangup`	closes the call with its reason (`cause`) and duration

Without a valid token, vynst replies with an empty response and stores nothing.

Showing calls live

Setting	Meaning
`iw_call_realtime_ui_enabled`	shows incoming calls as a pop-up in the admin area and displays ongoing calls
`iw_call_realtime_popup_target_mode`	`all`: everyone with read access to calls sees the pop-up; `target_user`: only the person called (for shared numbers, everyone again)
`iw_call_realtime_popup_incoming_only`	pop-up only for incoming calls
`iw_call_realtime_popup_auto_close_seconds`	pop-up closes after this many seconds
`iw_call_active_max_age_minutes`	older calls without a hangup no longer count as ongoing
`iw_call_push_enabled`	also sends a push notification to the admin app

Technically, vynst publishes every event via MQTT on logged-in/scope/call/live, or on <email>/call/live once the person called is known. Only users with the Calls right may subscribe to these topics. Without an MQTT broker, vynst only increments a counter in Firestore, and the apps then load the ongoing calls through the API.

Call	Purpose
`GET /api/sip/calls/active.json`	ongoing calls
`GET /api/sip/calls.json`	call list with filters, such as `incoming`, `number_in`, `crmperson_in_id`
`GET /api/sip/calls/{id}.json`	one call
`PUT /api/sip/calls/{id}.json`	add to a call, for example a note or an assignment

Click to call

So that vynst can dial for a person, that person signs in to sipgate once:

Create an OAuth application at sipgate, then enter sipgate_client_id and sipgate_client_secret in vynst under Settings → Calls → sipgate login (Einstellungen → Anrufe → sipgate Login).
sipgate_login_redirect_url is the page the person returns to after signing in. [[SECRET]] and [[PROVIDER]] are replaced.
Each person opens /api/sip/login once (signed in, with write access to calls) and confirms at sipgate.

After that, a call starts the call on the chosen device:

curl --request POST https://your-instance.iw-erp.de/api/sip/calls.json \
  --header 'x-iw-jwt-token: <TOKEN>' \
  --header 'content-type: application/json' \
  --data '{"call": {"provider": "sipgate", "device": "e0", "number": "+49301234567"}}'

device is the sipgate device ID (for example e0 for a terminal). With loginId you can use a shared group login instead of your own. If the login is missing, vynst responds with No Sipgate User.

Address book for the sipgate app

The sipgate app can query an external address book. vynst provides all people and companies with phone numbers for this:

GET https://your-instance.iw-erp.de/api/dw/export/json/iw-crm-contact-data-sipgate-json-list

Read access to contacts (crm) is enough.
For this path you may use a long-lived API token (prefix LT_), which you store once in the sipgate app.
sipgate_app_person_redirect_url and sipgate_app_company_redirect_url determine where the link on a contact leads ([[PERSON_ID]] and [[COMPANY_ID]] are replaced).

Other phone systems

Other systems can use a general webhook. It uses the same token:

POST https://your-instance.iw-erp.de/api/sip/generic/webhook?token=<TOKEN>

vynst recognises what arrives from the content:

Content	Recognised by
vCon (for example from a recording or AI solution)	fields `vcon`, `parties`, `dialog`
Report from a voice AI agent	`version` and `call` with `from` and `to`
Call reported after the fact	`call` with `caller` and `callee`
Individual events	`event` or `type` = `new`/`start`, `answer`, `end`/`hangup`, plus `callId`, `from`, `to`, `direction`

Verifying callers on the phone

Phone AI assistants that work with vynst through the MCP server verify callers with the tool caller_verify before they give any information.

API

The endpoints are listed under Smart home and automation, under SipgateAPI.