API-Schlüssel und Berechtigungen

Die Ringhum-REST-API ermöglicht es Ihren eigenen Systemen, mit Ihrem Workspace zu arbeiten: Anrufe und Transkripte auflisten, Assistenten erstellen, Termine buchen, Kontakte verwalten, ausgehende Anrufe tätigen und mehr. Jede Anfrage wird mit einem API-Schlüssel authentifiziert, der zu einem Workspace gehört. Dieser Artikel behandelt das Erstellen von Schlüsseln und die Konventionen, die für jeden Endpunkt gelten. Die vollständige Endpunkt-Referenz finden Sie unter /docs.

Wer Schlüssel verwalten kann

Die API ist in jedem Plan verfügbar. Was ein Schlüssel tun kann, wird dennoch durch Ihren Plan begrenzt: Das Erstellen eines Assistenten über das Limit Ihres Plans hinaus liefert zum Beispiel einen Fehler.

Einen API-Schlüssel erstellen

1. Öffnen Sie Entwickler in der Seitenleiste.
2. Klicken Sie in der Karte API-Schlüssel auf Schlüssel erstellen.
3. Geben Sie einen Namen des Schlüssels ein, der zeigt, wo der Schlüssel verwendet wird, zum Beispiel "Produktionsserver".
4. Wählen Sie unter Berechtigungen read, write oder beides aus.
5. Klicken Sie auf Schlüssel erstellen.
6. Kopieren Sie den Schlüssel aus dem grünen Feld und bewahren Sie ihn an einem sicheren Ort auf, etwa im Secret-Store Ihres Servers. Klicken Sie auf Fertig.

Wichtig: Der Schlüssel wird nur einmal angezeigt. Ringhum speichert nur einen Fingerabdruck davon, daher kann er nicht erneut angezeigt werden. Falls Sie ihn verlieren, erstellen Sie einen neuen Schlüssel und widerrufen Sie den alten.

Schlüssel beginnen mit ck_live_. Die Tabelle API-Schlüssel zeigt für jeden Schlüssel den Namen, die ersten Zeichen des Schlüssels, seine Berechtigungen, wann er zuletzt verwendet wurde und ob er Aktiv oder Widerrufen ist.

Berechtigungen

Jeder Schlüssel kann die Endpunkte aufrufen, die nur lesen. Endpunkte, die etwas erstellen, ändern oder löschen, benötigen die Berechtigung write. Beispiele sind das Tätigen eines Anrufs, das Senden einer Nachricht, das Buchen eines Termins oder das Aktualisieren eines Assistenten. Die Referenz unter /docs kennzeichnet diese Endpunkte. Ein Schlüssel ohne write erhält dabei einen 403-Fehler.

Geben Sie jedem System nur den kleinstmöglichen Zugriff, den es braucht. Ein Reporting-Dashboard benötigt nur read.

Einen Schlüssel widerrufen

1. Suchen Sie unter Entwickler den Schlüssel in der Tabelle API-Schlüssel.
2. Klicken Sie auf Widerrufen und bestätigen Sie.

Anfragen mit diesem Schlüssel schlagen sofort mit 401 fehl. Widerrufene Schlüssel bleiben, markiert als Widerrufen, in der Liste, damit Sie ihre Historie sehen können. Ein Schlüssel kann nicht bearbeitet werden: Um seine Berechtigungen zu ändern, erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Anfragen stellen

• Basis-URL: https://ringhum.com/api/v1
• Authentifizierung: Senden Sie den Schlüssel als Bearer-Token: Authorization: Bearer ck_live_…
• Format: JSON ein- und ausgehend. Senden Sie Content-Type: application/json mit einem Body.
• Zeiten sind ISO 8601 in UTC. Telefonnummern sind im E.164-Format, zum Beispiel +14155550132. IDs sind Ganzzahlen.
• Aktualisierungen verwenden PATCH nur mit den Feldern, die Sie ändern möchten.
• Jede Antwort trägt einen X-Request-Id-Header. Geben Sie ihn an, wenn Sie den Support kontaktieren.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Um zu prüfen, zu welchem Workspace ein Schlüssel gehört, rufen Sie GET /me auf.

Antworten und Paginierung

Ein einzelnes Objekt kommt als {"data": {…}} zurück. Paginierte Listen kommen mit einem meta-Objekt zurück:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Verwenden Sie page und per_page, um durch die Ergebnisse zu blättern. per_page ist standardmäßig 25 und kann höchstens 100 betragen.

Fehler

Jeder Fehler hat dieselbe Form, mit einem stabilen type, den Sie in Ihrem Code prüfen können:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Rate Limits

Sie können 120 Anfragen pro Minute stellen. Antworten enthalten die Header X-RateLimit-Limit und X-RateLimit-Remaining. Überschreiten Sie das Limit, erhalten Sie 429 mit einem Retry-After-Header, der die zu wartenden Sekunden angibt.

Tipp: Fragen Sie nicht per Polling nach Anrufergebnissen. Fügen Sie einen Webhook für call.ended hinzu, und Ringhum sendet Ihnen die Zusammenfassung und das Transkript, sobald der Anruf beendet ist. Siehe Webhooks.

Häufige Fragen

Gibt es eine maschinenlesbare Spezifikation? Ja. Die OpenAPI-3.1-Beschreibung finden Sie unter /api/v1/openapi.json, sie benötigt keinen Schlüssel. Sie können daraus einen Client generieren.

Funktioniert ein Schlüssel nicht mehr, wenn die Person, die ihn erstellt hat, das Unternehmen verlässt? Nein. Schlüssel gehören dem Workspace und funktionieren weiter, bis sie widerrufen werden. Widerrufen Sie Schlüssel, denen Sie nicht mehr vertrauen, besonders wenn jemand mit Zugriff das Unternehmen verlässt.

Kann ich die API von einer Webseite aus verwenden? Nein. Jeder, der die Seite öffnet, könnte den Schlüssel lesen. Rufen Sie die API von Ihrem Server aus auf.