Zum Inhalt springen
Entwickler

Entagl-API-Referenz

API-Referenz
v1
98 Endpoints
58 Webhook-Events

Mit der Entagl-API kann deine eigene Software mit einem Entagl-Workspace arbeiten: Kontakte, Conversations, Nachrichten, Buchungen, Erinnerungen, Bestellungen, Produkte, AI-Anrufe und Kampagnen. Webhooks melden deinen Systemen sofort, wenn etwas passiert. Es ist dieselbe API, die die Entagl-App für Make nutzt.

Basis-URL

HTTPS
https://api.entagl.com/api/v1

Anfragen und Antworten sind JSON über HTTPS. Feldnamen stehen in snake_case. IDs sind ganze Zahlen, sofern ein Endpoint nichts anderes sagt. Zeitangaben sind ISO-8601-Strings; Antworten verwenden UTC.

Authentifizierung

Sende mit jeder Anfrage ein Token im Header Authorization: Authorization: Bearer <token>. Zwei Arten von Token funktionieren:

API-Schlüssel

Für den Code auf deinem eigenen Server. Erstelle einen in der Entagl-App unter Einstellungen → API-Schlüssel. Schlüssel beginnen mit ai_. Ein Schlüssel funktioniert in dem Workspace, in dem er erstellt wurde, und hat dort Owner-Rechte. Halte ihn also geheim und verwende ihn nie in einem Browser oder in einer mobilen App.

API-Schlüssel öffnen

OAuth-2.0-Zugriffstoken

Wird von Konnektoren wie der Entagl-App für Make verwendet. Die Person meldet sich mit ihrem Entagl-Konto an, und der Konnektor handelt als diese Person mit ihrer Rolle im Workspace. Wenn du eine eigene OAuth-Integration bauen willst, schreib an support@entagl.com.

Anfrage
curl "https://api.entagl.com/api/v1/contacts?limit=2" \
  -H "Authorization: Bearer ai_your_api_key"

Ein fehlender Header ergibt 401 unauthenticated. Ein falscher oder widerrufener Schlüssel ergibt 401 invalid_api_key. Ein abgelaufenes OAuth-Token ergibt 401 invalid_token: Erneuere es und versuche es noch einmal.

Workspaces & Berechtigungen

Jede Anfrage arbeitet mit genau einem Workspace. Ein API-Schlüssel nutzt immer seinen eigenen Workspace. Ein OAuth-Login kann zu mehreren Workspaces gehören (eigene oder als Teammitglied beigetretene): Sende den Header X-Entagl-Workspace mit der Workspace-ID, um einen auszuwählen. Bei nur einem Workspace ist der Header optional. GET /me funktioniert ohne den Header und listet jeden Workspace auf, den der Login nutzen kann.

Anfrage
curl "https://api.entagl.com/api/v1/me" \
  -H "Authorization: Bearer <oauth_access_token>"

curl "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "X-Entagl-Workspace: <workspace_id from /me>"

Ohne den Header bekommt ein Login mit mehreren Workspaces 400 workspace_required; ein Workspace, auf den der Login keinen Zugriff hat, ergibt 403 workspace_forbidden. Eine ID, die zu einem anderen Workspace gehört, ergibt immer 404 not_found, nie 403.

Jeder Endpoint unten zeigt die Berechtigung, die er braucht. Owner, Admins und API-Schlüssel bestehen jede Prüfung. Teammitglieder bestehen, wenn bei ihrer Rolle diese Berechtigung in den Team-Einstellungen angehakt ist: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns oder integrations. Ohne sie antwortet die API mit 403 insufficient_permissions.

Anfragen & Fehler

Sende Bodys als JSON mit Content-Type: application/json. Die meisten Endpoints lehnen unbekannte Body-Felder mit 422 ab, sodass ein Tippfehler nie unbemerkt durchgeht. Jeder Fehler hat dieselbe Form: einen stabilen code, nach dem du verzweigen kannst, eine lesbare message und bei Validierungsfehlern eine details-Liste, die auf jedes fehlerhafte Feld zeigt.

