Sign inGet started

Kontakty

Zarządzaj kontaktami w dashboardzie w Contacts > All contacts, w terminalu za pomocą bird contacts, przez API kontaktów lub przy użyciu dowolnego z SDK.

Docieranie do kontaktów

Aby wysłać e-mail do jednej osoby, użyj jej adresu w API wysyłania. Rekord kontaktu przechowuje jej dane do ponownego użycia. Aby dotrzeć do wielu osób naraz, skorzystaj z wysyłki zbiorczej lub połącz je w grupę odbiorców i wyślij broadcast. Samo zapisanie kontaktu nie powoduje wysłania wiadomości.

Strona Contacts

Strona Contacts pokazuje imię i nazwisko, identyfikatory, członkostwo w grupach odbiorców i informacje o utworzeniu kontaktu. Wyszukaj kontakt po imieniu i nazwisku, adresie e-mail lub numerze telefonu, a następnie wybierz wiersz, aby go otworzyć. Użyj akcji w nagłówku, aby dodać jeden kontakt lub zaimportować wiele. Wyświetlanie wymaga uprawnienia do odczytu email_marketing. Dodawanie, edytowanie i usuwanie wymagają uprawnienia do zapisu.
Strona Contacts w dashboardzie z zapisanymi kontaktami według adresu e-mail, imienia i nazwiska, zewnętrznego identyfikatora i daty utworzenia, z wyszukiwarką oraz przyciskami Properties, Import i Add contact

Co zawiera kontakt

Każdy kontakt ma adres e-mail, numer telefonu lub oba te identyfikatory, z których każdy jest unikatowy w obszarze roboczym. Opcjonalnie może też zawierać imię i nazwisko oraz własny identyfikator:
PoleZnaczenie
emailAdres unikatowy w obszarze roboczym. Usuwamy białe znaki na początku i końcu oraz zapisujemy adres małymi literami, dlatego Sam@Acme.com i sam@acme.com są normalizowane do tego samego identyfikatora.
phone_numberNumer telefonu unikatowy w obszarze roboczym. Format jest normalizowany do postaci międzynarodowej. Zapis nie weryfikuje metadanych planu numeracji, własności numeru, osiągalności ani zgody.
first_nameOpcjonalne imię używane do personalizowania wysyłki.
last_nameOpcjonalne nazwisko.
external_idOpcjonalny własny klucz główny osoby, np. identyfikator użytkownika z bazy danych. Jeśli jest ustawiony, musi być unikatowy w obszarze roboczym. Pozwala dopasować kontakt do własnych rekordów bez polegania na adresie e-mail.
dataWartości własnych właściwości, po jednej na każdą zarejestrowaną właściwość kontaktu.
Dashboard wyznacza etykiety Email i SMS na podstawie obecnych identyfikatorów. API zwraca email i phone_number, ale nie zwraca pola channels. Te etykiety nie potwierdzają zgody na wysyłkę ani osiągalności przez dany kanał.
Każdy kontakt ma także identyfikator z prefiksem con_ oraz znaczniki czasu utworzenia i aktualizacji. Pełną specyfikację pól znajdziesz w dokumentacji API.

Właściwości kontaktów

Właściwości kontaktów definiują schemat typów własnych pól kontaktu. Zarejestruj właściwość w obszarze roboczym, a od tej pory każdy kontakt będzie mógł mieć jej wartość w data. Zadeklarowanie schematu z góry zapewnia niezawodną personalizację i segmentację: wartość zawsze ma zadeklarowany typ, na którym może polegać szablon lub filtr.
Strona Contact properties w dashboardzie z sześcioma właściwościami, ich kluczami, typami, wartościami zastępczymi i datami utworzenia; jedna z właściwości ma etykietę Archived
Zarządzaj nimi w Contacts > Contact properties. Każda właściwość ma klucz, typ i opcjonalną wartość zastępczą:
  • Klucz to nazwa, za pomocą której odwołujesz się do wartości, na przykład plan_tier. Musi być zapisany małymi literami i zaczynać się od litery (^[a-z][a-z0-9_]*$). Po utworzeniu nie można go zmienić.
  • Typ to string, number, boolean lub datetime. Po utworzeniu również nie można go zmienić. datetime przyjmuje znacznik czasu RFC 3339 z jawnym przesunięciem strefy czasowej, takim jak 2026-01-15T11:30:00+02:00. Normalizujemy go do UTC z dokładnością do sekundy, więc ta wartość jest zapisywana i zwracana jako 2026-01-15T09:30:00Z. Sama data bez czasu jest odrzucana. Dashboard oznacza te typy jako Text, Number, True / false i Date & time.
  • Wartość zastępcza jest odczytywana dla kontaktu, który nie ma własnej wartości. Dzięki temu brakujące plan_tier może zwrócić free zamiast pustej wartości.
Właściwości są archiwizowane, a nie usuwane. Archiwizacja blokuje nowe zapisy pod danym kluczem, zachowując wszystkie zapisane wartości. Klucz pozostaje zarezerwowany, więc nigdy nie może wrócić z innym typem. Cofnij archiwizację, aby ponownie używać właściwości. Rezerwacja jest także powodem niezmienności typu: zapisana wartość number nie może nagle zacząć być odczytywana jako string. W obszarze roboczym można zarejestrować maksymalnie 200 właściwości. Zarchiwizowane właściwości wliczają się do limitu, ponieważ ich klucze nadal są zarezerwowane.
Ustawiaj wartości właściwości tam, gdzie edytujesz kontakt. Formularz kontaktu w dashboardzie pokazuje po jednym polu wejściowym z odpowiednim typem dla każdej aktywnej właściwości. CLI i API przyjmują te same klucze w data.

