Kontak

Kelola kontak di Kontak > Semua kontak pada dashboard, dengan bird contacts dari terminal, melalui API kontak, atau menggunakan SDKs yang tersedia.

Menjangkau kontak

Untuk mengirim email kepada satu orang, kirim ke alamatnya dengan API pengiriman; record kontak menyimpan identitasnya agar siap digunakan kembali. Untuk menjangkau banyak orang sekaligus, kirim batch, atau kelompokkan mereka ke dalam audiens lalu kirim broadcast. Menyimpan kontak tidak mengirim pesan apa pun dengan sendirinya.

Halaman Kontak

Halaman Kontak menampilkan nama kontak, pengenal, keanggotaan audiens, dan informasi pembuatannya. Cari berdasarkan nama, email, atau telepon, lalu pilih baris untuk membuka kontak. Gunakan tindakan di bagian atas halaman untuk menambahkan satu kontak atau mengimpor banyak kontak. Untuk melihatnya, Anda memerlukan izin baca email_marketing. Untuk menambahkan, mengedit, dan menghapusnya, Anda memerlukan izin tulis.

Isi sebuah kontak

Setiap kontak memiliki alamat email, nomor telepon, atau keduanya, masing-masing unik di workspace Anda. Kontak juga dapat memiliki nama dan pengenal Anda sendiri:

Dashboard menentukan label Email dan SMS dari pengenal yang tersedia. API mengembalikan email dan phone_number; responsnya tidak berisi field channels. Label tersebut tidak membuktikan adanya izin mengirim atau bahwa kontak dapat dijangkau melalui kanal tersebut.

Setiap kontak juga memiliki ID berawalan con_ serta timestamp pembuatan dan pembaruannya. Kontrak field lengkap tersedia di referensi API.

Properti kontak

Properti kontak adalah skema bertipe untuk field kustom pada kontak. Daftarkan properti untuk workspace Anda, lalu setiap kontak dapat memiliki nilainya di bawah data. Menetapkan skema sejak awal membuat personalisasi dan segmentasi dapat diandalkan: nilai selalu diterima dalam tipe yang Anda tetapkan, sehingga template atau filter dapat mengandalkannya.

Kelola properti di Kontak > Properti kontak. Setiap properti memiliki kunci, tipe, dan fallback opsional:

• Kunci adalah nama yang Anda gunakan untuk merujuk nilai, misalnya plan_tier. Kunci harus menggunakan huruf kecil dan diawali huruf (^[a-z][a-z0-9_]*$), serta tidak dapat diubah setelah dibuat.
• Tipe adalah salah satu dari string, number, boolean, atau datetime, dan juga tidak dapat diubah setelah dibuat. datetime menerima timestamp RFC 3339 dengan offset eksplisit, seperti 2026-01-15T11:30:00+02:00, yang kami normalkan ke UTC dengan presisi detik, sehingga nilai tersebut disimpan dan dikembalikan sebagai 2026-01-15T09:30:00Z. Tanggal tanpa waktu ditolak. Dashboard memberi label Teks, Angka, Benar / salah, dan Tanggal & waktu untuk tipe-tipe ini.
• Nilai fallback adalah nilai yang terbaca untuk kontak yang tidak memiliki nilainya sendiri, sehingga plan_tier yang tidak terisi dapat menghasilkan free alih-alih nilai kosong.

Atur nilai properti di tempat Anda mengedit kontak. Formulir kontak di dashboard menampilkan satu input sesuai tipe untuk setiap properti aktif, dan CLI serta API menerima kunci yang sama di bawah data.

Mengarsipkan properti

Pengarsipan adalah cara menghapus properti kontak dari daftar yang digunakan. Bird menyimpan nilainya agar Anda dapat memulihkannya dengan Batalkan arsip. Properti tidak memiliki opsi penghapusan permanen.

Properti yang diarsipkan tidak muncul dalam pemilih properti, termasuk saat memetakan kolom impor. Versi template baru yang membaca properti tersebut tidak dapat dipublikasikan. Pesan kesalahan publikasi menyebutkan nama properti. Template yang sudah dipublikasikan tetap mengirim dan menggunakan nilai kontak atau nilai fallback properti.

Kontak tetap menyimpan nilainya. Anda masih dapat membaca dan memperbaruinya melalui API dan impor. Nilai harus sesuai dengan tipe properti.

Jika otomatisasi yang dipublikasikan, termasuk yang dijeda, menggunakan properti dalam pemicu atau penulisan data kontak, pengarsipan mengembalikan konflik 409. Proses aktif yang menulis properti juga mencegah pengarsipan. Hapus properti dari otomatisasi tersebut atau arsipkan otomatisasinya. Biarkan proses aktif selesai atau batalkan, lalu arsipkan properti lagi. Pesan kesalahan menyebutkan otomatisasi jika Anda memiliki izin untuk membacanya.

Batalkan pengarsipan properti untuk memulihkannya beserta nilainya. Properti akan muncul lagi dalam pemilih dan dapat digunakan dalam versi template baru. Kuncinya tetap dicadangkan selama diarsipkan dan dihitung dalam batas 200 properti workspace.

Mengimpor dan menyinkronkan kontak

