Zum Inhalt

Rufnummern

Verwende einen API-Schlüssel oder REST-OAuth-Access-Token. Scopes und deine aktuellen Workspace-Rechte gelten gemeinsam. Die Beispiele verwenden fiktive Daten.

Agent zuweisen: Rufnummern

PUT /api/external/v1/phone-numbers/{id}/assignment

Scope: phone-numbers:write

Ressource zuerst lesen. Den aktuellen ETag einschließlich Anführungszeichen als If-Match senden. Ändert das aktive Standardrouting. Aktive Overrides, Flow-Routen oder eine andere Agent-Rufnummer können mit 409 blockieren. Kauft oder kündigt keine Nummer.

Parameter

Name Position Typ Pflicht Beschreibung
id Pfad string (uuid) Ja Ressourcen-ID im gebundenen Workspace.
If-Match Header string Ja ETag aus dem vorherigen Leseaufruf einschließlich Anführungszeichen.
Beispiel: "revision-from-get"

Request-Body · application/json

Feld Typ Pflicht Beschreibung
agentId string (uuid) Ja ID des Agents. 
{
  "agentId": "00000000-0000-0000-0000-000000000001"
}

Antwort 200

Erfolgreich.

Header Typ Beschreibung
Cache-Control string Die Antwort darf nicht zwischengespeichert werden.
Beispiel: no-store
ETag string Aktuelle Revision. Bei erforderlichem If-Match unverändert einschließlich Anführungszeichen senden.
Beispiel: "revision-from-get"

application/json

Feld Typ Beschreibung
id string (uuid) Ressourcen-ID in deinem Workspace.
number string Im Workspace gespeicherte Rufnummer.
country string Ländercode.
routingTimezone string Zeitzone für Routing-Zeitpläne.
maxAiCallDurationSeconds integer (int32) Maximale KI-Anrufdauer, in Sekunden.
defaultRoute object Standard-Routingziel oder null ohne Standardzuordnung.
revision string Aktuelle Ressourcenrevision. Beim Ändern den ETag der Antwort als If-Match senden.
defaultRoute — Felder
Feld Typ Beschreibung
type string Typ des Standard-Routingziels.
Werte: AGENT, AGENTIC_FLOW
id string (uuid) Ressourcen-ID in deinem Workspace. 
{
  "id": "00000000-0000-0000-0000-000000000001",
  "number": "string",
  "country": "string",
  "routingTimezone": "string",
  "maxAiCallDurationSeconds": 0,
  "defaultRoute": {
    "type": "AGENT",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  "revision": "revision-from-get"
}
Fehlerantworten
Status Bedeutung
400 Ungültige Eingabe, Auswahl oder Zeitgrenzen.
401 Fehlender, abgelaufener oder ungültiger Zugang. Der Body kann leer sein.
403 Benötigter Scope oder aktuelles Benutzerrecht fehlt. Der Body kann leer sein.
404 Ressource im gebundenen Workspace nicht verfügbar.
409 Fehlende/veraltete Revision oder Abhängigkeits-/Routingkonflikt. Vor erneutem Versuch neu lesen.
429 Gemeinsames Workspace-Budget überschritten. Retry-After abwarten; unklare Schreibvorgänge nicht blind wiederholen.
503 Vorübergehend nicht verfügbar. Unklare Schreibvorgänge vor erneutem Versuch prüfen.

Fehler-Body

Feld Typ Beschreibung
status integer HTTP-Statuscode.
error string Beschreibung des Fehlers.
details any Weitere Fehlerdetails, sofern vorhanden.
Regeln: null erlaubt
code string Maschinenlesbarer Fehlercode.
params object Zusätzliche Werte zum Fehlercode.
fieldErrors object Validierungsfehler nach Eingabefeld.

Bei 429 oder 503 den Header Retry-After (Sekunden) beachten. Unklare Schreibvorgänge vor einem neuen Versuch prüfen.

Zuweisung entfernen: Rufnummern

DELETE /api/external/v1/phone-numbers/{id}/assignment

Scope: phone-numbers:write

Ressource zuerst lesen. Den aktuellen ETag einschließlich Anführungszeichen als If-Match senden. Ändert das aktive Standardrouting. Aktive Overrides, Flow-Routen oder eine andere Agent-Rufnummer können mit 409 blockieren. Kauft oder kündigt keine Nummer.

Parameter

Name Position Typ Pflicht Beschreibung
id Pfad string (uuid) Ja Ressourcen-ID im gebundenen Workspace.
If-Match Header string Ja ETag aus dem vorherigen Leseaufruf einschließlich Anführungszeichen.
Beispiel: "revision-from-get"

Antwort 204

Gelöscht; kein Response-Body.

Header Typ Beschreibung
Cache-Control string Die Antwort darf nicht zwischengespeichert werden.
Beispiel: no-store
Fehlerantworten
Status Bedeutung
400 Ungültige Eingabe, Auswahl oder Zeitgrenzen.
401 Fehlender, abgelaufener oder ungültiger Zugang. Der Body kann leer sein.
403 Benötigter Scope oder aktuelles Benutzerrecht fehlt. Der Body kann leer sein.
404 Ressource im gebundenen Workspace nicht verfügbar.
409 Fehlende/veraltete Revision oder Abhängigkeits-/Routingkonflikt. Vor erneutem Versuch neu lesen.
429 Gemeinsames Workspace-Budget überschritten. Retry-After abwarten; unklare Schreibvorgänge nicht blind wiederholen.
503 Vorübergehend nicht verfügbar. Unklare Schreibvorgänge vor erneutem Versuch prüfen.

Fehler-Body

Feld Typ Beschreibung
status integer HTTP-Statuscode.
error string Beschreibung des Fehlers.
details any Weitere Fehlerdetails, sofern vorhanden.
Regeln: null erlaubt
code string Maschinenlesbarer Fehlercode.
params object Zusätzliche Werte zum Fehlercode.
fieldErrors object Validierungsfehler nach Eingabefeld.

Bei 429 oder 503 den Header Retry-After (Sekunden) beachten. Unklare Schreibvorgänge vor einem neuen Versuch prüfen.

Rufnummer abrufen

GET /api/external/v1/phone-numbers/{id}

Scope: phone-numbers:read

Parameter

Name Position Typ Pflicht Beschreibung
id Pfad string (uuid) Ja Ressourcen-ID im gebundenen Workspace.

Antwort 200

Erfolgreich.

Header Typ Beschreibung
Cache-Control string Die Antwort darf nicht zwischengespeichert werden.
Beispiel: no-store
ETag string Aktuelle Revision. Bei erforderlichem If-Match unverändert einschließlich Anführungszeichen senden.
Beispiel: "revision-from-get"

application/json

Feld Typ Beschreibung
id string (uuid) Ressourcen-ID in deinem Workspace.
number string Im Workspace gespeicherte Rufnummer.
country string Ländercode.
routingTimezone string Zeitzone für Routing-Zeitpläne.
maxAiCallDurationSeconds integer (int32) Maximale KI-Anrufdauer, in Sekunden.
defaultRoute object Standard-Routingziel oder null ohne Standardzuordnung.
revision string Aktuelle Ressourcenrevision. Beim Ändern den ETag der Antwort als If-Match senden.
defaultRoute — Felder
Feld Typ Beschreibung
type string Typ des Standard-Routingziels.
Werte: AGENT, AGENTIC_FLOW
id string (uuid) Ressourcen-ID in deinem Workspace. 
{
  "id": "00000000-0000-0000-0000-000000000001",
  "number": "string",
  "country": "string",
  "routingTimezone": "string",
  "maxAiCallDurationSeconds": 0,
  "defaultRoute": {
    "type": "AGENT",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  "revision": "revision-from-get"
}
Fehlerantworten
Status Bedeutung
400 Ungültige Eingabe, Auswahl oder Zeitgrenzen.
401 Fehlender, abgelaufener oder ungültiger Zugang. Der Body kann leer sein.
403 Benötigter Scope oder aktuelles Benutzerrecht fehlt. Der Body kann leer sein.
404 Ressource im gebundenen Workspace nicht verfügbar.
429 Gemeinsames Workspace-Budget überschritten. Retry-After abwarten; unklare Schreibvorgänge nicht blind wiederholen.
503 Vorübergehend nicht verfügbar. Unklare Schreibvorgänge vor erneutem Versuch prüfen.

Fehler-Body

Feld Typ Beschreibung
status integer HTTP-Statuscode.
error string Beschreibung des Fehlers.
details any Weitere Fehlerdetails, sofern vorhanden.
Regeln: null erlaubt
code string Maschinenlesbarer Fehlercode.
params object Zusätzliche Werte zum Fehlercode.
fieldErrors object Validierungsfehler nach Eingabefeld.

Bei 429 oder 503 den Header Retry-After (Sekunden) beachten. Unklare Schreibvorgänge vor einem neuen Versuch prüfen.

Rufnummern auflisten

GET /api/external/v1/phone-numbers

Scope: phone-numbers:read

Parameter

Name Position Typ Pflicht Beschreibung
page Query integer (int32) Nein Seitenindex ab 0.
Regeln: 0–100000
Standard: 0
size Query integer (int32) Nein Ergebnisse pro Seite.
Regeln: 1–100
Standard: 25

Antwort 200

Erfolgreich.

Header Typ Beschreibung
Cache-Control string Die Antwort darf nicht zwischengespeichert werden.
Beispiel: no-store

application/json

Feld Typ Beschreibung
items Liste von object Ergebnisse dieser Seite.
page integer (int32) Aktueller Seitenindex, beginnend bei 0.
size integer (int32) Angeforderte Anzahl der Ergebnisse pro Seite.
totalElements integer (int64) Gesamtzahl der passenden Ergebnisse.
totalPages integer (int32) Gesamtzahl der Ergebnisseiten.
items — Felder
Feld Typ Beschreibung
id string (uuid) Ressourcen-ID in deinem Workspace.
number string Im Workspace gespeicherte Rufnummer.
country string Ländercode.
routingTimezone string Zeitzone für Routing-Zeitpläne.
maxAiCallDurationSeconds integer (int32) Maximale KI-Anrufdauer, in Sekunden.
defaultRoute object Standard-Routingziel oder null ohne Standardzuordnung.
revision string Aktuelle Ressourcenrevision. Beim Ändern den ETag der Antwort als If-Match senden.
defaultRoute — Felder
Feld Typ Beschreibung
type string Typ des Standard-Routingziels.
Werte: AGENT, AGENTIC_FLOW
id string (uuid) Ressourcen-ID in deinem Workspace. 
{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "number": "string",
      "country": "string",
      "routingTimezone": "string",
      "maxAiCallDurationSeconds": 0,
      "defaultRoute": {
        "type": "AGENT",
        "id": "00000000-0000-0000-0000-000000000001"
      },
      "revision": "revision-from-get"
    }
  ],
  "page": 0,
  "size": 25,
  "totalElements": 1,
  "totalPages": 1
}
Fehlerantworten
Status Bedeutung
400 Ungültige Eingabe, Auswahl oder Zeitgrenzen.
401 Fehlender, abgelaufener oder ungültiger Zugang. Der Body kann leer sein.
403 Benötigter Scope oder aktuelles Benutzerrecht fehlt. Der Body kann leer sein.
429 Gemeinsames Workspace-Budget überschritten. Retry-After abwarten; unklare Schreibvorgänge nicht blind wiederholen.
503 Vorübergehend nicht verfügbar. Unklare Schreibvorgänge vor erneutem Versuch prüfen.

Fehler-Body

Feld Typ Beschreibung
status integer HTTP-Statuscode.
error string Beschreibung des Fehlers.
details any Weitere Fehlerdetails, sofern vorhanden.
Regeln: null erlaubt
code string Maschinenlesbarer Fehlercode.
params object Zusätzliche Werte zum Fehlercode.
fieldErrors object Validierungsfehler nach Eingabefeld.

Bei 429 oder 503 den Header Retry-After (Sekunden) beachten. Unklare Schreibvorgänge vor einem neuen Versuch prüfen.