API v2 Kontakte und Leads

Kontakte verknüpfen Ihre eigenen stabilen Endnutzer-IDs mit Namen, E-Mail-Adressen und Telefonnummern. Leads sind schreibgeschützte Einsendungen, die von einem Agenten erfasst werden. Jeder Endpunkt auf dieser Seite erfordert Authorization: Bearer YOUR_API_KEY und Zugriff auf {agentId}.

Informationen zu signierten Identitätsangaben im eingebetteten Chat finden Sie unter Identitätsprüfung. Gemeinsame Authentifizierungs- und Validierungsfehler finden Sie im Fehlerkatalog.

Kontaktobjekt

Contact payloads expose customAttributes; write requests accept customAttributes.plan and other JSON keys such as customAttributes.seats.

Kontakte auflisten

Path: /api/v2/agents/{agentId}/contacts

GET /api/v2/agents/{agentId}/contacts

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts?search=alice&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Erfolg: 200 OK

{
  "data": [
    {
      "id": "f9878f31-c2b3-469f-a82e-26e996e67721",
      "externalId": "customer_123",
      "name": "Alice Example",
      "email": "[email protected]",
      "phone": "+1 555 0100",
      "customAttributes": { "plan": "pro", "seats": 4 },
      "createdAt": 1784332800,
      "updatedAt": 1784332800,
      "lastSeenAt": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Ungültige Limits oder Cursor führen zu 400 VALIDATION_INVALID_BODY.

Lead-Objekt

Leads auflisten

Path: /api/v2/agents/{agentId}/leads

GET /api/v2/agents/{agentId}/leads

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Wenn beide Datumsfilter angegeben sind, muss createdAfter beim Vergleich als Zeitpunkt kleiner oder gleich createdBefore sein. Gleiche Grenzwerte sind zulässig.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/leads?createdAfter=2026-07-18T08:00:00Z&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Erfolg: 200 OK

{
  "data": [
    {
      "id": "ad47f673-6bfb-43a0-a296-d79c84870a32",
      "name": "Alice Example",
      "email": "[email protected]",
      "phone": "+1 555 0100",
      "conversationId": "a1b2c3d4e5f6g7h8",
      "createdAt": 1784361600
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Leads werden nach Einsendezeitpunkt vom neuesten zum ältesten sortiert. Ungültige Limits, Cursor, Datums-/Zeitwerte oder vertauschte Datumsgrenzen führen zu 400 VALIDATION_INVALID_BODY.

Einen Kontakt erstellen oder aktualisieren

POST /api/v2/agents/{agentId}/contacts

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Dieser Endpunkt führt ein Upsert auf dem Paar {agentId, externalId} durch. Existiert bereits ein passender Kontakt, werden nur die in der Anfrage enthaltenen Profilfelder aktualisiert. Ein weggelassenes Feld behält seinen gespeicherten Wert; ein explizites null oder ein leerer String löscht ihn.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"customer_123","name":"Alice Example","email":"[email protected]","customAttributes":{"plan":"pro","seats":4}}'

Erfolg: 201 Created, sowohl für Neueinträge als auch für Aktualisierungen bei Konflikten. Das Kontaktobjekt wird als reines Objekt zurückgegeben.

{
  "id": "f9878f31-c2b3-469f-a82e-26e996e67721",
  "externalId": "customer_123",
  "name": "Alice Example",
  "email": "[email protected]",
  "phone": null,
  "customAttributes": { "plan": "pro", "seats": 4 },
  "createdAt": 1784332800,
  "updatedAt": 1784332800,
  "lastSeenAt": null
}

Ungültige Bodys führen zu 400 VALIDATION_INVALID_BODY mit Validierungsdetails.

Kontakte importieren

Path: /api/v2/agents/{agentId}/contacts/import

POST /api/v2/agents/{agentId}/contacts/import

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Die Anfrage verwendet Feldnamen in snake_case. rows muss 1 bis 1.000 Einträge enthalten.

Zeilen werden innerhalb der Anfrage anhand von external_id dedupliziert; das letzte Vorkommen gewinnt. Anders als beim partiellen Upsert eines einzelnen Kontakts erzeugt der Import für jede beibehaltene Zeile jedes Profilfeld, sodass ein weggelassener, null- oder leerer Profilwert bei einem Konflikt als null gespeichert wird.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/contacts/import' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"rows":[{"external_id":"customer_123","name":"Alice Example","email":"[email protected]","phone":"+1 555 0100","customAttributes":{"plan":"pro"}},{"external_id":"customer_456","name":"Bob Example","email":"[email protected]","phone":null}]}'

Erfolg: 200 OK

{
  "processed": 2,
  "skipped": 0
}

processed ist die Anzahl der eindeutigen externen IDs, für die ein Upsert durchgeführt wurde. skipped ist die Anzahl der aus dem übermittelten Batch entfernten Duplikatzeilen. Ungültige Bodys, einschließlich leerer Batches und Batches mit mehr als 1.000 Zeilen, führen zu 400 VALIDATION_INVALID_BODY.

Referenz

• API-v2-Übersicht
• API-v2-Fehlerkatalog
• Unterhaltungen und nutzerbezogener Verlauf
• Identitätsprüfung