Sign inGet started

Cartões de contato do WhatsApp

Uma mensagem de cartão de contato compartilha um ou mais contatos: um nome que o destinatário vê no cartão e uma visualização de perfil que ele abre a partir dele, contendo números de telefone, e-mails, sites, endereços, um empregador e uma data de aniversário. Use-a para entregar a um cliente o número de um colega, de um entregador ou o seu próprio, em vez de colar dígitos em um texto que ele precisará redigitar.

Enviar um cartão de contato

contact_cards é um array. Cada cartão precisa de um name, e esse nome precisa de formatted_name mais pelo menos uma outra 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);
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.
A forma completa adiciona um empregador, uma data de aniversário e os outros arrays de detalhes de contato:
Exemplo de código
{
  "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"
        }
      ]
    }
  ]
}
Todo rótulo type, seja em um telefone, um e-mail, um site ou um endereço, é texto livre que você escreve, enviado exatamente como você escreveu e exibido ao lado do valor na visualização de perfil do destinatário. O WhatsApp não define vocabulário para esses rótulos, então Mobile, Landline, Pop-Up e Work (old) são todos igualmente válidos.

O que dá a um cartão um botão

Um número de telefone escrito em E.164, com o código do país e o + inicial, dá a esse cartão um botão que abre um chat do WhatsApp com o número. Um número que o Bird não consegue ler como E.164 ainda é exibido no cartão, exatamente como você o escreveu; ele apenas não ganha um botão.
Isso inclui um número escrito sem o + inicial. O Bird não vai adicionar um para você: um número em formato nacional de um país pode ser interpretado como um número válido em outro quando um + é adicionado, o que apontaria o botão para um desconhecido. Recusar-se a adivinhar custa um botão; adivinhar errado custa ao destinatário um chat com a pessoa errada.
Um cartão sem nenhum número de telefone é exibido sem botão de chat e só pode ser salvo na agenda de contatos.

Limites

CampoLimiteAplicado por
contact_cards1 a 5 cartões por mensagemBird, no aceite (422)
nameobrigatório; formatted_name mais uma outra parte do nomeBird, no aceite (422)
formatted_name, first_name, middle_name, last_nameaté 256 caracteresBird, no aceite (422)
prefix, suffixaté 64 caracteresBird, no aceite (422)
birthdayopcional, YYYY-MM-DD, e uma data que o calendário comportaBird, no aceite (422)
phone_numbers, emails, urls, addressesaté 10 entradas cadaBird, no aceite (422)
phone_numberaté 32 caracteresBird, no aceite (422)
emailaté 254 caracteresBird, no aceite (422)
urlaté 2.048 caracteres, não validado como URLBird, no aceite (422)
type em qualquer telefone, e-mail, site ou endereçoaté 64 caracteres de texto livreBird, no aceite (422)
company, department, titleaté 128 caracteresBird, no aceite (422)
street, city, state, zip, country, country_codeaté 128 caracteresBird, no aceite (422)
O limite de cinco cartões é do Bird, e está deliberadamente muito abaixo do que o WhatsApp aceita. A própria descrição publicada do API do WhatsApp declara cinco, sua documentação recomenda menos por motivos de usabilidade e feedback negativo, e uma mensagem que abre como "Contact 1 and 256 other contacts" é um vetor de spam antes de ser um recurso. Aumentar o limite depois seria uma mudança aditiva, então pergunte se cinco é pouco para o que você está construindo.
Todo limite de comprimento acima também é do Bird. O WhatsApp não aplica nenhum que valha a pena mencionar, e seu cliente não compensa: um type de 500 caracteres é exibido como dez linhas de uma mesma letra repetida, e um url de 4.000 caracteres é descartado silenciosamente, deixando a visualização de perfil em branco. Um 422 nomeando o campo infrator é melhor do que um cartão que o destinatário não consegue ler.

Duas regras que o schema não consegue expressar

Um nome precisa de uma segunda parte. formatted_name sozinho é recusado com um 422 E15061 WhatsAppContactNameIncomplete, nomeando contact_cards.<n>.name. Qualquer um entre prefix, first_name, middle_name, last_name ou suffix o satisfaz, mas um valor em branco ou contendo apenas espaços não conta, e um org não o resgata. Esse é um requisito do próprio WhatsApp, não documentado em nenhum lugar na sua referência; o Bird o captura no aceite para que você receba um erro acionável em vez de uma falha assíncrona.
Uma data de aniversário precisa ser uma data real. birthday é YYYY-MM-DD; qualquer outro formato, e qualquer data que o calendário não comporta, como 2026-02-30, é recusado com um 422 E15062 WhatsAppContactBirthdayInvalid. O próprio WhatsApp aceita 2026-02-30 e o exibe ao destinatário, o que parece um bug nos seus dados.

Lendo um cartão de volta

Um cartão que você enviou é lido de volta no mesmo campo contact_cards que um cartão recebido usa, pela lista de mensagens ou por GET /v1/whatsapp/messages/{id}:
Exemplo de código
{
  "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 estão ausentes em um cartão que você enviou: o WhatsApp define ambos em um cartão que um contato compartilhou. Um rótulo type que você enviou é lido de volta exatamente como escrito, enquanto um rótulo em um cartão recebido fica em minúsculas. Consulte Recebendo cartões de contato do WhatsApp para o lado de entrada.

Casos especiais

  • A janela de atendimento ao cliente precisa estar aberta. O envio de um cartão de contato é uma mensagem de serviço, entregável apenas dentro de uma janela aberta; consulte a janela de atendimento ao cliente do hub.
  • Não existe wa_id para enviar. O WhatsApp identifica o contato de um cartão por um ID de conta; o Bird o deriva de cada phone_number E.164 em vez de aceitar um, então o botão em um cartão nunca pode apontar para algo diferente dos dígitos impressos nele.
  • vcard é somente leitura. O WhatsApp o gera para um cartão que um contato compartilhou. Não há como enviar um cartão como texto vCard bruto.
  • Um cartão não é um registro de contato. Enviar um compartilha detalhes em uma mensagem; ele não cria nada no seu espaço de trabalho, e o destinatário salvá-lo é uma ação dele, invisível para você.

Próximos passos