API v2 – kontakty i leady

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

Kontakty łączą Twoje własne, stabilne identyfikatory użytkowników końcowych z imionami i nazwiskami, adresami e-mail oraz numerami telefonów. Leady to zgłoszenia tylko do odczytu, zebrane przez agenta. Każdy punkt końcowy na tej stronie wymaga nagłówka Authorization: Bearer YOUR_API_KEY oraz dostępu do {agentId}.

Informacje o podpisanych oświadczeniach tożsamości w osadzonym czacie znajdziesz w sekcji Weryfikacja tożsamości. Wspólne błędy uwierzytelniania i walidacji opisano w katalogu błędów.

Obiekt kontaktu

Lista kontaktów

Ścieżka: /api/v2/agents/{agentId}/contacts

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {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'

Sukces: 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
  }
}

Nieprawidłowe wartości limit lub cursor skutkują błędem 400 VALIDATION_INVALID_BODY.

Obiekt leada

Lista leadów

Ścieżka: /api/v2/agents/{agentId}/leads

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Gdy oba filtry dat są podane, wartość createdAfter musi być mniejsza lub równa createdBefore przy porównaniu jako konkretne chwile w czasie. Równe granice są dozwolone.

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'

Sukces: 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
  }
}

Leady są uporządkowane według czasu zgłoszenia, od najnowszych do najstarszych. Nieprawidłowe wartości limit, cursor, dat i godzin lub odwrócone granice dat skutkują błędem 400 VALIDATION_INVALID_BODY.

Tworzenie lub aktualizacja jednego kontaktu

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Ten punkt końcowy tworzy nowy kontakt lub aktualizuje istniejący na podstawie pary {agentId, externalId}. Jeśli pasujący kontakt już istnieje, aktualizowane są wyłącznie pola profilu obecne w żądaniu. Pominięte pole zachowuje swoją zapisaną wartość; jawne podanie null lub pustego ciągu znaków czyści je.

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}}'

Sukces: 201 Created zarówno przy tworzeniu nowego wpisu, jak i przy aktualizacji w wyniku konfliktu. Obiekt kontaktu jest zwracany bez opakowania.

{
  "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
}

Nieprawidłowa treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY wraz ze szczegółami walidacji.

Importowanie kontaktów

Ścieżka: /api/v2/agents/{agentId}/contacts/import

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Żądanie wykorzystuje nazwy pól w formacie snake_case. Pole rows musi zawierać od 1 do 1000 wpisów.

Wiersze są deduplikowane na podstawie external_id w ramach żądania; wygrywa ostatnie wystąpienie. W przeciwieństwie do częściowej aktualizacji pojedynczego kontaktu, import ustawia wszystkie pola profilu dla każdego zachowanego wiersza, więc pominięta, null lub pusta wartość profilu jest w razie konfliktu zapisywana jako null.

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}]}'

Sukces: 200 OK

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

processed to liczba unikalnych identyfikatorów zewnętrznych, dla których utworzono lub zaktualizowano wpis. skipped to liczba zduplikowanych wierszy usuniętych z przesłanej partii. Nieprawidłowa treść żądania, w tym puste partie oraz partie zawierające ponad 1000 wierszy, skutkuje błędem 400 VALIDATION_INVALID_BODY.

Powiązane materiały

• Przegląd API v2
• Katalog błędów API v2
• Konwersacje i historia poszczególnych użytkowników
• Weryfikacja tożsamości