Endpoint:
/subscriptions

Methode:
POST

Erforderliche Scopes:

calls.events
calls.events.personal
calls.events.presence

Beschreibung:

Fordert ein neues Abonnement gemäß den im Request-Body angegebenen Einstellungen an. Die Einstellungen beinhalten Filter, um festzulegen, welche Ereignistypen und für welche Agenten (Nebenstellen) Benachrichtigungen empfangen werden sollen.

Verfügbare Parameter

Parameter	Typ	Pattern	Beschreibung
`id`	string	`[a-f0-9]{32}`	Eine 128-Bit-Hex-ID, die das Abonnement eindeutig beschreibt
`event_types`	array	—	Optional. Liste von Ereignissen, auf die abonniert wird. Standard: `["created", "ringing", "answered", "terminated"]`
`agents`	array	—	Optional. Liste von Agenten (Nebenstellen), auf die man abonniert ist. Standard: `[{"number": "*"}]`
`agents[].field`	enum	`*, from, to`	Optional. Gibt an, in welchem Feld nach der Nummer oder Extension-ID gesucht wird. `*` bedeutet beides (Absender und Empfänger).
`agents[].number`	string	`\d{3,15}`	Optional. Die interne Nummer der Extension. `*` bedeutet alle.
`agents[].extension_id`	string	`[a-f0-9]{32}`	Optional. Die spezifische Extension-ID. `*` bedeutet alle.
`mode`	enum	`presence, detailed`	Optional. Standard ist `presence`. `presence` liefert begrenzte Infos (z. B. BLF), `detailed` liefert detaillierte Anrufinformationen.
`callback_url`	string	`.*`	URL, an die Benachrichtigungen via POST gesendet werden. Muss vollständiger Pfad sein (inkl. Protokoll und Domain).
`callback_content_type`	enum	`application/json`	Optional. Der Content-Type der Benachrichtigungen. Zurzeit wird nur `application/json` unterstützt.

Hinweise zu agents[] Feldern:

Wenn agents[].field gesetzt ist, aber agents[].number und agents[].extension_id leer sind, wird field automatisch zu "*" geändert.
Wenn sowohl number als auch extension_id gesetzt sind, wird nach der extension_id gefiltert, und number wird zu "*" gesetzt.

Hinweise zu Scopes und Berechtigungen:

calls.events – Keine Einschränkungen bei agents- oder event_types-Filtern.
calls.events.personal – agents darf nur Ereignisse des Benutzers enthalten, der das Token verwendet. Keine Einschränkungen bei event_types.
calls.events.presence – Nur die Ereignisse "created", "ringing", "answered" und "terminated" mit Modus "presence" sind erlaubt. Keine Einschränkungen bei agents.

Antwort bei Erfolg

HTTP-Status: 200 OK, 201 Created oder 202 Accepted
Der Response-Body enthält das neu erstellte Abonnement-Objekt.

Antwort bei Fehler

Wenn ein Fehler auftritt, wird ein Statuscode ungleich 200 OK zurückgegeben. Der Body enthält ein JSON-Objekt mit Fehlerdetails:

Parameter	Typ	Beschreibung
`status_code`	number	HTTP-Statuscode
`error_code`	string	Optional. Fehlercode
`message`	string	Optional. Beschreibung des Fehlers

Bekannte Fehlercodes

HTTP-Code	Fehlercode	Beschreibung
`400`	`validation`	Validierungsfehler bei den Eingabedaten
`401`	`invalid_grant`	Autorisierungs-Token ist ungültig oder abgelaufen
`403`	`access_denied`	Keine Berechtigung für die angeforderten Scopes