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:
| Nama field | Penjelasan |
|---|---|
| Alamat yang unik di workspace Anda. Kami menyimpannya setelah menghapus spasi di awal dan akhir serta mengubah huruf menjadi huruf kecil, sehingga Sam@Acme.com dan sam@acme.com dinormalisasi menjadi pengenal yang sama. | |
| phone_number | Nomor telepon yang unik di workspace Anda. Formatnya dinormalisasi ke bentuk internasional. Penyimpanan tidak memverifikasi metadata rencana penomoran, kepemilikan, keterjangkauan, atau persetujuan. |
| first_name | Nama depan opsional, digunakan untuk mempersonalisasi pengiriman. |
| last_name | Nama keluarga opsional. |
| external_id | Opsional. Kunci utama Anda sendiri untuk orang tersebut (ID pengguna dari database Anda), yang unik di workspace Anda jika diisi. Gunakan untuk mencocokkan kontak dengan record Anda sendiri tanpa bergantung pada email. |
| data | Nilai properti kustom, satu untuk setiap properti kontak yang terdaftar. |
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.
Properti diarsipkan, bukan dihapus. Pengarsipan menghentikan penulisan baru ke kunci sambil mempertahankan semua nilai yang sudah tersimpan. Kunci tetap dicadangkan sehingga tidak dapat digunakan kembali dengan tipe berbeda. Batalkan pengarsipan untuk mengaktifkannya kembali. Pencadangan ini juga menjadi alasan tipe tidak dapat diubah: number yang tersimpan tidak boleh mulai dibaca sebagai string. Satu workspace dapat mendaftarkan hingga 200 properti, dan properti yang diarsipkan tetap dihitung dalam batas tersebut karena kuncinya masih dicadangkan.
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.
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.
Untuk menyinkronkan dari database Anda sendiri, buat skrip CLI atau panggil endpoint batch. bird contacts create <email> menambahkan satu kontak. bird contacts batch melakukan upsert hingga 1.000 kontak dalam satu panggilan. Gunakan satu batch per proses, alih-alih satu permintaan per orang, agar daftar kontak tetap selaras 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{
"name": "contacts_create",
"arguments": {
"email": "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 pengenal yang diberikan (alamat email, nomor telepon, atau ID eksternal). Field match_on opsional membatasi pencocokan ke salah satu pengenal tersebut. Entri juga dapat mengatur nilai properti kustom, dan dapat memasukkan setiap kontak dalam permintaan langsung ke audiens melalui audience_ids. Setiap entri berhasil atau gagal secara terpisah, dan respons melaporkan satu hasil per entri sesuai urutan pengajuan:
Contoh kode
{
"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 pengenal sebuah entri menunjuk ke kontak berbeda yang sudah ada, entri tersebut gagal dengan konflik yang perlu ditinjau. Perbaiki record sumber sebelum mencoba lagi; batch tidak menggabungkan kontak-kontak tersebut.
Dua perilaku default berguna untuk sinkronisasi. Batch menggabungkan kunci data ke data kontak yang sudah ada, sehingga impor yang mengubah satu atribut tidak menghapus atribut lainnya. Kirim nilai null untuk mengosongkan satu kunci, 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 emailnya berubah. Pada contoh batch, user_2214 sudah ada, sehingga entri mengarah ke kontak tersebut dan mengganti emailnya dengan email baru.
Menghapus kontak
Menghapus kontak bersifat permanen: record dan keanggotaan audiensnya hilang dan tidak dapat dipulihkan. Namun, supresi dan preferensi tidak berubah. Setelah kontak dihapus, alamat yang mengalami hard bounce tetap ada di daftar supresi, dan alamat yang berhenti berlangganan tetap mempertahankan preferensi opt-out. Jadi, menghapus seseorang tidak diam-diam membuatnya dapat dikirimi email lagi.
Langkah berikutnya
- Audiens: kelompokkan kontak ke dalam daftar yang dapat digunakan kembali
- Supresi: daftar alamat di workspace yang tidak kami kirimi pesan, disimpan terpisah dari kontak Anda
- Pengiriman batch: jangkau banyak penerima dalam satu panggilan, hingga 100 pesan per permintaan
- CLI: buat skrip untuk kontak, properti, dan audiens dengan perintah bird
- Referensi API: skema permintaan dan respons lengkap
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Tonton panduannyaGetting started with emailJelajahi kemampuannyaEmailIkuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Coba praktiknya dan dapatkan ringkasan implementasi