Mensagem de Contato

O tipo CONTACT_MESSAGE permite enviar um cartão de contato (vCard) para o destinatário. O contato aparecerá como um cartão interativo que o destinatário pode salvar na agenda.

Payload

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "CONTACT_MESSAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "displayName": "Maria Silva",
    "vCard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;Maria;;;\nFN:Maria Silva\nTEL;type=CELL;waid=5511988887777:+55 11 98888-7777\nEND:VCARD"
  }
}

Campos

string

required

Deve ser "CONTACT_MESSAGE".

Address

required

Endereço do destinatário. Veja formatos de endereço.

string

required

Nome de exibição do contato. Aparece como título do cartão de contato.

string

required

Conteúdo do cartão de contato no formato vCard 3.0. Deve conter pelo menos nome e um telefone.

Formato vCard

O vCard é um formato padrão para troca de informações de contato. Abaixo os campos mais comuns:

BEGIN:VCARD
VERSION:3.0
N:Sobrenome;Nome;;;
FN:Nome Completo
ORG:Nome da Empresa
TITLE:Cargo
TEL;type=CELL;waid=5511999999999:+55 11 99999-9999
TEL;type=WORK:+55 11 3333-4444
EMAIL;type=WORK:email@empresa.com
ADR;type=WORK:;;Av. Paulista, 1578;Sao Paulo;SP;01310-200;Brasil
URL:https://www.empresa.com
END:VCARD

O campo waid no telefone é específico do WhatsApp e indica o número do WhatsApp associado ao contato. Isso permite que o destinatário inicie uma conversa diretamente pelo cartão.

Exemplos

Contato simples

curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua-api-key-aqui" \
  -d '{
    "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "content": {
      "type": "CONTACT_MESSAGE",
      "to": {
        "type": "WHATSAPP",
        "number": "5511999999999"
      },
      "displayName": "Suporte MessageFy",
      "vCard": "BEGIN:VCARD\nVERSION:3.0\nN:MessageFy;Suporte;;;\nFN:Suporte MessageFy\nORG:MessageFy\nTEL;type=CELL;waid=5511900001111:+55 11 90000-1111\nEMAIL;type=WORK:suporte@messagefy.io\nURL:https://messagefy.io\nEND:VCARD"
    }
  }'

import requests

vcard = """BEGIN:VCARD
VERSION:3.0
N:MessageFy;Suporte;;;
FN:Suporte MessageFy
ORG:MessageFy
TEL;type=CELL;waid=5511900001111:+55 11 90000-1111
EMAIL;type=WORK:suporte@messagefy.io
URL:https://messagefy.io
END:VCARD"""

response = requests.post(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui"
    },
    json={
        "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "content": {
            "type": "CONTACT_MESSAGE",
            "to": {
                "type": "WHATSAPP",
                "number": "5511999999999"
            },
            "displayName": "Suporte MessageFy",
            "vCard": vcard
        }
    }
)
print(response.json())

const vcard = [
  "BEGIN:VCARD",
  "VERSION:3.0",
  "N:MessageFy;Suporte;;;",
  "FN:Suporte MessageFy",
  "ORG:MessageFy",
  "TEL;type=CELL;waid=5511900001111:+55 11 90000-1111",
  "EMAIL;type=WORK:suporte@messagefy.io",
  "URL:https://messagefy.io",
  "END:VCARD",
].join("\n");

const response = await fetch(
  "https://api-dev.messagefy.io/api/v1/message/SendMessage",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "sua-api-key-aqui",
    },
    body: JSON.stringify({
      channelId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      content: {
        type: "CONTACT_MESSAGE",
        to: {
          type: "WHATSAPP",
          number: "5511999999999",
        },
        displayName: "Suporte MessageFy",
        vCard: vcard,
      },
    }),
  }
);
const data = await response.json();
console.log(data);

Contato completo com endereço

