Cartes de contact WhatsApp
Un message de carte de contact partage un ou plusieurs contacts : un nom que le destinataire voit sur la carte, et une vue de profil qu'il ouvre depuis celle-ci contenant des numéros de téléphone, des e-mails, des sites web, des adresses, un employeur et une date de naissance. Utilisez-le pour transmettre à un client le numéro d'un collègue, d'un coursier ou le vôtre, au lieu de coller des chiffres dans un texte qu'il devra ensuite retaper.
Envoyer une carte de contact
contact_cards est un tableau. Chaque carte nécessite un name, et ce nom nécessite formatted_name plus au moins une autre partie :
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 est requis sur chaque message de service : un numéro que votre espace de travail possède, pas un numéro géré par Bird.
La forme complète ajoute un employeur, une date de naissance et les autres tableaux de coordonnées :
Exemple de code
{
"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"
}
]
}
]
}Chaque libellé type, sur un téléphone, un e-mail, un site web ou une adresse, est du texte libre que vous rédigez, envoyé exactement tel que vous l'avez écrit, et affiché à côté de la valeur dans la vue de profil du destinataire. WhatsApp ne définit aucun vocabulaire pour ces libellés, donc Mobile, Landline, Pop-Up et Work (old) sont tous également valides.
Ce qui donne un bouton à une carte
Un numéro de téléphone écrit en E.164, avec son indicatif pays et son + initial, donne à cette carte un bouton qui ouvre une conversation WhatsApp avec le numéro. Un numéro que Bird ne peut pas lire comme E.164 s'affiche quand même sur la carte, exactement tel que vous l'avez écrit ; il ne génère simplement aucun bouton.
Cela inclut un numéro écrit sans son + initial. Bird n'en ajoutera pas pour vous : un numéro au format national d'un pays peut être interprété comme un numéro valide dans un autre pays une fois qu'un + y est ajouté, ce qui pointerait le bouton vers un inconnu. Renoncer à deviner coûte un bouton ; deviner faux coûte au destinataire une conversation avec la mauvaise personne.
Une carte ne contenant aucun numéro de téléphone s'affiche sans bouton de conversation et ne peut qu'être enregistrée dans un carnet d'adresses.
Limites
| Champ | Limite | Appliquée par |
|---|---|---|
| contact_cards | 1 à 5 cartes par message | Bird, à l'acceptation (422) |
| name | requis ; formatted_name plus une autre partie du nom | Bird, à l'acceptation (422) |
| formatted_name, first_name, middle_name, last_name | jusqu'à 256 caractères | Bird, à l'acceptation (422) |
| prefix, suffix | jusqu'à 64 caractères | Bird, à l'acceptation (422) |
| birthday | optionnel, YYYY-MM-DD, et une date que le calendrier reconnaît | Bird, à l'acceptation (422) |
| phone_numbers, emails, urls, addresses | jusqu'à 10 entrées chacun | Bird, à l'acceptation (422) |
| phone_number | jusqu'à 32 caractères | Bird, à l'acceptation (422) |
| jusqu'à 254 caractères | Bird, à l'acceptation (422) | |
| url | jusqu'à 2 048 caractères, non validé comme URL | Bird, à l'acceptation (422) |
| type sur tout téléphone, e-mail, site web ou adresse | jusqu'à 64 caractères de texte libre | Bird, à l'acceptation (422) |
| company, department, title | jusqu'à 128 caractères | Bird, à l'acceptation (422) |
| street, city, state, zip, country, country_code | jusqu'à 128 caractères | Bird, à l'acceptation (422) |
Le plafond de cinq cartes vient de Bird, et il est volontairement bien en dessous de ce que WhatsApp accepte. La description API publiée par WhatsApp déclare cinq, sa documentation recommande moins pour des raisons d'utilisabilité et de retours négatifs, et un message qui s'ouvre comme "Contact 1 and 256 other contacts" est un vecteur de spam avant d'être une fonctionnalité. Relever le plafond plus tard serait un changement additif, donc demandez si cinq est insuffisant pour ce que vous construisez.
Chaque limite de longueur ci-dessus vient aussi de Bird. WhatsApp n'en impose aucune digne de ce nom et son client ne compense pas : un type de 500 caractères s'affiche sur dix lignes d'une seule lettre répétée, et un url de 4 000 caractères est supprimé silencieusement, laissant la vue de profil vide. Une 422 nommant le champ fautif vaut mieux qu'une carte que le destinataire ne peut pas lire.
Deux règles que le schéma ne peut pas exprimer
Un nom nécessite une deuxième partie. formatted_name seul est refusé avec une 422 E15061 WhatsAppContactNameIncomplete, nommant contact_cards.<n>.name. N'importe lequel parmi prefix, first_name, middle_name, last_name ou suffix suffit, mais une valeur vide ou composée uniquement d'espaces ne compte pas, et un org ne le rattrape pas. C'est une exigence propre à WhatsApp, non documentée dans sa référence ; Bird l'intercepte à l'acceptation pour que vous obteniez une erreur exploitable au lieu d'un échec asynchrone.
Une date de naissance doit être une date réelle. birthday est YYYY-MM-DD ; toute autre forme, et toute date que le calendrier ne reconnaît pas, comme 2026-02-30, est refusée avec une 422 E15062 WhatsAppContactBirthdayInvalid. WhatsApp lui-même accepte 2026-02-30 et l'affiche au destinataire, ce qui ressemble à un bug dans vos données.
Relire une carte
Une carte que vous avez envoyée se relit sur le même champ contact_cards qu'utilise une carte entrante, via la liste de messages ou GET /v1/whatsapp/messages/{id} :
Exemple de code
{
"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 et vcard sont absents sur une carte que vous avez envoyée : WhatsApp les définit tous deux sur une carte partagée par un contact. Un libellé type que vous avez envoyé se relit exactement tel qu'écrit, tandis qu'un libellé sur une carte reçue est mis en minuscules. Consultez Recevoir des cartes de contact WhatsApp pour le côté entrant.
Cas particuliers
- La fenêtre de service client doit être ouverte. L'envoi d'une carte de contact est un message de service, livrable uniquement dans une fenêtre ouverte ; consultez la fenêtre de service client du hub.
- Il n'y a pas de wa_id à envoyer. WhatsApp identifie le contact d'une carte par un identifiant de compte ; Bird le dérive de chaque phone_number E.164 au lieu d'en accepter un, de sorte que le bouton d'une carte ne peut jamais pointer ailleurs que sur les chiffres qui y sont imprimés.
- vcard est en lecture seule. WhatsApp le génère pour une carte partagée par un contact. Il n'existe aucun moyen d'envoyer une carte sous forme de texte vCard brut.
- Une carte n'est pas un enregistrement de contact. En envoyer une partage des coordonnées dans un message ; cela ne crée rien dans votre espace de travail, et l'enregistrement par le destinataire est sa propre action, invisible pour vous.
Étapes suivantes
- Messages de service WhatsApp : la fenêtre de service client et le modèle partagé par tous les messages de service
- Demandes de coordonnées : demander son numéro à un contact au lieu d'en envoyer un
- Recevoir des messages WhatsApp : messages entrants, médias et le webhook whatsapp.received
- Envoyer des messages WhatsApp : l'enveloppe de requête, le modèle 202 et les réessais sûrs
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channelComprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builderExplorer la fonctionnalitéWhatsApp
Essayez la pratique et obtenez un guide d'implémentation