HalloLuci.de JSON-API – Dokumentation

Authentifizierung

Jede Anfrage muss mit einem gültigen Bearer-Token authentifiziert werden. Der Token wird von HalloLuci.de beim Anlegen der JSON-API-Schnittstelle automatisch generiert und kann jederzeit unter Schnittstellen → JSON-API → Token anzeigen abgerufen oder neu generiert werden.

Bearer-Token (empfohlen)

Authorization: Bearer <api_token>

Der API-Token ist ein kryptografisch zufälliger 64-Zeichen-Hex-String. Er wird serverseitig generiert und ist nur über das Dashboard einsehbar.

Bei fehlenden oder falschen Zugangsdaten antwortet die API mit HTTP 401 und einem WWW-Authenticate-Header.

Fehlerformat

Fehler werden als JSON-Objekt mit error (Meldung) und code (HTTP-Statuscode) zurückgegeben.

{
  "error": "Kontakt nicht gefunden.",
  "code": 404
}

HTTP-Code	Bedeutung
`200`	Erfolg
`201`	Ressource erstellt
`400`	Ungültige Anfrage (fehlende Parameter etc.)
`401`	Nicht authentifiziert
`403`	Berechtigung fehlt
`404`	Ressource nicht gefunden
`405`	HTTP-Methode nicht erlaubt

Paginierung

Listen-Endpunkte unterstützen die Parameter limit und offset. Die Antwort enthält total (Gesamtanzahl).

GET https://app.halloluci.de/api_receiver.php?resource=contacts&limit=20&offset=40

{
  "contacts": [...],
  "total": 142,
  "limit": 20,
  "offset": 40
}

Kontakte

Berechtigung: contacts

GET https://app.halloluci.de/api_receiver.php?resource=contacts

Alle Kontakte auflisten

Parameter	Typ	Beschreibung
`limit` opt	int	Max. Ergebnisse (1–200, Standard: 50)
`offset` opt	int	Überspringen (Standard: 0)
`search` opt	string	Suche in Name, Firma, Jobtitel

