Solicitar compartilhamento do contato

Envie uma mensagem com o botão nativo de compartilhar contato. A pessoa escolhe se deseja compartilhar seu telefone com a empresa.

Rotas e autenticação

Use o token de API da empresa, criado em Configurações → Integrações → Tokens de API. Tokens com escopos restritos precisam do escopo waba, inclusive para a rota unificada. Tokens legados sem escopos continuam permitidos. O CHANNEL_UUID deve pertencer à mesma empresa do token.

Exemplo WABA: solicitar pelo telefone

Substitua CHANNEL_UUID, SEU_API_TOKEN e o telefone pelos dados da sua integração. Envie o número com código do país, somente dígitos. O texto deve conter entre 1 e 1024 caracteres.

curl --request POST 'https://backend.sendeasy.app/api/v1/channels/CHANNEL_UUID/request-contact' \
  --header 'Authorization: Bearer SEU_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"to":"5511999999999","body":"Compartilhe seu contato para continuarmos o atendimento."}'

WABA: contato sem telefone

Quando você receber apenas um BSUID, passe esse identificador opaco em to, sem alterá-lo. Username é um nome de apresentação e não substitui o destinatário. A SendEasy envia uma mensagem nativa request_contact_info para a Meta. A disponibilidade e as regras de envio dependem da conta e do provedor.

{
  "to": "BR.Example123",
  "body": "Compartilhe seu contato para continuarmos o atendimento."
}

ZuckZapGo: telefone ou LID

Para um canal WhatsApp com provedor ZuckZapGo/WuzAPI, use a mesma rota unificada e inclua id, obrigatório com 1 a 128 caracteres alfanuméricos. O destinatário pode ser telefone, JID de telefone ou LID completo. BSUID, username, grupos e JID com sufixo de dispositivo não são aceitos nessa integração.

{
  "to": "123456789012345@lid",
  "body": "Compartilhe seu contato para continuarmos o atendimento.",
  "id": "ContactRequest202610060001"
}

Resposta e confirmação de entrega

HTTP 200 retorna a resposta do provedor. No WABA, messages[0].id identifica a mensagem aceita. Aceitação não confirma entrega: acompanhe os eventos statuses da Meta ou consulte a rota de status abaixo. O envio por esse endpoint não cria, por si só, uma mensagem de saída ou um ticket no inbox WABA.

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.EXAMPLE" }]
}

curl 'https://backend.sendeasy.app/api/v1/waba/CHANNEL_UUID/messages/MESSAGE_ID/status' \
  --header 'Authorization: Bearer SEU_API_TOKEN'

Quando a pessoa compartilhar o contato

O compartilhamento entra no fluxo normal de mensagens e o payload original é preservado no encaminhamento de webhooks. Na API oficial, o cartão tem origin: "contact_request"; o telefone vem de contacts[].phones[].wa_id. Na ZuckZapGo, o evento Message tem contactMessage.isSelfContact: true; o vCard contém a identidade compartilhada. A correlação é pela conversa e fica restrita à empresa e canal. Um cartão comum de terceiros não deve substituir a identidade do remetente.

Erros e novas tentativas

O ID estável e a idempotência descritos aqui se aplicam à ZuckZapGo. Reutilize o mesmo id e payload quando uma nova tentativa for permitida. A SendEasy não faz retry automático. No WABA, incluir id não adiciona idempotência ao envio.

Outros erros são retornados com o status HTTP do provedor e seus detalhes em provider. Confirme que a conta permite esse tipo de mensagem. Uma falha documentada pelo provedor como anterior ao despacho pode permitir nova tentativa com o mesmo ID e payload.

Veja também API Pública e WABA API.