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

# Presença

> Inscreve-se para receber atualizações de presença (online/offline) de um contato

# Presença

O comando **Presença** inscreve o canal para receber atualizações de presença (online/offline)
de um contato específico. Após a inscrição, você receberá webhooks sempre que o contato
ficar online ou offline.

## Requisição

```
POST /api/v1/message/SendCommand
```

```json theme={null}
{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "PRESENCE_SUBSCRIPTION",
    "commandType": "PRESENCE_SUBSCRIPTION",
    "id": "5511999887766@s.whatsapp.net"
  }
}
```

### Campos

| Campo | Tipo     | Obrigatório | Descrição                              |
| ----- | -------- | ----------- | -------------------------------------- |
| `id`  | `string` | **Sim**     | JID do contato para monitorar presença |

## Resposta da API

```json theme={null}
{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

## Webhook de confirmação

A aceitação da inscrição é confirmada via webhook do tipo `PRESENCE_SUBSCRIPTION_RESPONSE`,
entregue antes das atualizações de presença:

```json theme={null}
{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "PRESENCE_SUBSCRIPTION_RESPONSE",
    "success": true,
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "12345678901234:56@lid",
    "message": null
  }
}
```

### Campos da confirmação

| Campo     | Tipo      | Descrição                                                               |
| --------- | --------- | ----------------------------------------------------------------------- |
| `success` | `boolean` | Indica se a inscrição foi aceita                                        |
| `jid`     | `string`  | JID do contato inscrito                                                 |
| `lid`     | `string`  | LID (LinkedID) do contato inscrito                                      |
| `message` | `string`  | Mensagem auxiliar (ex.: erro) quando a inscrição não pode ser concluída |

<Note>
  O webhook `PRESENCE_SUBSCRIPTION_RESPONSE` é apenas a confirmação da inscrição. As mudanças
  de status do contato chegam depois, em webhooks separados do tipo `CONTACT_PRESENCE`.
</Note>

## Webhook CONTACT\_PRESENCE

Após a inscrição, você receberá webhooks do tipo `CONTACT_PRESENCE` sempre que o status
do contato mudar.

### Campos do webhook

| Campo         | Tipo                | Descrição                                                  |
| ------------- | ------------------- | ---------------------------------------------------------- |
| `jid`         | `string`            | JID do contato                                             |
| `lid`         | `string`            | LID do contato                                             |
| `unavailable` | `boolean`           | `false` = contato **online**, `true` = contato **offline** |
| `lastSeen`    | `string` (ISO 8601) | Última vez que o contato esteve online                     |

### Exemplos de evento

<AccordionGroup>
  <Accordion title="Contato ficou online">
    ```json theme={null}
    {
      "packageId": null,
      "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": {
        "type": "CONTACT_PRESENCE",
        "jid": "5511999887766@s.whatsapp.net",
        "lid": "12345678901234:56@lid",
        "unavailable": false,
        "lastSeen": "2025-04-14T14:22:00Z"
      }
    }
    ```

    O campo `unavailable` com valor `false` indica que o contato está **online** neste momento.
  </Accordion>

  <Accordion title="Contato ficou offline">
    ```json theme={null}
    {
      "packageId": null,
      "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": {
        "type": "CONTACT_PRESENCE",
        "jid": "5511999887766@s.whatsapp.net",
        "lid": "12345678901234:56@lid",
        "unavailable": true,
        "lastSeen": "2025-04-14T14:45:00Z"
      }
    }
    ```

    O campo `unavailable` com valor `true` indica que o contato está **offline**. O campo
    `lastSeen` contém o horário em que o contato ficou offline.
  </Accordion>
</AccordionGroup>

## Limitações

<AccordionGroup>
  <Accordion title="Privacidade do contato">
    Se o contato desativou a exibição de "visto por último" e "online" nas configurações
    de privacidade do WhatsApp, você pode não receber atualizações de presença. Não há como
    contornar essa restrição — ela é controlada inteiramente pelo contato.
  </Accordion>

  <Accordion title="Inscrição por sessão">
    A inscrição de presença é vinculada a sessão atual. Se a sessão for desconectada
    e reconectada, você **deve** reenviar o comando `PRESENCE_SUBSCRIPTION` para cada contato
    que deseja monitorar. Considere implementar um mecanismo automático que reenvia as
    inscrições após receber o evento [CONNECTED](/comandos/iniciar-sessao).
  </Accordion>

  <Accordion title="Latência">
    Atualizações de presença podem ter um pequeno atraso (alguns segundos) entre a mudança real
    do status e o recebimento do webhook. Isso é inerente ao protocolo do WhatsApp e não pode
    ser eliminado.
  </Accordion>
</AccordionGroup>

## Exemplo completo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-dev.messagefy.io/api/v1/message/SendCommand \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: sua-api-key" \
    -d '{
      "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": {
        "type": "PRESENCE_SUBSCRIPTION",
        "commandType": "PRESENCE_SUBSCRIPTION",
        "id": "5511999887766@s.whatsapp.net"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-dev.messagefy.io/api/v1/message/SendCommand",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "sua-api-key"
      },
      json={
          "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "content": {
              "type": "PRESENCE_SUBSCRIPTION",
              "commandType": "PRESENCE_SUBSCRIPTION",
              "id": "5511999887766@s.whatsapp.net"
          }
      }
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api-dev.messagefy.io/api/v1/message/SendCommand",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key",
      },
      body: JSON.stringify({
        channelId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        content: {
          type: "PRESENCE_SUBSCRIPTION",
          commandType: "PRESENCE_SUBSCRIPTION",
          id: "5511999887766@s.whatsapp.net",
        },
      }),
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Tip>
  Use eventos de presença para otimizar o envio de mensagens. Enviar mensagens quando
  o contato está online aumenta a chance de leitura rápida. Combine com o indicador
  de [digitação](/comandos/digitacao) para uma experiência mais natural.
</Tip>