Kartu kontak WhatsApp
Pesan kartu kontak membagikan satu atau beberapa kontak: nama yang dilihat penerima pada kartu, dan tampilan profil yang bisa mereka buka berisi nomor telepon, email, situs web, alamat, perusahaan, dan tanggal lahir. Gunakan ini untuk memberikan nomor rekan kerja, kurir, atau nomor Anda sendiri kepada pelanggan, alih-alih menempelkan angka ke dalam teks yang kemudian harus mereka ketik ulang.
Mengirim kartu kontak
contact_cards adalah array. Setiap kartu membutuhkan name, dan nama tersebut membutuhkan formatted_name ditambah setidaknya satu bagian lain:
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
contact_cards: [
{
name: {
formatted_name: "Barbara J. Johnson",
first_name: "Barbara",
last_name: "Johnson",
},
phone_numbers: [{ phone_number: "+16505559999", type: "Mobile" }],
},
],
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
contact_cards=[
{
"name": {
"formatted_name": "Barbara J. Johnson",
"first_name": "Barbara",
"last_name": "Johnson",
},
"phone_numbers": [{"phone_number": "+16505559999", "type": "Mobile"}],
}
],
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
ContactCards: []bird.WhatsAppContactCardSend{{
Name: bird.WhatsAppContactNameSend{
FormattedName: "Barbara J. Johnson",
FirstName: bird.String("Barbara"),
LastName: bird.String("Johnson"),
},
PhoneNumbers: &[]bird.WhatsAppContactPhoneSend{{
PhoneNumber: "+16505559999",
Type: bird.String("Mobile"),
}},
}},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$name = (new WhatsAppContactCardSendName())
->setFormattedName('Barbara J. Johnson')
->setFirstName('Barbara')
->setLastName('Johnson');
$phone = (new WhatsAppContactPhoneSend())
->setPhoneNumber('+16505559999')
->setType('Mobile');
$card = (new WhatsAppContactCardSend())
->setName($name)
->setPhoneNumbers([$phone]);
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
contactCards: [$card],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--to +16505551234 \
--from +13124495648 \
--contact-cards '[{"name":{"formatted_name":"Barbara J. Johnson","first_name":"Barbara","last_name":"Johnson"},"phone_numbers":[{"phone_number":"+16505559999","type":"Mobile"}]}]'curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"contact_cards": [
{
"name": {
"formatted_name": "Barbara J. Johnson",
"first_name": "Barbara",
"last_name": "Johnson"
},
"phone_numbers": [
{ "phone_number": "+16505559999", "type": "Mobile" }
]
}
]
}'from wajib ada pada setiap pesan layanan: nomor milik workspace Anda, bukan nomor yang dikelola Bird.
Bentuk lengkapnya menambahkan perusahaan, tanggal lahir, dan array detail kontak lainnya:
Contoh kode
{
"to": "+16505551234",
"from": "+13124495648",
"contact_cards": [
{
"name": {
"formatted_name": "Dr. Barbara J. Johnson Esq.",
"prefix": "Dr.",
"first_name": "Barbara",
"middle_name": "Joana",
"last_name": "Johnson",
"suffix": "Esq."
},
"org": { "company": "Lucky Shrub", "department": "Legal", "title": "Lead Counsel" },
"birthday": "1999-01-23",
"phone_numbers": [
{ "phone_number": "+16505559999", "type": "Landline" },
{ "phone_number": "+19175559999", "type": "Mobile" }
],
"emails": [{ "email": "bjohnson@example.com", "type": "Work" }],
"urls": [{ "url": "https://example.com", "type": "Company" }],
"addresses": [
{
"street": "1 Lucky Shrub Way",
"city": "Menlo Park",
"state": "CA",
"zip": "94025",
"country": "United States",
"country_code": "US",
"type": "Office"
}
]
}
]
}Setiap label type, pada telepon, email, situs web, maupun alamat, adalah teks bebas yang Anda tulis, dikirim persis seperti yang Anda tulis, dan ditampilkan di samping nilainya dalam tampilan profil penerima. WhatsApp tidak menetapkan kosakata untuk ini, jadi Mobile, Landline, Pop-Up dan Work (old) semuanya sama-sama valid.
Apa yang membuat kartu memiliki tombol
Nomor telepon yang ditulis dalam format E.164, dengan kode negara dan + di depannya, membuat kartu tersebut memiliki tombol yang membuka obrolan WhatsApp dengan nomor itu. Nomor yang tidak dapat dibaca Bird sebagai E.164 tetap ditampilkan pada kartu, persis seperti yang Anda tulis; hanya saja tidak mendapat tombol.
Ini termasuk nomor yang ditulis tanpa + di depannya. Bird tidak akan menambahkannya untuk Anda: nomor format nasional dari satu negara bisa diuraikan sebagai nomor valid di negara lain begitu + ditambahkan, yang akan mengarahkan tombol ke orang asing. Menolak menebak hanya mengorbankan tombol; menebak salah mengorbankan penerima dengan obrolan ke orang yang salah.
Kartu yang tidak memiliki nomor telepon sama sekali ditampilkan tanpa tombol obrolan, dan hanya bisa disimpan ke buku alamat.
Batas
| Field | Batas | Diterapkan oleh |
|---|---|---|
| contact_cards | 1 hingga 5 kartu per pesan | Bird, saat accept (422) |
| name | wajib; formatted_name ditambah satu bagian nama lain | Bird, saat accept (422) |
| formatted_name, first_name, middle_name, last_name | hingga 256 karakter | Bird, saat accept (422) |
| prefix, suffix | hingga 64 karakter | Bird, saat accept (422) |
| birthday | opsional, YYYY-MM-DD, dan tanggal yang ada di kalender | Bird, saat accept (422) |
| phone_numbers, emails, urls, addresses | hingga 10 entri masing-masing | Bird, saat accept (422) |
| phone_number | hingga 32 karakter | Bird, saat accept (422) |
| hingga 254 karakter | Bird, saat accept (422) | |
| url | hingga 2.048 karakter, tidak divalidasi sebagai URL | Bird, saat accept (422) |
| type pada telepon, email, situs web, atau alamat mana pun | hingga 64 karakter teks bebas | Bird, saat accept (422) |
| company, department, title | hingga 128 karakter | Bird, saat accept (422) |
| street, city, state, zip, country, country_code | hingga 128 karakter | Bird, saat accept (422) |
Batas lima kartu adalah milik Bird, dan sengaja jauh di bawah jumlah yang diterima WhatsApp. Deskripsi API yang dipublikasikan WhatsApp sendiri menyatakan lima, dokumentasinya merekomendasikan lebih sedikit demi kegunaan dan alasan umpan balik negatif, dan pesan yang terbuka sebagai "Contact 1 and 256 other contacts" adalah vektor spam sebelum menjadi fitur. Menaikkan batas ini nanti merupakan perubahan aditif, jadi tanyakan jika lima terlalu sedikit untuk kebutuhan Anda.
Setiap batas panjang di atas juga milik Bird. WhatsApp tidak menerapkan batas yang berarti dan kliennya tidak mengompensasi: type sepanjang 500 karakter ditampilkan sebagai sepuluh baris satu huruf berulang, dan url sepanjang 4.000 karakter dihapus secara diam-diam, membuat tampilan profil kosong. 422 yang menyebutkan field yang bermasalah lebih baik daripada kartu yang tidak bisa dibaca penerima.
Dua aturan yang tidak bisa diekspresikan skema
Nama membutuhkan bagian kedua. formatted_name saja ditolak dengan 422 E15061 WhatsAppContactNameIncomplete, menyebutkan contact_cards.<n>.name. Salah satu dari prefix, first_name, middle_name, last_name, atau suffix memenuhi syarat, tetapi nilai kosong atau hanya berisi spasi tidak dihitung, dan org tidak menyelamatkannya. Ini adalah persyaratan WhatsApp sendiri, tidak didokumentasikan di mana pun dalam referensinya; Bird menangkapnya saat accept sehingga Anda mendapat error yang bisa ditindaklanjuti, bukan kegagalan asinkron.
Tanggal lahir harus berupa tanggal nyata. birthday adalah YYYY-MM-DD; bentuk lain apa pun, dan tanggal yang tidak ada di kalender, seperti 2026-02-30, ditolak dengan 422 E15062 WhatsAppContactBirthdayInvalid. WhatsApp sendiri menerima 2026-02-30 dan menampilkannya kepada penerima, yang terlihat seperti bug di data Anda.
Membaca kembali kartu
Kartu yang Anda kirim terbaca kembali pada field contact_cards yang sama dengan yang digunakan kartu masuk, melalui daftar pesan atau GET /v1/whatsapp/messages/{id}:
Contoh kode
{
"id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
"direction": "outbound",
"status": "delivered",
"contact_cards": [
{
"name": { "formatted_name": "Barbara J. Johnson", "first_name": "Barbara" },
"phone_numbers": [{ "phone_number": "+16505559999", "type": "Mobile" }]
}
]
}origin dan vcard tidak ada pada kartu yang Anda kirim: WhatsApp menetapkan keduanya pada kartu yang dibagikan kontak. Label type yang Anda kirim terbaca kembali persis seperti yang ditulis, sedangkan label pada kartu yang diterima diubah ke huruf kecil. Lihat Menerima kartu kontak WhatsApp untuk sisi masuk.
Kasus khusus
- Jendela layanan pelanggan harus terbuka. Pengiriman kartu kontak adalah pesan layanan, hanya bisa dikirim di dalam jendela yang terbuka; lihat jendela layanan pelanggan di hub.
- Tidak ada wa_id untuk dikirim. WhatsApp mengidentifikasi kontak kartu berdasarkan account ID; Bird menurunkannya dari setiap phone_number E.164 alih-alih menerimanya secara langsung, sehingga tombol pada kartu tidak pernah bisa mengarah ke tempat selain angka yang tercetak di kartu.
- vcard bersifat read-only. WhatsApp menghasilkannya untuk kartu yang dibagikan kontak. Tidak ada cara mengirim kartu sebagai teks vCard mentah.
- Kartu bukan catatan kontak. Mengirimnya membagikan detail dalam pesan; tidak membuat apa pun di workspace Anda, dan penerima yang menyimpannya adalah tindakan mereka sendiri, tidak terlihat oleh Anda.
Langkah selanjutnya
- Pesan layanan WhatsApp: jendela layanan pelanggan dan model yang digunakan bersama setiap pesan layanan
- Permintaan info kontak: minta nomor kontak alih-alih mengirimnya
- Menerima pesan WhatsApp: pesan masuk, media, dan webhook whatsapp.received
- Mengirim pesan WhatsApp: request envelope, model 202, dan coba lagi yang aman
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.
Tonton panduannyaConnecting WhatsApp to Bird: from buying a number to a live channelPahami konsepnyaWhat is the 24-hour customer service window on WhatsApp?Gunakan alatnyaWhatsApp message builderJelajahi kemampuannyaWhatsApp
Coba praktiknya dan dapatkan ringkasan implementasi