Solicitações de informações de contato no WhatsApp
Uma solicitação de informações de contato coloca um botão sob uma mensagem do WhatsApp pedindo ao destinatário que compartilhe um número de telefone. Use quando você precisa de um número para entrar em contato com alguém, como uma ligação de retorno ou a confirmação de uma reserva, em vez de um endereço salvo. Para solicitar uma localização, use solicitações de localização.
Enviar uma solicitação de informações de contato
Defina interactive.type como request_contact_info, com um body_text e nada mais. WhatsApp renderiza o próprio botão, então não há nada para rotulá-lo:
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 é obrigatório em toda mensagem de serviço: um número que o seu espaço de trabalho possui, não um gerenciado pelo Bird. Este tipo não nomeia nenhum campo próprio, e o schema proíbe header, footer_text e todos os campos de outros tipos (buttons, list, cta_url, cards) explicitamente, então body_text é a mensagem inteira, limitada a 1.024 caracteres. A Meta não define limite de tamanho do corpo para este tipo; Bird aplica o limite de 1.024 caracteres que todo outro tipo interativo, exceto menu de lista, carrega.
in_reply_to_message_id ainda funciona neste tipo, para citar uma mensagem anterior na mesma conversa. Veja no hub citar uma mensagem para correlacionar uma resposta para entender como a resolução funciona e o que ela pode perder.
Lendo o contato compartilhado
Um toque não produz um interactive_reply. Ele chega como uma mensagem de entrada comum carregando um array contact_cards:
Exemplo de código
{
"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 é um array, e uma mensagem contacts que não carregava nenhum cartão retorna como [] em vez de como um campo ausente. O mesmo campo carrega um cartão que você envia, então um cartão que responde a essa solicitação é distinguido por origin, não pelo campo em que chega. Verificar origin é obrigatório antes de tratar um cartão como sua resposta. origin é contact_request quando o cartão responde a essa solicitação, ou other quando o contato compartilhou um cartão espontaneamente, o que pode nomear um terceiro completamente e não o próprio contato. Um toque carrega apenas phone_numbers[].{phone_number, type} e omite vcard; o objeto de contato completo, com name, org, birthday e o restante, chega apenas em origin: "other". Você vê essa resposta pela lista de mensagens ou por GET /v1/whatsapp/messages/{id}; veja no hub ler uma resposta para o caminho completo.
Correlacionando a resposta com a pergunta
Diferente de uma solicitação de localização, a Meta não coloca context na resposta deste tipo, então in_reply_to_message_id é omitido em vez de resolvido. Correlacione por from junto com um envio recente seu, ou aceite que não é possível. Duas solicitações pendentes para o mesmo contato são indistinguíveis: nada na resposta indica qual solicitação ela responde, então um espaço de trabalho que envia uma segunda solicitação de informações de contato antes de a primeira ser respondida não consegue identificar qual cartão corresponde a qual.
Este é o contraste deliberado com solicitações de localização: a resposta daquele tipo carrega o próprio context da Meta, então in_reply_to_message_id é resolvido e o mecanismo de citar uma mensagem para correlacionar uma resposta do hub vincula a resposta de volta automaticamente. A resposta de uma solicitação de informações de contato não tem esse mecanismo para se apoiar.
Solicitando dentro de um template
A mensagem interativa request_contact_info é a contraparte de formato livre do botão de template REQUEST_CONTACT_INFO, que solicita o mesmo cartão de contato mas pode alcançar um destinatário cuja janela de atendimento ao cliente está fechada. Use a mensagem interativa quando o destinatário entrou em contato recentemente e você quer a solicitação redigida para esta conversa; use o botão de template quando a janela estiver fechada, ou quando a solicitação acompanha uma mensagem que você já envia como template. Veja templates WhatsApp para envio com template.
Pontos de atenção
- A janela de atendimento ao cliente precisa estar aberta. Uma solicitação de informações de contato é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; veja no hub a janela de atendimento ao cliente. A verificação da janela falha como aberta, então um 202 não é prova de que a janela estava de fato aberta no momento do envio.
- from deve ser um número que o seu espaço de trabalho possui, e a janela que precisa estar aberta é vinculada a esse número, não ao seu espaço de trabalho como um todo.
- A resposta não pode ser vinculada à solicitação por id. Nenhum context do lado da Meta significa que in_reply_to_message_id é omitido na resposta; correlacione por from junto com um envio recente seu.
- Uma recusa é silenciosa. WhatsApp mostra ao destinatário uma tela de compartilhamento, e dispensá-la não produz nenhuma mensagem nem nenhum webhook. A ausência de uma mensagem contact_cards é o único sinal, então qualquer fluxo que espera uma resposta precisa de seu próprio timeout em vez de um evento de recusa para monitorar.
- Sem header, sem footer e sem rótulo de botão. O schema proíbe header e footer_text neste tipo explicitamente, e não há campo para rotular o botão. Tudo que o destinatário lê precisa estar em body_text.
- O número divulgado não é garantido como sendo o mesmo de onde o contato conversa. A Meta alerta que o ID e o número de telefone de um usuário podem nem sempre coincidir, então não presuma que o número compartilhado é igual a from.phone_number. Também não é garantido que esteja em E.164: Bird normaliza quando é possível analisar e repassa literalmente quando não é.
- A resposta é uma mensagem contact_cards, não um interactive_reply. Uma integração que monitora apenas interactive_reply para um toque vai perder este tipo completamente, assim como uma que monitora apenas location de entrada para o outro tipo de solicitação.
Tudo que o schema pode expressar aqui, um body_text muito longo, um header, um footer_text, ou qualquer um de buttons, list, cta_url, cards, é uma falha simples de validação da solicitação sem código de catálogo. Uma citação que não resolve falha a solicitação antes de qualquer coisa ser criada ou cobrada: 404 E15071 quando o id não nomeia nenhuma mensagem que este espaço de trabalho possui, 422 E15072 quando nomeia uma que não pode ser citada. Veja no hub os erros para a tabela completa de erros interativos e Envio de mensagens WhatsApp para os erros que qualquer envio WhatsApp pode encontrar.
Próximos passos
- Mensagens interativas WhatsApp: o que todos os seis tipos interativos compartilham
- Solicitações de localização: solicite uma localização em vez de um número de telefone
- Templates WhatsApp: alcance um destinatário cuja janela de atendimento ao cliente está fechada
- Envio de mensagens WhatsApp: a estrutura da solicitação, o modelo 202 e retentativas seguras
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação