SparkTG

Wechsel zu API v2-Dokumentation

Wechsel zu API v2

v2

Wechsel zu API v2

Token-basierte Authentifizierung für Ihre bestehende Integration

Ihre Integration ruft die SparkTG-API unter /api/v1 auf und sendet bei jeder Anfrage einen SparkTG-Benutzernamen und ein Passwort. Die API-Authentifizierung wird auf signierte API-Tokens umgestellt, die für dieselben Endpunkte unter /api/v2 verfügbar sind. Endpunkte, Parameter und Antworten bleiben gleich: Bei den meisten Integrationen ändern sich nur die Basis-URL und der Authorization-Header.

Warum zu v2 wechseln

Was gesendet wird
Benutzername + Passwort (v1):Ein Login-Passwort, bei jeder Anfrage
API-Token (v2):Ein signiertes Token; kein Passwort verlässt je die Hände Ihres Admins
Bei einem Leck
Benutzername + Passwort (v1):Funktioniert, bis das Passwort geändert wird – und dasselbe Passwort öffnet unter Umständen auch das Dashboard
API-Token (v2):Widerrufen Sie genau dieses Token sofort auf der Seite API Access Tokens; Dashboard-Logins sind nicht betroffen
Geltungsbereich
Benutzername + Passwort (v1):Alles, worauf dieser Benutzer Zugriff hat
API-Token (v2):Genau ein Service, im Token festgelegt
Gültigkeit
Benutzername + Passwort (v1):Kein Ablauf
API-Token (v2):Läuft nach einem Jahr ab; erneuern Sie es, indem Sie ein neues Token erzeugen
Wer es erstellen kann
Benutzername + Passwort (v1):Jeder, der das Passwort kennt
API-Token (v2):Nur ein Service-Admin, nach Prüfung mit einem Einmalpasswort (OTP)
Stabilität
Benutzername + Passwort (v1):Funktioniert nicht mehr, sobald jemand das Passwort ändert
API-Token (v2):An kein Login-Passwort gebunden
Nachvollziehbarkeit
Benutzername + Passwort (v1):—
API-Token (v2):Jede Anfrage wird dem Service des Tokens zugeordnet erfasst

API-Token erzeugen

  1. 1Öffnen Sie im SparkTG-Dashboard Admin → Settings → API Access Tokens.
  2. 2Wählen Sie unter Generate a new token, wo Sie das Einmalpasswort erhalten möchten (SMS, WhatsApp oder Email), und fordern Sie es an.
  3. 3Geben Sie das OTP ein, fügen Sie optional eine Bezeichnung hinzu (zum Beispiel den Namen Ihrer Integration) und erzeugen Sie das Token.
  4. 4Kopieren Sie das Token und bewahren Sie es sicher auf. Es wird nur einmal angezeigt und ist ein Jahr gültig.

Das Token erzeugt Ihr Service-Admin. Dieselbe Seite listet Ihre Tokens und ermöglicht das Widerrufen. Erzeugen Sie vor Ablauf eines Tokens ein neues und stellen Sie Ihre Integration darauf um.

Was sich ändert

Basis-URL
v1 (bisher):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
Authentifizierung
v1 (bisher):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
Service-ID (svc-id / service-id)
v1 (bisher):Wählt den Service aus.
v2:Optional. Der Service ergibt sich immer aus dem Token. Wenn Sie den Wert senden, muss er zum Service des Tokens passen, sonst HTTP 403.
Agent für eine Aktion
v1 (bisher):Wird den gesendeten Parametern entnommen.
v2:Unverändert. Senden Sie weder agent-sip noch agent-id noch agent-number, wird die Aktion dem Admin zugeordnet, der das Token erzeugt hat – senden Sie also agent-sip, agent-id oder agent-number des Agenten.
Geplante Anrufe entfernen
v1 (bisher):GET oder POST
v2:Nur DELETE, Parameter im Query-String
WhatsApp-Nachricht senden
v1 (bisher):Wird als Agent des Benutzers gesendet
v2:Der optionale Query-Parameter agent-id wählt den sendenden Agenten
Services auflisten
v1 (bisher):Alle Services des Benutzers
v2:Nur der Service des Tokens

Erfolgreiche Antworten und endpunktspezifische Fehler sind dieselben wie in v1. Jede v2-Anfrage wird für die Abrechnung der API-Nutzung erfasst.

Beispiele

Benutzername + Passwort (v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
API-Token (v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
  'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'

Ersetzen Sie <YOUR_TOKEN> durch Ihr API-Token

Token-Fehler

Das Token wird geprüft, bevor der Endpunkt läuft – jede v2-Anfrage kann diese Fehler liefern.

HTTP 401Der Authorization-Header fehlt oder ist fehlerhaft, oder das Token ist abgelaufen.
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401Das Token wurde auf der Seite API Access Tokens widerrufen.
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403Der Service, zu dem das Token gehört, ist nicht aktiv.
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403Ein svc-id- oder service-id-Parameter wurde mit einer anderen Service-ID gesendet.
{"status":"error","code":403,"message":"svc-id does not match token's service"}

v2-Endpunkte

Diese APIs sind schon heute über v2 verfügbar. Die übrigen SparkTG-APIs wechseln bald zu v2.