Importowanie i synchronizowanie kontaktów

Aby zaimportować listę ze strony Contacts, wybierz Import i prześlij plik CSV, TSV lub Excel. Umieść jeden kontakt w każdym wierszu i dodaj wiersz nagłówkowy z nazwami kolumn. Plik może zawierać maksymalnie 50 000 kontaktów. Pliki CSV mogą mieć do 50 MB, a pliki arkuszy kalkulacyjnych do 10 MB.
Wiersz nagłówkowy pomaga rozpoznać pola kontaktu. Kolumny o nazwach "Email Address", "E-Mail" lub "Correo electrónico" są mapowane na pole adresu e-mail. Pojedyncza kolumna zawierająca pełne imię i nazwisko jest dzielona na imię i nazwisko. Jeśli dwie kolumny mogłyby wypełnić to samo pole, wybierana jest ta, której wartości potwierdzają jej nazwę. Przy każdej kolumnie widać kilka jej wartości, aby można było sprawdzić zawartość. Podzielone imię i nazwisko jest pokazane obok wartości źródłowej. Zmień mapowanie w menu rozwijanym każdej kolumny. Wszystkie osoby z pliku można w ramach tego samego importu dodać do jednej lub kilku grup odbiorców.
Każdy wiersz jest dopasowywany do istniejącego kontaktu na podstawie zawartych w nim identyfikatorów i aktualizowany albo tworzony jako nowy kontakt. Ponowny import tego samego pliku wykonuje więc upsert zamiast tworzyć duplikaty. Zanim cokolwiek zostanie zapisane, dashboard informuje, ile wstępnie sprawdzonych wierszy nie można zaimportować przy obecnym mapowaniu. Po zakończeniu każdy pominięty wiersz zawiera numer wiersza źródłowego i błąd.
Aby synchronizować kontakty z własną bazą danych, użyj skryptu wywołującego CLI lub wywołaj endpoint operacji zbiorczej. bird contacts create <email> dodaje jeden kontakt. bird contacts batch tworzy lub aktualizuje do 1 000 kontaktów w jednym wywołaniu. Używaj jednej operacji zbiorczej na przebieg zamiast jednego żądania na osobę, aby utrzymywać listę kontaktów w zgodzie z systemem.
const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"
Każda pozycja operacji zbiorczej jest automatycznie dopasowywana na podstawie podanych identyfikatorów: adresu e-mail, numeru telefonu lub zewnętrznego identyfikatora. Opcjonalne pole match_on wymusza zamiast tego dopasowanie na podstawie tylko jednego z nich. Pozycja może też ustawiać wartości własnych właściwości. Za pomocą audience_ids można dodać każdy kontakt z żądania bezpośrednio do grup odbiorców. Każda pozycja niezależnie kończy się sukcesem lub błędem. Odpowiedź zawiera jeden wynik na pozycję, w kolejności przesłania:
Przykład kodu
{
  "data": [
    {
      "contact_id": "con_01ky7q5t51echr7mqj5c08423b",
      "entry": { "email": "alex@example.com", "phone_number": null, "external_id": null },
      "matched_on": "email",
      "status": "updated"
    },
    {
      "contact_id": "con_01ky7q6mxdfhe86c9dqyt866pz",
      "entry": { "email": "jamie@example.com", "phone_number": null, "external_id": null },
      "matched_on": null,
      "status": "created"
    },
    {
      "contact_id": "con_01ky7q7rv9e9pt4vkr0w0gxq5e",
      "entry": { "email": "casey@example.com", "phone_number": null, "external_id": "user_2214" },
      "matched_on": "external_id",
      "status": "updated"
    }
  ]
}
Jeśli identyfikatory pozycji wskazują różne istniejące kontakty, pozycja kończy się konfliktem wymagającym sprawdzenia. Popraw rekord źródłowy przed ponowną próbą. Operacja zbiorcza nie scala tych kontaktów.
Przy synchronizacji przydatne są dwa zachowania domyślne. Operacja zbiorcza scala klucze data z istniejącymi danymi kontaktu, więc import zmieniający jeden atrybut nie usuwa pozostałych. Wyślij wartość null, aby wyczyścić jeden klucz, albo ustaw data_mode: "replace", aby nadpisać całą mapę. Ustaw własny external_id dla każdego kontaktu, aby kolejna synchronizacja znalazła tę samą osobę nawet po zmianie adresu e-mail. W przykładzie operacji zbiorczej user_2214 już istnieje, więc pozycja zostaje dopasowana do tego kontaktu i zastępuje jego adres e-mail nowym.

Usuwanie kontaktu

Usunięcie kontaktu jest trwałe: rekord i jego członkostwa w grupach odbiorców znikają i nie można ich odzyskać. Suppresje i preferencje pozostają jednak bez zmian. Adres, dla którego wystąpiło twarde odbicie, po usunięciu kontaktu nadal znajduje się na liście suppresji, a adres osoby, która się wypisała, zachowuje preferencję rezygnacji. Usunięcie osoby nigdy więc nie sprawia, że niepostrzeżenie znów można do niej wysyłać wiadomości.

Kolejne kroki

  • Grupy odbiorców: łącz kontakty w listy do ponownego użycia
  • Suppresje: lista adresów w obszarze roboczym, na które nie dostarczamy wiadomości, przechowywana oddzielnie od kontaktów
  • Wysyłka zbiorcza: docieraj do wielu odbiorców jednym wywołaniem, do 100 wiadomości na żądanie
  • CLI: zarządzaj kontaktami, właściwościami i grupami odbiorców w skryptach za pomocą polecenia bird
  • Dokumentacja API: pełne schematy żądań i odpowiedzi