Demandes de coordonnées WhatsApp
Une demande de coordonnées place un bouton sous un message WhatsApp qui invite le destinataire à partager un numéro de téléphone. Utilisez-la lorsque vous avez besoin d'un numéro pour joindre quelqu'un, par exemple pour un rappel ou une confirmation de réservation, et non d'une adresse enregistrée. Pour demander une localisation, utilisez les demandes de localisation.
Envoyer une demande de coordonnées
Définissez interactive.type à request_contact_info, avec un body_text et rien d'autre. WhatsApp affiche le bouton lui-même, il n'y a donc rien à lui attribuer comme libellé :
const msg = await bird.whatsapp.send({
to: "+16505551234",
from: "+13124495648",
interactive: {
type: "request_contact_info",
body_text:
"To confirm your booking we need a number to reach you on. Tap below to share yours.",
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+16505551234",
from_="+13124495648",
interactive={
"type": "request_contact_info",
"body_text": "To confirm your booking we need a number to reach you on. Tap below to share yours.",
},
)
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",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "request_contact_info",
BodyText: "To confirm your booking we need a number to reach you on. Tap below to share yours.",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('request_contact_info')
->setBodyText('To confirm your booking we need a number to reach you on. Tap below to share yours.');
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive '{"body_text":"To confirm your booking we need a number to reach you on. Tap below to share yours.","type":"request_contact_info"}' \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "To confirm your booking we need a number to reach you on. Tap below to share yours.",
"type": "request_contact_info"
},
"to": "+16505551234"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "+16505551234",
"from": "+13124495648",
"interactive": {
"type": "request_contact_info",
"body_text": "To confirm your booking we need a number to reach you on. Tap below to share yours."
}
}'from est obligatoire sur chaque message de service : un numéro appartenant à votre espace de travail, pas un numéro géré par Bird. Ce type ne déclare aucun champ propre, et le schéma interdit header, footer_text, ainsi que tous les champs des autres types (buttons, list, cta_url, cards), si bien que body_text constitue l'intégralité du message, plafonné à 1 024 caractères. Meta ne spécifie aucune limite de longueur du corps pour ce type ; Bird applique la limite de 1 024 caractères que portent tous les autres types interactifs sauf un menu liste.
in_reply_to_message_id fonctionne toujours avec ce type, pour citer un message antérieur dans la même conversation. Consultez la section citer un message pour corréler une réponse du hub pour comprendre comment la résolution fonctionne et ce qu'elle peut manquer.
Lire le contact partagé
Un appui ne produit pas de interactive_reply. Il arrive sous forme de message entrant ordinaire portant un tableau contact_cards :
Exemple de code
{
"id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
"direction": "inbound",
"from": { "phone_number": "+16505551234", "bsuid": "US.13491208655302741918" },
"to": { "phone_number": "+13124495648" },
"status": "received",
"contact_cards": [
{
"origin": "contact_request",
"phone_numbers": [{ "phone_number": "+14155550829", "type": "cell" }]
}
],
"created_at": "2026-08-26T10:00:00Z"
}contact_cards est un tableau, et un message contacts sans fiche renvoie [] plutôt qu'un champ absent. Le même champ porte une fiche que vous envoyez, de sorte qu'une fiche répondant à cette demande se distingue par origin, et non par le champ sur lequel elle arrive. Vérifier origin est obligatoire avant de traiter une fiche comme votre réponse. origin vaut contact_request lorsque la fiche répond à cette demande, ou other lorsque le contact a partagé une fiche spontanément, laquelle peut désigner un tiers et non le contact lui-même. Un appui ne porte que phone_numbers[].{phone_number, type} et omet vcard ; l'objet contact complet, avec name, org, birthday et le reste, n'arrive que sur origin: "other". Vous consultez cette réponse via la liste de messages ou GET /v1/whatsapp/messages/{id} ; voir la section lire une réponse du hub pour le parcours complet.
Corréler la réponse avec la demande
Contrairement à une demande de localisation, Meta ne place aucun context sur la réponse de ce type, si bien que in_reply_to_message_id est omis au lieu d'être résolu. Corrélez sur from combiné à un envoi récent de votre part, ou acceptez que la corrélation est impossible. Deux demandes en attente vers le même contact sont indiscernables : rien dans la réponse n'indique à quelle demande elle correspond, de sorte qu'un espace de travail qui envoie une seconde demande de coordonnées avant d'avoir reçu la réponse à la première ne peut pas distinguer quelle fiche répond à quelle demande.
C'est le contraste délibéré avec les demandes de localisation : la réponse de ce type porte le context propre à Meta, de sorte que in_reply_to_message_id est résolu et le mécanisme citer un message pour corréler une réponse du hub rattache automatiquement la réponse à la demande. La réponse à une demande de coordonnées ne dispose d'aucun mécanisme équivalent.
Demander via un modèle à la place
Le message interactif request_contact_info est l'équivalent libre du bouton de modèle REQUEST_CONTACT_INFO, qui demande la même fiche de contact mais peut atteindre un destinataire dont la fenêtre de service client est fermée. Utilisez le message interactif lorsque le destinataire vous a écrit récemment et que vous souhaitez formuler la demande pour cette conversation ; utilisez le bouton de modèle lorsque la fenêtre est fermée, ou lorsque la demande accompagne un message que vous envoyez déjà sous forme de modèle. Consultez modèles WhatsApp pour l'envoi via un modèle.
Points d'attention
- La fenêtre de service client doit être ouverte. Une demande de coordonnées est un message de service, livrable uniquement dans une fenêtre ouverte ; voir la section fenêtre de service client du hub. La vérification de la fenêtre échoue en mode ouvert, donc un 202 ne prouve pas que la fenêtre était réellement ouverte au moment de l'envoi.
- from doit être un numéro appartenant à votre espace de travail, et la fenêtre qu'il nécessite est liée à ce numéro, pas à votre espace de travail dans son ensemble.
- La réponse ne peut pas être rattachée à la demande par identifiant. L'absence de context côté Meta signifie que in_reply_to_message_id est omis sur la réponse ; corrélez sur from combiné à un envoi récent de votre part.
- Un refus est silencieux. WhatsApp affiche au destinataire une feuille de partage, et la fermer ne produit ni message ni webhook. L'absence d'un message contact_cards est le seul signal, de sorte que tout flux attendant une réponse a besoin de son propre délai d'expiration plutôt que d'un événement de refus à surveiller.
- Pas d'en-tête, pas de pied de page et pas de libellé de bouton. Le schéma interdit header et footer_text sur ce type, et il n'y a aucun champ pour libeller le bouton. Tout ce que le destinataire lit doit figurer dans body_text.
- Le numéro communiqué n'est pas garanti être celui depuis lequel le contact écrit. Meta avertit que l'identifiant d'un utilisateur et son numéro de téléphone ne correspondent pas toujours, donc ne supposez pas que le numéro partagé est égal à from.phone_number. Il n'est pas non plus garanti au format E.164 : Bird le normalise lorsqu'il est analysable et le transmet tel quel dans le cas contraire.
- La réponse est un message contact_cards, pas un interactive_reply. Une intégration qui ne surveille que interactive_reply pour un appui manquera entièrement ce type, tout comme une intégration qui ne surveille que les location entrants pour l'autre type de demande.
Tout ce que le schéma peut exprimer ici, un body_text trop long, un header, un footer_text, ou l'un quelconque de buttons, list, cta_url, cards, est un simple échec de validation de la requête sans code catalogue. Une citation qui ne se résout pas fait échouer la requête avant toute création ou facturation : 404 E15071 lorsque l'identifiant ne désigne aucun message détenu par cet espace de travail, 422 E15072 lorsqu'il désigne un message qui ne peut pas être cité. Consultez la section erreurs du hub pour la table complète des erreurs interactives et Envoyer des messages WhatsApp pour les erreurs que tout envoi WhatsApp peut rencontrer.
Étapes suivantes
- Messages interactifs WhatsApp : ce que les six types interactifs ont en commun
- Demandes de localisation : demander une localisation au lieu d'un numéro de téléphone
- Modèles WhatsApp : atteindre un destinataire dont la fenêtre de service client est fermée
- 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