{
  "contacts": [
    {
      "id": 1,
      "name": "Max Mustermann",
      "company": "Muster GmbH",
      "job_title": "Geschäftsführer",
      "notes": null,
      "phones":     [{"label": "Mobil",  "number": "+4915112345678"}],
      "emails":     [{"label": "E-Mail", "address": "max@muster.de"}],
      "references": [{"system": "CRM-X", "ref_id": "CRM-123"}],
      "addresses":  [{"street": "Musterstr. 1", "city": "München", "zip": "80333", "country": "DE"}]
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

GET https://app.halloluci.de/api_receiver.php?resource=contacts&id=1

Einzelnen Kontakt abrufen

{
  "contact": { "id": 1, "name": "Max Mustermann", ... }
}

POST https://app.halloluci.de/api_receiver.php?resource=contacts

Neuen Kontakt erstellen

Feld	Typ	Beschreibung
`name` req	string	Vollständiger Name
`company` opt	string	Firma
`job_title` opt	string	Berufsbezeichnung
`notes` opt	string	Notizen
`phones` opt	array	`[{"label": "Mobil", "number": "+49..."}]`
`emails` opt	array	`[{"label": "E-Mail", "address": "..."}]`

POST https://app.halloluci.de/api_receiver.php?resource=contacts
Content-Type: application/json

{
  "name": "Erika Musterfrau",
  "company": "Beispiel AG",
  "phones": [{"label": "Büro", "number": "+4989123456"}]
}

Antwortet mit HTTP 201 und dem erstellten Kontakt-Objekt.

PUT https://app.halloluci.de/api_receiver.php?resource=contacts&id=1

Kontakt aktualisieren (nur übermittelte Felder werden geändert)

{
  "company": "Neue Firma GmbH",
  "notes": "Aktualisiert via API"
}

DELETE https://app.halloluci.de/api_receiver.php?resource=contacts&id=1

Kontakt löschen

{"deleted": true, "id": 1}

Anrufe

Berechtigung: calls | Nur lesend (GET).

GET https://app.halloluci.de/api_receiver.php?resource=calls

Anrufliste abrufen. Standard: Basis-Felder. Mit ?include=full wird jeder Anruf vollständig angereichert (Kontakt, Labels, Vorgänge).

Parameter	Typ	Beschreibung
`limit` opt	int	Max. Ergebnisse (1–100, Standard: 20)
`offset` opt	int	Überspringen (Standard: 0)
`status` opt	string	Filter: `completed`, `forwarded`, `failed`, `busy`
`include` opt	string	`full` → jeder Anruf enthält Kontakt, Labels und Vorgänge

GET https://app.halloluci.de/api_receiver.php?resource=calls&id=1

Einzelnen Anruf vollständig abrufen – inkl. zugeordnetem Kontakt, Labels, abgearbeiteten Vorgängen und vollständigem Gesprächsverlauf. Entspricht exakt der Detailansicht im Dashboard.

{
  "call": {
    "id": 1,
    "call_id": "uuid-...",
    "caller_number": "+4915112345678",
    "forward_number": null,
    "call_date": "2026-04-27 10:30:00",
    "duration": 120,
    "duration_seconds": 120,
    "duration_formatted": "00:02:00",
    "status": "completed",
    "cost": 0.06,
    "summary": "Kunde möchte einen Schaden melden. Daten wurden aufgenommen.",
    "notes": "Interne Notiz des Sachbearbeiters",

    "conversation": [
      {"speaker": "assistant", "text": "Guten Tag, was kann ich für Sie tun?"},
      {"speaker": "caller",    "text": "Ich möchte einen Schaden melden."}
    ],

    "contact": {
      "id": 5,
      "name": "Max Mustermann",
      "company": "Muster GmbH",
      "job_title": "Geschäftsführer",
      "notes": null,
      "phones":     [{"label": "Mobil",  "number": "+4915112345678"}],
      "emails":     [{"label": "E-Mail", "address": "max@muster.de"}],
      "references": [{"system": "CRM-X", "id": "CRM-4711"}],
      "addresses":  [{"street": "Musterstr. 1", "city": "München", "zip": "80333", "country": "DE"}]
    },

    "labels": [
      {"id": 2, "name": "Schadenmeldung", "color": "#dc3545", "type": "category", "assigned_by": "ai"},
      {"id": 7, "name": "Max Mustermann", "color": "#6c757d", "type": "employee", "assigned_by": "system"}
    ],

    "processes": [
      {
        "id": 12,
        "workflow_name": "Schadenmeldung",
        "workflow_topic": "schaden",
        "collected_data": {
          "Schadensort": "München",
          "Schadenstag": "27.04.2026",
          "Schadensbeschreibung": "Wasserschaden im Keller"
        },
        "summary": "Wasserschaden am 27.04. im Keller. Kontakt per E-Mail zugesagt.",
        "email_sent": true,
        "sms_sent": false,
        "completed_at": "2026-04-27 10:32:15"
      }
    ]
  }
}

contact ist null wenn die Anrufernummer keinem Kontakt zugeordnet ist. labels und processes sind leere Arrays wenn keine vorhanden.

Konfiguration

Nur lesend (GET). Gibt die Benutzer-Konfiguration zurück. Sensible Felder (SMTP-Passwörter etc.) werden herausgefiltert.

GET https://app.halloluci.de/api_receiver.php?resource=config

Konfiguration lesen

{
  "config": {
    "ansprechpartner": [...],
    "workflows": [...],
    ...
  }
}

Geplante Anrufe

Berechtigung: calls

GET https://app.halloluci.de/api_receiver.php?resource=scheduled_calls

Alle geplanten Anrufe auflisten (sortiert nach Termin aufsteigend)

POST https://app.halloluci.de/api_receiver.php?resource=scheduled_calls

Geplanten Anruf erstellen

Feld	Typ	Beschreibung
`phone` req	string	Ziel-Telefonnummer
`scheduled_at` req	datetime	Termin (ISO 8601, z.B. `2026-05-01T10:00:00`)
`note` opt	string	Interne Notiz

{
  "phone": "+4915112345678",
  "scheduled_at": "2026-05-01T10:00:00",
  "note": "Rückruf wegen Vertragsänderung"
}

PUT https://app.halloluci.de/api_receiver.php?resource=scheduled_calls&id=1

Geplanten Anruf aktualisieren. Felder: phone, scheduled_at, note, status (pending|done|cancelled)

DELETE https://app.halloluci.de/api_receiver.php?resource=scheduled_calls&id=1

Geplanten Anruf löschen