> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensagem de Contato

> Envie cartões de contato com informações de telefone, email e endereço via vCard

# 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

```json theme={null}
{
  "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

<ParamField body="content.type" type="string" required>
  Deve ser `"CONTACT_MESSAGE"`.
</ParamField>

<ParamField body="content.to" type="Address" required>
  Endereço do destinatário. Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ParamField>

<ParamField body="content.displayName" type="string" required>
  Nome de exibição do contato. Aparece como título do cartão de contato.
</ParamField>

<ParamField body="content.vCard" type="string" required>
  Conteúdo do cartão de contato no formato vCard 3.0. Deve conter pelo menos nome e um telefone.
</ParamField>

## 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
```

<Note>
  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.
</Note>

## Exemplos

### Contato simples

<CodeGroup>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</CodeGroup>

### Contato completo com endereço

```json theme={null}
{
  "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"
  }
}
```

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

<Warning>
  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.
</Warning>

## Resposta

```json theme={null}
{
  "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`.

<Note>
  Para o envelope completo do webhook (`packageId`, `channelId`, `correlationId`, `timestamp`, `providerMetadata`, `echoMessage`) e a configuração do canal de recebimento, veja [Recebendo Eventos](/recebendo-eventos).
</Note>

### Exemplo de webhook recebido

```json theme={null}
{
  "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

<ResponseField name="content.type" type="string">
  Sempre `"CONTACT_MESSAGE"`.
</ResponseField>

<ResponseField name="content.from" type="Address">
  Endereço de quem compartilhou o contato. Para WhatsApp inclui `jid`, `number` e `name` (e opcionalmente `lid`). Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ResponseField>

<ResponseField name="content.to" type="Address">
  Endereço do canal/chat que recebeu a mensagem.
</ResponseField>

<ResponseField name="content.messageId" type="string">
  Identificador da mensagem no provedor. Guarde-o para responder ou citar posteriormente.
</ResponseField>

<ResponseField name="content.displayName" type="string">
  Nome de exibição do contato compartilhado.
</ResponseField>

<ResponseField name="content.vCard" type="string">
  Conteúdo do cartão de contato no formato vCard 3.0, com nome, telefone(s) e demais informações.
</ResponseField>

<ResponseField name="content.isGroupMessage" type="boolean">
  `true` quando o contato foi compartilhado em um grupo.
</ResponseField>

<ResponseField name="content.isFromMe" type="boolean">
  `true` quando a mensagem foi enviada pelo próprio canal (eco).
</ResponseField>

<ResponseField name="content.isBroadcast" type="boolean">
  `true` se a mensagem foi enviada para uma lista de transmissão (broadcast list).
</ResponseField>

<ResponseField name="content.isAnnounceGroup" type="boolean">
  `true` se a mensagem foi enviada para um grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isCommunityNotices" type="boolean">
  `true` se a mensagem foi enviada para o grupo de avisos da comunidade.
</ResponseField>

<ResponseField name="content.isNewsletter" type="boolean">
  `true` se a mensagem foi enviada para um canal/newsletter.
</ResponseField>

<ResponseField name="content.timestamp" type="DateTimeOffset">
  Momento em que a mensagem foi recebida pelo provedor.
</ResponseField>

<Note>
  Os campos comuns a toda mensagem recebida (`isForwarded`, `isStatusMessage`, `isHistoryMessage`, `quotedMessage`, `metaReferralAds`) também podem estar presentes. Veja o [envelope comum de mensagens](/mensagens/visao-geral).
</Note>