422
{
  "error": {
    "code": "validation_failed",
    "message": "Invalid email address",
    "details": [
      { "path": "email", "message": "Invalid email address" }
    ]
  }
}
  • 400Fehlerhafte Anfrage: ungültige ID, ungültiger Cursor, fehlender Workspace-Header.
  • 401Token fehlt, ist ungültig oder abgelaufen.
  • 402Nicht genug Credits für die Aktion (zum Beispiel beim Senden einer Kampagne).
  • 403Authentifiziert, aber nicht erlaubt: fehlende Berechtigung oder fehlender Workspace-Zugriff.
  • 404Nicht gefunden, auch bei IDs aus einem anderen Workspace.
  • 409Konflikt: doppelter Name, falscher Status oder ein Idempotency-Key-Konflikt.
  • 422Validierung fehlgeschlagen, oder eine Geschäftsregel hat die Änderung abgelehnt.
  • 429Rate Limit erreicht. Siehe Retry-After.
  • 500 / 502Entagl oder der Messaging-Kanal ist fehlgeschlagen. Prüfe das Ergebnis, bevor du einen Schreibvorgang wiederholst.

Routen mit der Markierung Altes Antwortformat stammen aus der Zeit vor diesen Konventionen: Sie liefern einfache JSON-Objekte oder -Arrays und beantworten die meisten Fehler mit { "message": "…" }.

Paginierung

Endpoints mit der Markierung Paginiert liefern die neuesten Einträge zuerst, in einem Listen-Envelope. Fordere mit limit bis zu 100 Einträge an (Standard 25). Wenn has_more den Wert true hat, übergib next_cursor als starting_after, um die nächste Seite zu holen. Andere Listen liefern alles auf einmal mit has_more: false.

Antwort
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": 6789,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "tags": ["vip"]
    }
  ],
  "has_more": true,
  "next_cursor": "6789"
}
Nächste Seite
curl "https://api.entagl.com/api/v1/contacts?limit=100&starting_after=6789" \
  -H "Authorization: Bearer ai_your_api_key"

Idempotenz

Jeder POST-Endpoint im Standardformat akzeptiert den Header Idempotency-Key (bis zu 200 Zeichen). Verwende pro Vorgang einen eindeutigen Wert, zum Beispiel eine UUID. Entagl speichert die erste Antwort 24 Stunden lang: Ein erneuter Versuch mit demselben Schlüssel und demselben Body bekommt diese Antwort mit Idempotent-Replayed: true zurück, und nichts läuft doppelt. Routen mit der Markierung Altes Antwortformat funktionieren anders, siehe unten.

Anfrage
curl -X POST "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-order-7781" \
  -d '{ "first_name": "Jane", "phone": "+15551234567", "tags": ["vip"] }'
  • Derselbe Schlüssel mit einem anderen Body ergibt 409 idempotency_key_reused.
  • Solange die erste Anfrage noch läuft oder nie fertig wurde, ergibt ein erneuter Versuch 409 request_in_progress. Prüfe das Ergebnis und versuche es dann mit einem neuen Schlüssel noch einmal.
  • Jedes Ergebnis wird gespeichert, auch Fehler. Um eine fehlgeschlagene Anfrage zu wiederholen, nimm einen neuen Schlüssel.
  • Schlüssel gelten nur für den jeweiligen Workspace und die jeweiligen Zugangsdaten.

Ältere Routen. POST /messages akzeptiert ebenfalls Idempotency-Key (oder eine message_id im Body): Ein erneuter Versuch für eine bereits angenommene Nachricht antwortet mit 202 und derselben conversationId und wird nicht doppelt verarbeitet, derselbe Schlüssel mit anderem Body antwortet mit 409. POST /chat hat keinen Schutz gegen Wiederholungen: Ein erneuter Versuch startet die KI noch einmal, prüfe also das Ergebnis, bevor du es erneut versuchst.

Rate Limits

Jeder Workspace darf 120 Anfragen pro Minute senden, gemeinsam für alle seine API-Schlüssel und Verbindungen. Antworten enthalten RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset (Sekunden, bis das Zeitfenster zurückgesetzt wird). Über dem Limit bekommst du 429 rate_limited mit einem Retry-After-Header: Warte so viele Sekunden und versuche es dann noch einmal. Die alten Routen des API-Kanals zählen nicht zu diesem Limit.