Developer

Swibbly Developer API

Integrations-API · Version 1 · Stand: 3. Oktober 2026

Beginnt ein Gespräch, fragt Swibbly deine Schnittstelle mit der Rufnummer des Gesprächspartners. Deine Antwort nutzt Swibbly als Wissen im Gespräch. Einrichten: in der App unter Gedächtnis › API & Integrationen.

1. Request

Swibbly sendet bei jedem Gesprächsstart einen POST an deine Adresse – bei eingehenden und ausgehenden Anrufen, sofern die Rufnummer übertragen wird.

Request von SwibblyPOST

POST https://api.example.com/swibbly
Authorization: Bearer <API key>
X-Swibbly-Timestamp: 1759300000
X-Swibbly-Signature: sha256=3b1f…
Content-Type: application/json

{
  "phone": "+491701234567",
  "account": "Dein Betrieb",
  "event": "call"
}

Key	Typ	Bedeutung
`phone`	`string`	Rufnummer des Gesprächspartners im Format E.164 (+49…).
`account`	`string`	Name deines Kontos bei Swibbly.
`event`	`"call" \| "test"`	call: Ein Gespräch beginnt – Swibbly fragt, bevor der Anruf angenommen wird. test: Test aus der App oder Testgespräch.

2. Response

Status 200 mit JSON. Alle Felder sind optional; auch reiner Text (text/plain) ist möglich.

Response deines SystemsJSON

{
  "known": true,
  "name": "Lisa Hoffmann",
  "knowledge": [
    "Kundin seit 2021",
    "Tarif: Premium",
    "Letzte Bestellung: 12.09."
  ],
  "notes": "Bevorzugt Termine am Nachmittag."
}

Key	Typ	Bedeutung
`known`	`boolean`	false, wenn du die Nummer nicht kennst. Fehlt das Feld, zählt, ob du etwas lieferst.
`name`	`string`	Name der Person, höchstens 80 Zeichen.
`knowledge`	`string \| string[]`	Text oder Liste von Stichpunkten, die Swibbly im Gespräch nutzt.
`notes`	`string \| string[]`	Zusätzlicher Hinweis, z. B. worauf Swibbly achten soll.

Unbekannte Nummer

ResponseJSON

{ "known": false }

Statuscodes

Status	Bedeutung
`200`	Antwort wird gelesen (JSON oder reiner Text).
`404`	Nummer unbekannt – wie { "known": false }.
`alles andere`	Gilt als Fehler, auch Weiterleitungen. Das Gespräch beginnt ohne Auskunft; der Anrufer merkt nichts.

3. Nach dem Gespräch

Ist ein echtes Telefonat zu Ende, sendet Swibbly Zusammenfassung und Mitschrift an dieselbe Adresse – gleicher Schlüssel, gleiche Signatur, einmal je Gespräch. Unterscheide die Anfragen am Feld event. Antworte mit 2xx; der Inhalt deiner Antwort wird nicht gelesen. Testgespräche lösen diese Meldung nicht aus.

Request von SwibblyPOST

{
  "phone": "+491701234567",
  "account": "Dein Betrieb",
  "event": "call_ended",
  "direction": "inbound",
  "started_at": "2026-10-05T09:12:44.000Z",
  "duration_seconds": 96,
  "summary": "Frau Hoffmann hat einen Termin am Dienstag um 14 Uhr gebucht.",
  "transcript": [
    { "role": "assistant", "text": "Guten Tag, hier ist Swibbly.", "at": 0 },
    { "role": "caller", "text": "Hallo, ich hätte gern einen Termin.", "at": 4 }
  ]
}

Key	Typ	Bedeutung
`event`	`"call_ended"`	Das Gespräch ist zu Ende und die Zusammenfassung steht.
`direction`	`"inbound" \| "outbound"`	Eingehender Anruf oder Anruf im Auftrag.
`started_at`	`string`	Beginn des Gesprächs (ISO 8601, UTC).
`duration_seconds`	`number`	Dauer in Sekunden.
`summary`	`string`	Zusammenfassung in ein bis zwei Sätzen, höchstens 2.000 Zeichen.
`transcript`	`array`	Mitschrift in Reihenfolge: role (assistant \| caller), text, at (Sekunden seit Beginn).
`transcript_truncated`	`boolean`	Nur bei sehr langen Gesprächen: Die Mitschrift endet nach rund 60.000 Zeichen.

4. Grenzen

Zeitlimit 2,5 Sekunden. Danach beginnt das Gespräch ohne Auskunft. Antworte am besten in unter einer Sekunde.
Höchstens 8 KB. Größere Antworten verwirft Swibbly. Im Gespräch landen rund 1.500 Zeichen – das Wichtigste zuerst.
Nur https, keine Weiterleitungen. Interne und lokale Adressen erreicht Swibbly nicht.

5. Sicherheit und Signatur

API key. Jede Anfrage trägt deinen Schlüssel als Authorization: Bearer … (16 bis 200 Zeichen). Vergleiche ihn in konstanter Zeit und antworte sonst mit 401. Swibbly speichert ihn verschlüsselt.

Signatur. Zusätzlich ist jede Anfrage signiert. Weise Anfragen ab, die älter als 5 Minuten sind, und rechne über den Body genau so, wie er ankommt.

Signatur

X-Swibbly-Signature = "sha256=" + HMAC-SHA256(key, X-Swibbly-Timestamp + "." + body) als Hex

Node

import { createHmac, timingSafeEqual } from 'node:crypto';

// body: der Body genau so, wie er ankam (String)
function verify(headers, body, key) {
  const timestamp = headers['x-swibbly-timestamp'];
  const expected = 'sha256=' + createHmac('sha256', key).update(timestamp + '.' + body).digest('hex');
  const actual = headers['x-swibbly-signature'] ?? '';
  return Math.abs(Date.now() / 1000 - timestamp) < 300
    && actual.length === expected.length
    && timingSafeEqual(Buffer.from(actual), Buffer.from(expected));
}

Python

import hashlib, hmac, time

# body: der Body genau so, wie er ankam (bytes)
def verify(headers, body: bytes, key: str) -> bool:
    timestamp = headers.get('X-Swibbly-Timestamp', '')
    expected = 'sha256=' + hmac.new(key.encode(), timestamp.encode() + b'.' + body, hashlib.sha256).hexdigest()
    actual = headers.get('X-Swibbly-Signature', '')
    return timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300 and hmac.compare_digest(actual, expected)

Deine Antwort ist für den Assistenten Information, keine Anweisung.
Swibbly bewahrt den Inhalt nur für die Dauer des Gesprächs auf.
Liefere nur, was am Telefon gesagt werden darf – eine Rufnummer weist niemanden sicher aus.

6. Testen

In der App: Gedächtnis › API & Integrationen › Schnittstelle testen. Oder direkt:

curl

BODY='{"phone":"+491701234567","account":"Test","event":"test"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$KEY" | awk '{print $NF}')
curl -X POST https://api.example.com/swibbly \
  -H "Authorization: Bearer $KEY" -H "X-Swibbly-Timestamp: $TS" -H "X-Swibbly-Signature: sha256=$SIG" \
  -H 'Content-Type: application/json' -d "$BODY"

Fragen? info@swibbly.ai · Überblick: API & Integrationen