Untuk mengimpor daftar dari halaman Kontak, pilih Impor dan unggah file CSV, TSV, atau Excel. Isi satu kontak per baris dan sertakan baris header yang memberi nama kolom. Satu file dapat berisi hingga 50.000 kontak. Ukuran file CSV dapat mencapai 50 MB, sedangkan file spreadsheet dapat mencapai 10 MB.

Baris header membantu mengidentifikasi setiap field kontak. Kolom bernama "Email Address", "E-Mail", atau "Correo electrónico" semuanya dipetakan ke field email. Satu kolom yang berisi nama lengkap dipecah menjadi nama depan dan nama keluarga. Jika dua kolom dapat mengisi field yang sama, kolom dengan nilai yang mendukung namanya akan dipilih. Setiap kolom menampilkan beberapa contoh nilainya agar Anda dapat melihat isinya, dan nama yang dipecah ditampilkan bersama nilai asalnya. Ubah pemetaan melalui dropdown setiap kolom. Semua orang dalam file dapat ditambahkan ke satu atau lebih audiens sebagai bagian dari impor yang sama.

Setiap baris dicocokkan dengan kontak yang sudah ada berdasarkan pengenalnya, lalu kontak tersebut diperbarui, atau dibuat jika masih baru. Jadi, mengimpor ulang file yang sama melakukan upsert tanpa menumpuk duplikat. Sebelum data ditulis, dashboard melaporkan jumlah baris awal yang tidak dapat diimpor dengan pemetaan saat ini. Setelah proses selesai, setiap baris yang dilewati mencantumkan nomor baris sumber dan kesalahannya.

Jumlah duplikat pada impor merujuk pada baris yang berulang di dalam file Anda. Pencocokan menggunakan alamat email jika ada, atau nomor telepon jika tidak. Kecocokan dengan kontak yang sudah ada di workspace Anda muncul sebagai pembaruan saat API mengonfirmasinya.

“This row was not confirmed as saved” berarti dashboard tidak menerima hasil yang mengonfirmasi baris tersebut. Baris mungkin sudah tersimpan, meskipun jumlah yang dibuat dan diperbarui nol. Periksa beberapa kontak yang terpengaruh sebelum mencoba lagi. Biarkan tab impor tetap terbuka sampai selesai; dashboard menjalankan impor dari tab tersebut.

Untuk menyinkronkan dari database Anda sendiri, buat skrip CLI atau panggil batch endpoint. bird contacts create <email> menambahkan satu kontak. bird contacts batch melakukan upsert hingga 1.000 kontak dalam satu panggilan. Gunakan satu batch per proses, bukan satu permintaan per orang, agar daftar kontak Anda tetap sinkron dengan sistem Anda.

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

Setiap entri batch dicocokkan secara otomatis berdasarkan identifier yang disediakan (alamat email, nomor telepon, atau external ID), dan field opsional match_on memaksa pencocokan hanya pada salah satu dari ketiganya. Sebuah entri juga dapat menetapkan nilai properti kustom, dan dapat langsung memasukkan setiap kontak dalam permintaan ke dalam audiens melalui audience_ids. Setiap entri berhasil atau gagal secara independen, dan respons melaporkan satu hasil per entri sesuai urutan pengiriman:

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

Jika identifier suatu entri mengarah ke kontak yang sudah ada namun berbeda, entri tersebut gagal dengan konflik untuk ditinjau. Perbaiki catatan sumber sebelum mencoba lagi; batch tidak menggabungkan kontak-kontak tersebut.

Dua perilaku default berguna untuk sinkronisasi. Batch menggabungkan key data ke data kontak yang sudah ada, sehingga impor yang menyentuh satu atribut tidak menghapus atribut lainnya. Kirim nilai null untuk mengosongkan satu key, atau atur data_mode: "replace" untuk menimpa seluruh map. Tetapkan external_id Anda sendiri pada setiap kontak, agar sinkronisasi berikutnya menemukan orang yang sama meskipun email mereka berubah. Dalam contoh batch, user_2214 sudah ada, sehingga entri tersebut diarahkan ke kontak itu dan menulis email baru di tempatnya.

Menghapus kontak

Menghapus kontak bersifat permanen: catatan beserta keanggotaan audiensnya hilang, dan tidak ada yang dapat memulihkannya. Namun, supresi dan preferensi tidak terpengaruh. Alamat yang mengalami hard bounce tetap ada di daftar supresi Anda, dan alamat yang berhenti berlangganan tetap menyimpan preferensi opt-out-nya, setelah Anda menghapus kontak tersebut, sehingga menghapus seseorang tidak pernah diam-diam menjadikan mereka dapat dikirimi email lagi.

Langkah selanjutnya

• Audiens: mengelompokkan kontak ke dalam daftar yang dapat digunakan kembali
• Supresi: daftar alamat di workspace yang tidak kami kirimi pengiriman, disimpan terpisah dari kontak Anda
• Pengiriman batch: menjangkau banyak penerima dalam satu panggilan, hingga 100 pesan per permintaan
• CLI: mengelola kontak, properti, dan audiens dengan perintah bird
• Referensi API: skema permintaan dan respons lengkap