Enviar contato (vCard) pelo WhatsApp via API: cartão do vendedor, especialista e filiais

Pela API não oficial do WhatsApp você envia um cartão de contato nativo com POST /message/contact, vários de uma vez com POST /message/contacts, responde a uma mensagem específica com um cartão via POST /message/{id}/contact e ainda pede o telefone do cliente com POST /message/request-phone. O cliente recebe o vCard do jeito que conhece: com botão para conversar e para salvar na agenda.

Parece um recurso pequeno, mas resolve um momento que aparece em quase todo atendimento: "fala com o fulano". Em vez de copiar e colar um número no meio do texto — que o cliente precisa selecionar, copiar e salvar à mão —, o bot ou o atendente manda um cartão, e o próximo passo fica a um toque.

A camada não oficial não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Enviar um contato

O corpo é direto: quem recebe e os dados do cartão.

curl -X POST "https://us.api-wa.me/SUA_KEY/message/contact" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "contact": {
      "fullName": "Mariana Souza — Financeiro",
      "organization": "Loja Exemplo",
      "phoneNumber": "5511988887777"
    }
  }'

• fullName e phoneNumber são obrigatórios.
• organization é opcional e aparece no cartão — ótimo para deixar claro de onde é o contato.
• phoneNumber vai no formato internacional, só dígitos (país + DDD + número).

Uma dica de nome: coloque o papel junto do nome ("Mariana Souza — Financeiro"). Quando o cliente salvar, vai lembrar por que salvou.

Enviar vários contatos de uma vez

Para listas curtas de contatos relacionados — filiais, plantão, equipe de uma obra —, um envio só:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/contacts" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "displayName": "Nossas lojas",
    "contacts": [
      { "fullName": "Loja Centro", "phoneNumber": "5511977776666", "organization": "Loja Exemplo" },
      { "fullName": "Loja Zona Sul", "phoneNumber": "5511966665555", "organization": "Loja Exemplo" },
      { "fullName": "Loja Guarulhos", "phoneNumber": "5511955554444", "organization": "Loja Exemplo" }
    ]
  }'

O displayName é o título do conjunto que o cliente vê na conversa. Mantenha a lista curta: três a cinco cartões são úteis; vinte viram uma lista telefônica que ninguém abre.

Responder com um contato, citando a pergunta

No atendimento, o contato quase sempre é resposta a uma pergunta ("quem cuida de nota fiscal?"). Enviar como resposta citada deixa isso claro no chat:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/ID_DA_MENSAGEM/contact" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "contact": {
      "fullName": "Carlos Lima — Notas fiscais",
      "organization": "Loja Exemplo",
      "phoneNumber": "5511944443333"
    }
  }'

O ID_DA_MENSAGEM é o id da mensagem do cliente que chegou no webhook. Os outros tipos de resposta citada estão em responder mensagem citada pela API.

Pedir o telefone do cliente

O caminho inverso também existe. Às vezes a conversa chega por um identificador que não é o telefone — o WhatsApp usa cada vez mais identificadores internos, os LIDs — e você precisa do número para cadastrar, emitir nota ou combinar entrega:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/request-phone" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999" }'

O contato recebe um pedido nativo para compartilhar o número. É consentido por definição: ele decide se compartilha. Se o que você tem é um LID e quer o telefone sem incomodar o cliente, há também a resolução em lote pela API — o assunto completo está em LID no WhatsApp: o que é e como resolver o número.

Três fluxos que funcionam

1. Bot que encaminha para o especialista

O bot resolve o básico, mas certas perguntas precisam de um humano específico. Em vez de "aguarde que alguém vai te chamar", o bot entrega o contato certo:

const BASE = 'https://us.api-wa.me/SUA_KEY';

const ESPECIALISTAS = {
  financeiro: { fullName: 'Mariana Souza — Financeiro', phoneNumber: '5511988887777' },
  tecnico:    { fullName: 'Paulo Reis — Suporte técnico', phoneNumber: '5511933332222' },
};

async function post(path, body) {
  const res = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`${path} → ${res.status}`);
  return res.json();
}

async function encaminhar(cliente, area, idMensagem) {
  const esp = ESPECIALISTAS[area];
  if (!esp) return;

  await post('/message/text', {
    to: cliente,
    text: 'Esse assunto quem resolve é a nossa especialista. Pode chamar direto por aqui:',
  });

  await post(`/message/${idMensagem}/contact`, {
    to: cliente,
    contact: { ...esp, organization: 'Loja Exemplo' },
  });
}

Funciona bem quando o especialista atende pelo próprio WhatsApp. Se toda a equipe atende no mesmo número, o caminho é outro: vários atendentes no mesmo número.

2. Cartão do vendedor depois da compra

Cliente fechou pelo site? Mande o cartão do consultor responsável junto da confirmação do pedido. O cliente salva, e a próxima compra já começa numa conversa com nome e rosto. Combina com notificações de pedido.

3. "Qual a loja mais perto?"

O cliente pergunta, o bot responde com os cartões das filiais da região via /message/contacts — ou, melhor ainda, pede a localização dele e manda só a mais próxima. O pedido de localização está em localização pela API do WhatsApp.

Contatos em grupo

O campo to também aceita um grupo, no formato [email protected]. Isso ajuda em grupos de trabalho e de clientes: o grupo de uma obra recebe o cartão do engenheiro responsável, o grupo de uma turma recebe o contato da secretaria, o grupo de suporte de um cliente corporativo recebe o plantão da semana. Como fica fixo no histórico do grupo, todo mundo encontra depois — e, se o grupo tem muita troca, vale fixar a mensagem com o cartão para ela não se perder.

Boas práticas

• Contato é resposta, não campanha. Envie quando o cliente precisa daquele contato, dentro de uma conversa. Cartão disparado para uma lista de desconhecidos é spam, e a WAME não apoia spam.
• Confira o número do cartão. Um cartão com número errado manda o cliente para um estranho. Mantenha os contatos da equipe num cadastro único, não espalhados pelo código. Se quiser garantir, valide antes com verificar se o número tem WhatsApp.
• Avise antes. Um texto curto ("quem resolve isso é a Mariana, segue o contato") antes do cartão contextualiza. Lembre também que, para contato que nunca conversou com você, abrir com texto é o caminho natural antes de qualquer formato mais rico.
• Respeite quem está no cartão. Compartilhar o número de um funcionário exige que ele saiba e concorde — é dado pessoal dele.

E o risco de bloqueio?

Cartão de contato é um tipo de mensagem que as pessoas usam o tempo todo no app, e dentro de uma conversa em andamento não chama atenção de ninguém. Os envios já saem com "digitando..." e tempo humano, e a instância tem identidade de dispositivo própria. Para esse uso, a taxa de bloqueio é muito baixa quando o uso é o certo. O que derruba número é outra coisa — o panorama está em o que realmente derruba um número.

Conclusão

Enviar contato pela API não oficial do WhatsApp é trocar o "anota aí o número" por um cartão nativo que o cliente salva com um toque. /message/contact para um cartão, /message/contacts para um conjunto, /message/{id}/contact para responder citando a pergunta e /message/request-phone para pedir o número do cliente. Use dentro da conversa, no momento em que o contato resolve o problema, e o recurso vira atalho em vez de ruído. Os parâmetros completos estão na documentação, e os outros recursos da camada não oficial estão em vantagens da API não oficial.