{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "CONTACT_MESSAGE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "displayName": "Dr. Carlos Mendes",
    "vCard": "BEGIN:VCARD\nVERSION:3.0\nN:Mendes;Carlos;Dr.;;\nFN:Dr. Carlos Mendes\nORG:Clinica Saude Total\nTITLE:Medico Cardiologista\nTEL;type=CELL;waid=5511977776666:+55 11 97777-6666\nTEL;type=WORK:+55 11 3456-7890\nEMAIL;type=WORK:carlos.mendes@clinicasaudetotal.com.br\nADR;type=WORK:;;Rua Augusta, 2530, sala 42;Sao Paulo;SP;01412-100;Brasil\nURL:https://clinicasaudetotal.com.br\nEND:VCARD"
  }
}

Use \n para separar as linhas do vCard no JSON. Cada campo do vCard deve estar em uma linha separada.

O displayName deve corresponder ao FN (Full Name) do vCard para consistência na exibição. Caso sejam diferentes, o WhatsApp pode exibir o FN do vCard.

Resposta

{
  "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Recebimento

Quando um contato é compartilhado com o seu canal, a plataforma entrega um webhook com content.type igual a CONTACT_MESSAGE. O contato recebido usa exatamente os mesmos campos do envio: displayName e vCard.

Para o envelope completo do webhook (packageId, channelId, correlationId, timestamp, providerMetadata, echoMessage) e a configuração do canal de recebimento, veja Recebendo Eventos.

Exemplo de webhook recebido

{
  "packageId": "019a1234-5678-7abc-def0-123456789abc",
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": null,
  "content": {
    "type": "CONTACT_MESSAGE",
    "from": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777",
      "name": "Joao Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511900001111@s.whatsapp.net",
      "number": "5511900001111"
    },
    "messageId": "20CFBA298FAB68AA75D3B369EDB5C805",
    "isFromMe": false,
    "isGroupMessage": false,
    "displayName": "Maria Silva",
    "vCard": "BEGIN:VCARD\nVERSION:3.0\nN:Silva;Maria;;;\nFN:Maria Silva\nTEL;type=CELL;waid=5511977776666:+55 11 97777-6666\nEND:VCARD",
    "timestamp": "2025-12-01T14:30:00.000+00:00"
  },
  "timestamp": "2025-12-01T14:30:00.100+00:00",
  "providerMetadata": null
}

Campos recebidos

string

Sempre "CONTACT_MESSAGE".

Address

Endereço de quem compartilhou o contato. Para WhatsApp inclui jid, number e name (e opcionalmente lid). Veja formatos de endereço.

Address

Endereço do canal/chat que recebeu a mensagem.

string

Identificador da mensagem no provedor. Guarde-o para responder ou citar posteriormente.

string

Nome de exibição do contato compartilhado.

string

Conteúdo do cartão de contato no formato vCard 3.0, com nome, telefone(s) e demais informações.

boolean

true quando o contato foi compartilhado em um grupo.

boolean

true quando a mensagem foi enviada pelo próprio canal (eco).

boolean

true se a mensagem foi enviada para uma lista de transmissão (broadcast list).

boolean

true se a mensagem foi enviada para um grupo de avisos da comunidade.

boolean

true se a mensagem foi enviada para o grupo de avisos da comunidade.

true se a mensagem foi enviada para um canal/newsletter.

DateTimeOffset

Momento em que a mensagem foi recebida pelo provedor.

Os campos comuns a toda mensagem recebida (isForwarded, isStatusMessage, isHistoryMessage, quotedMessage, metaReferralAds) também podem estar presentes. Veja o envelope comum de mensagens.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Mensagem de Contato

Mensagem de Contato

Payload

Campos

Formato vCard

Exemplos

Contato simples

Contato completo com endereço

Resposta

Recebimento

Exemplo de webhook recebido

Campos recebidos

​Mensagem de Contato

​Payload

​Campos

​Formato vCard

​Exemplos

​Contato simples

​Contato completo com endereço

​Resposta

​Recebimento

​Exemplo de webhook recebido

​Campos recebidos

Mensagem de Contato

Payload

Campos

Formato vCard

Exemplos

Contato simples

Contato completo com endereço

Resposta

Recebimento

Exemplo de webhook recebido

Campos recebidos