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.

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:

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.

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.

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.

Archiwizowanie właściwości

Archiwizacja to sposób na usunięcie właściwości kontaktu z użycia. Bird zachowuje jej wartości, aby można było ją przywrócić opcją Cofnij archiwizację. Nie ma opcji trwałego usunięcia właściwości.

Zarchiwizowana właściwość znika z list wyboru, także podczas mapowania kolumn importu. Nowych wersji szablonów, które ją odczytują, nie można opublikować. Błąd publikacji wskazuje właściwość. Już opublikowane szablony nadal wysyłają wiadomości i korzystają z wartości kontaktu lub wartości zastępczej właściwości.

Kontakty zachowują zapisane wartości. Nadal można je odczytywać i aktualizować przez API i importy. Wartości muszą odpowiadać typowi właściwości.

Jeśli opublikowana automatyzacja, również wstrzymana, używa właściwości w wyzwalaczu albo przy zapisie danych kontaktu, archiwizacja zwraca konflikt 409. Aktywne wykonanie, które zapisuje właściwość, także blokuje archiwizację. Usuń właściwość z tych automatyzacji lub je zarchiwizuj. Poczekaj na zakończenie aktywnych wykonań lub je anuluj, a następnie ponownie zarchiwizuj właściwość. Błąd wskazuje automatyzacje, jeśli masz uprawnienia do ich odczytu.

Cofnij archiwizację, aby przywrócić właściwość wraz z jej wartościami. Ponownie pojawi się na listach wyboru i będzie dostępna w nowych wersjach szablonów. Jej klucz pozostaje zarezerwowany podczas archiwizacji i wlicza się do limitu 200 właściwości w obszarze roboczym.

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.

Licznik duplikatów w imporcie odnosi się do powtórzonych wierszy w pliku. Używa adresu e-mail, jeśli jest obecny, lub numeru telefonu w przeciwnym razie. Dopasowania do kontaktów już istniejących w obszarze roboczym pojawiają się jako aktualizacje, gdy API je potwierdzi.

“This row was not confirmed as saved” oznacza, że dashboard nie otrzymał wyniku potwierdzającego ten wiersz. Wiersz mógł zostać zapisany, nawet jeśli liczniki utworzonych i zaktualizowanych wynoszą zero. Sprawdź kilka dotkniętych kontaktów przed ponowną próbą. Nie zamykaj karty importu, dopóki się nie zakończy; dashboard wykonuje import z tej karty.

Aby zsynchronizować dane z własnej bazy, użyj skryptu CLI lub wywołaj endpoint wsadowy. bird contacts create <email> dodaje jeden kontakt. bird contacts batch wykonuje upsert do 1000 kontaktów w jednym wywołaniu. Używaj jednego wsadu na uruchomienie zamiast jednego żądania na osobę, aby lista kontaktów była zsynchronizowana z Twoim systemem.

const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"

contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
print(contact.id, contact.email)

contact, err := client.Contacts.Create(context.Background(), bird.ContactCreateParams{
	Email:     bird.Ptr("jane@acme.com"),
	FirstName: bird.Ptr("Jane"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(contact.Id)

$contact = $bird->contacts->create(
    (new ContactCreateRequest())
        ->setEmail('jane@acme.com')
        ->setFirstName('Jane'),
);
echo $contact->getId(); // "con_…"

bird contacts create alice@acme.com \
  --first-name Alice \
  --last-name Anderson \
  --phone-number +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "phone_number": "+31612345678",
    "first_name": "Alice",
    "last_name": "Anderson"
  }'

Każdy wpis wsadu jest automatycznie dopasowywany na podstawie podanych identyfikatorów (adres e-mail, numer telefonu lub identyfikator zewnętrzny), a opcjonalne pole match_on wymusza dopasowanie tylko po jednym z nich. Wpis może również ustawiać wartości właściwości niestandardowych i dodawać każdy kontakt z żądania bezpośrednio do odbiorców za pomocą audience_ids. Każdy wpis kończy się powodzeniem lub błędem niezależnie, a odpowiedź zawiera jeden wynik na wpis w kolejności przesłania:

{
  "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 wpisu wskazują na różne istniejące kontakty, wpis kończy się konfliktem do przejrzenia. Popraw rekord źródłowy przed ponowną próbą; wsad nie scala tych kontaktów.

Dwa domyślne zachowania są przydatne przy synchronizacji. Wsad scala klucze data z istniejącymi danymi kontaktu, więc import modyfikujący jeden atrybut nigdy nie nadpisuje pozostałych. Wyślij wartość null, aby wyczyścić jeden klucz, lub ustaw data_mode: "replace", aby nadpisać całą mapę. Ustaw własny external_id na każdym kontakcie, aby późniejsza synchronizacja znalazła tę samą osobę nawet po zmianie adresu e-mail. W przykładzie wsadowym user_2214 już istnieje, więc wpis jest rozwiązywany do tego kontaktu i zapisuje nowy adres e-mail w jego miejsce.

Usuwanie kontaktu

Usunięcie kontaktu jest nieodwracalne: rekord i przynależności do odbiorców znikają i nic ich nie przywróci. Blokady i preferencje pozostają jednak nienaruszone. Adres, który zwrócił trwały błąd dostarczenia, pozostaje na Twojej liście blokad, a adres, który się wypisał, zachowuje preferencję rezygnacji po usunięciu kontaktu, więc usunięcie kogoś nigdy po cichu nie sprawia, że ponownie można do niego wysyłać wiadomości.

Następne kroki

• Odbiorcy: grupuj kontakty w listy wielokrotnego użytku
• Blokady: lista adresów w obszarze roboczym, na które nie dostarczamy wiadomości, przechowywana oddzielnie od kontaktów
• Wysyłka wsadowa: wysyłanie do wielu odbiorców w jednym wywołaniu, do 100 wiadomości na żądanie
• CLI: skryptowe zarządzanie kontaktami, właściwościami i grupami odbiorców za pomocą polecenia bird
• Dokumentacja API: pełne schematy żądań i odpowiedzi