Schede contatto WhatsApp
Un messaggio con scheda contatto condivide uno o più contatti: un nome che il destinatario vede sulla scheda e una vista profilo che può aprire, contenente numeri di telefono, email, siti web, indirizzi, un datore di lavoro e una data di nascita. Usalo per consegnare a un cliente il numero di un collega, di un corriere o il tuo, anziché incollare cifre in un testo che poi dovrà ricopiare.
Inviare una scheda contatto
contact_cards è un array. Ogni scheda richiede un name, e quel nome richiede formatted_name più almeno un'altra parte:
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 è obbligatorio su ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird.
La struttura completa aggiunge un datore di lavoro, una data di nascita e gli altri array di dettagli contatto:
Esempio di codice
{
"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"
}
]
}
]
}Ogni etichetta type, su un telefono, un'email, un sito web o un indirizzo, è testo libero che scrivi tu, inviato esattamente come lo hai scritto e mostrato accanto al valore nella vista profilo del destinatario. WhatsApp non definisce un vocabolario per queste etichette, quindi Mobile, Landline, Pop-Up e Work (old) sono tutti ugualmente validi.
Cosa fa ottenere un pulsante a una scheda
Un numero di telefono scritto in E.164, con il prefisso internazionale e il + iniziale, fa ottenere alla scheda un pulsante che apre una chat WhatsApp con quel numero. Un numero che Bird non riesce a leggere come E.164 viene comunque mostrato sulla scheda, esattamente come lo hai scritto; semplicemente non ottiene alcun pulsante.
Questo include un numero scritto senza il + iniziale. Bird non ne aggiungerà uno per te: un numero in formato nazionale di un Paese può risultare valido in un altro una volta aggiunto un +, e il pulsante punterebbe a uno sconosciuto. Rinunciare a indovinare costa un pulsante; indovinare sbagliato costa al destinatario una chat con la persona sbagliata.
Una scheda priva di qualsiasi numero di telefono viene mostrata senza pulsante chat e può solo essere salvata in rubrica.
Limiti
| Campo | Vincolo | Imposto da |
|---|---|---|
| contact_cards | Da 1 a 5 schede per messaggio | Bird, all'accettazione (422) |
| name | obbligatorio; formatted_name più un'altra parte del nome | Bird, all'accettazione (422) |
| formatted_name, first_name, middle_name, last_name | fino a 256 caratteri | Bird, all'accettazione (422) |
| prefix, suffix | fino a 64 caratteri | Bird, all'accettazione (422) |
| birthday | facoltativo, YYYY-MM-DD, e una data presente nel calendario | Bird, all'accettazione (422) |
| phone_numbers, emails, urls, addresses | fino a 10 voci ciascuno | Bird, all'accettazione (422) |
| phone_number | fino a 32 caratteri | Bird, all'accettazione (422) |
| fino a 254 caratteri | Bird, all'accettazione (422) | |
| url | fino a 2048 caratteri, non validato come URL | Bird, all'accettazione (422) |
| type su qualsiasi telefono, email, sito web o indirizzo | fino a 64 caratteri di testo libero | Bird, all'accettazione (422) |
| company, department, title | fino a 128 caratteri | Bird, all'accettazione (422) |
| street, city, state, zip, country, country_code | fino a 128 caratteri | Bird, all'accettazione (422) |
Il limite di cinque schede è di Bird, ed è deliberatamente molto inferiore a quanto WhatsApp accetta. La descrizione API pubblicata da WhatsApp dichiara cinque, la sua documentazione ne raccomanda meno per motivi di usabilità e feedback negativo, e un messaggio che si apre come "Contact 1 and 256 other contacts" è un vettore di spam prima ancora di essere una funzionalità. Alzare il limite in futuro sarebbe un cambiamento additivo, quindi chiedi se cinque è insufficiente per ciò che stai costruendo.
Anche ogni limite di lunghezza sopra indicato è di Bird. WhatsApp non ne impone alcuno degno di nota e il suo client non compensa: un type di 500 caratteri viene mostrato come dieci righe di una sola lettera ripetuta, e un url di 4000 caratteri viene scartato silenziosamente, lasciando la vista profilo vuota. Un 422 che indica il campo problematico è meglio di una scheda illeggibile per il destinatario.
Due regole che lo schema non può esprimere
Un nome richiede una seconda parte. Il solo formatted_name viene rifiutato con un 422 E15061 WhatsAppContactNameIncomplete, che indica contact_cards.<n>.name. Uno qualsiasi tra prefix, first_name, middle_name, last_name o suffix lo soddisfa, ma un valore vuoto o composto solo da spazi non conta, e un org non lo salva. Questo è un requisito di WhatsApp, non documentato da nessuna parte nel suo riferimento; Bird lo intercetta all'accettazione, così ottieni un errore utilizzabile anziché un fallimento asincrono.
La data di nascita deve essere una data reale. birthday è YYYY-MM-DD; qualsiasi altro formato, e qualsiasi data che il calendario non contiene, come 2026-02-30, viene rifiutato con un 422 E15062 WhatsAppContactBirthdayInvalid. WhatsApp stesso accetta 2026-02-30 e lo mostra al destinatario, il che sembra un bug nei tuoi dati.
Rileggere una scheda
Una scheda che hai inviato viene riletta sullo stesso campo contact_cards usato da una scheda in entrata, tramite la lista messaggi o GET /v1/whatsapp/messages/{id}:
Esempio di codice
{
"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 e vcard sono assenti su una scheda che hai inviato: WhatsApp li imposta entrambi su una scheda condivisa da un contatto. Un'etichetta type che hai inviato viene riletta esattamente come scritta, mentre un'etichetta su una scheda ricevuta viene convertita in minuscolo. Vedi Ricevere schede contatto WhatsApp per il lato in entrata.
Casi limite
- La finestra del servizio clienti deve essere aperta. L'invio di una scheda contatto è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; vedi la finestra del servizio clienti dell'hub.
- Non esiste un wa_id da inviare. WhatsApp identifica il contatto di una scheda tramite un account ID; Bird lo ricava da ogni phone_number E.164 anziché accettarne uno, quindi il pulsante su una scheda non può mai puntare a qualcosa di diverso dalle cifre stampate su di essa.
- vcard è in sola lettura. WhatsApp lo genera per una scheda condivisa da un contatto. Non c'è modo di inviare una scheda come testo vCard grezzo.
- Una scheda non è un record contatto. Inviarne una condivide dei dettagli in un messaggio; non crea nulla nel tuo spazio di lavoro, e il salvataggio da parte del destinatario è una sua azione, invisibile per te.
Prossimi passi
- Messaggi di servizio WhatsApp: la finestra del servizio clienti e il modello condiviso da ogni messaggio di servizio
- Richieste di informazioni di contatto: chiedi a un contatto il suo numero anziché inviarne uno
- Ricevere messaggi WhatsApp: messaggi in entrata, media e il webhook whatsapp.received
- Inviare messaggi WhatsApp: la struttura della richiesta, il modello 202 e i tentativi sicuri
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channelComprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builderEsplora la funzionalitàWhatsApp
Prova l'esercitazione e ottieni un brief di implementazione