sipgate und Telefonie

Anrufe aus sipgate in Echtzeit anzeigen, mit Personen verknüpfen, per Klick wählen und das Adressbuch für die sipgate App bereitstellen.

vynst (inwendo ERP) verbindet sich auf drei Wegen mit eurer Telefonanlage:

Weg	Richtung	Wofür
sipgate.io Push	sipgate → vynst	Jeder Anruf landet als Anruf-Eintrag in vynst, mit Person, Firma und Dauer
sipgate Login (OAuth)	vynst → sipgate	Click-to-Call: Mitarbeiter wählen eine Nummer direkt aus vynst
Adressbuch-Export	vynst → sipgate App	Die sipgate App zeigt bei Anrufen den Namen aus vynst und verlinkt auf den Kontakt

Andere Anlagen, Sprach-KI-Agenten und Systeme mit vCon sprechen den allgemeinen Anruf-Webhook an.

Alle Funktionen brauchen das Recht Anrufe (call). Die Einstellungen liegen unter Einstellungen → Anrufe.

Anrufe aus sipgate empfangen

Legt in vynst unter Einstellungen → Anrufe → sipgate.io einen langen, zufälligen Token fest (iw_sipgate_io_valid_token).
Tragt in sipgate.io (Webhooks im sipgate-Konto) als URL für eingehende und ausgehende Anrufe ein:
```
https://eure-instanz.iw-erp.de/api/sip/sipgateio?token=<TOKEN>
```
Fertig. Bei einem neuen Anruf antwortet vynst sipgate mit einer XML-Antwort, die sich für onAnswer und onHangup wieder bei derselben Adresse meldet.

vynst wertet die Ereignisse so aus:

Ereignis von sipgate	Was vynst tut
`newCall`	legt einen Anruf an (`from`, `to`, `direction`) und sucht die Nummer bei Personen und Firmen
`answer`	merkt sich, wer abgenommen hat (`answeringNumber`)
`hangup`	schließt den Anruf mit Grund (`cause`) und Dauer ab

Ohne gültigen Token antwortet vynst leer und speichert nichts.

Anrufe live anzeigen

Einstellung	Bedeutung
`iw_call_realtime_ui_enabled`	blendet eingehende Anrufe in der Verwaltung als Pop-up ein und zeigt die laufenden Anrufe
`iw_call_realtime_popup_target_mode`	`all`: alle mit Leserecht Anrufe sehen das Pop-up; `target_user`: nur die angerufene Person (bei Sammelnummern wieder alle)
`iw_call_realtime_popup_incoming_only`	Pop-up nur bei eingehenden Anrufen
`iw_call_realtime_popup_auto_close_seconds`	Pop-up schließt nach so vielen Sekunden
`iw_call_active_max_age_minutes`	ältere Anrufe ohne Auflegen gelten nicht mehr als laufend
`iw_call_push_enabled`	zusätzlich eine Push-Nachricht an die Verwaltungs-App

Technisch veröffentlicht vynst jedes Ereignis per MQTT auf logged-in/scope/call/live, oder auf <E-Mail>/call/live, wenn die angerufene Person feststeht. Nur Benutzer mit dem Recht Anrufe dürfen diese Topics abonnieren. Ohne MQTT-Broker zählt vynst nur einen Zähler in Firestore hoch, und die Apps laden die laufenden Anrufe über die API nach.

Aufruf	Zweck
`GET /api/sip/calls/active.json`	laufende Anrufe
`GET /api/sip/calls.json`	Anrufliste mit Filtern, etwa `incoming`, `number_in`, `crmperson_in_id`
`GET /api/sip/calls/{id}.json`	ein Anruf
`PUT /api/sip/calls/{id}.json`	Anruf ergänzen, zum Beispiel Notiz oder Zuordnung

Per Klick anrufen

Damit vynst für eine Person wählen kann, meldet sie sich einmal bei sipgate an:

Bei sipgate eine OAuth-Anwendung anlegen und in vynst unter Einstellungen → Anrufe → sipgate Login sipgate_client_id und sipgate_client_secret eintragen.
sipgate_login_redirect_url ist die Seite, auf die die Person nach dem Login zurückkommt. [[SECRET]] und [[PROVIDER]] werden ersetzt.
Jede Person öffnet einmal /api/sip/login (angemeldet, mit Schreibrecht Anrufe) und bestätigt bei sipgate.

Danach startet ein Aufruf den Anruf auf dem gewählten Gerät:

curl --request POST https://eure-instanz.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 ist die sipgate-Geräte-ID (etwa e0 für ein Endgerät). Mit loginId könnt ihr einen freigegebenen Sammel-Login statt des eigenen nutzen. Fehlt der Login, antwortet vynst mit No Sipgate User.

Adressbuch für die sipgate App

Die sipgate App kann ein externes Adressbuch abfragen. vynst liefert dafür alle Personen und Firmen mit Telefonnummern:

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

Das Recht Kontakte (crm) zum Lesen reicht.
Für diesen Pfad dürft ihr einen langlebigen API-Token (Präfix LT_) verwenden, den ihr einmal in der sipgate App hinterlegt.
sipgate_app_person_redirect_url und sipgate_app_company_redirect_url bestimmen, wohin der Link am Kontakt führt ([[PERSON_ID]], [[COMPANY_ID]] werden ersetzt).

Andere Telefonanlagen

Für andere Anlagen gibt es einen allgemeinen Webhook. Er nutzt denselben Token:

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

vynst erkennt am Inhalt, was ankommt:

Inhalt	Erkannt an
vCon (zum Beispiel aus einer Aufzeichnungs- oder KI-Lösung)	Felder `vcon`, `parties`, `dialog`
Bericht eines Sprach-KI-Agenten	`version` und `call` mit `from` und `to`
Nachträglich gemeldeter Anruf	`call` mit `caller` und `callee`
Einzelne Ereignisse	`event` oder `type` = `new`/`start`, `answer`, `end`/`hangup`, dazu `callId`, `from`, `to`, `direction`

Anrufer am Telefon verifizieren

Telefon-KI-Assistenten, die über den MCP-Server mit vynst arbeiten, prüfen Anrufer vor jeder Auskunft mit dem Tool caller_verify.

API

Die Endpunkte stehen im Bereich Smart Home und Automationen unter SipgateAPI.