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

{
  "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

{
  "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:

{
  "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

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.

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

Contato ficou online

{
  "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.

Contato ficou offline

{
  "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.

Limitações

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.

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.

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.

Exemplo completo

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"
    }
  }'

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())

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);

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 para uma experiência mais natural.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Presença

Presença

Requisição

Campos

Resposta da API

Webhook de confirmação

Campos da confirmação

Webhook CONTACT_PRESENCE

Campos do webhook

Exemplos de evento

Limitações

Exemplo completo

​Presença

​Requisição

​Campos

​Resposta da API

​Webhook de confirmação

​Campos da confirmação

​Webhook CONTACT_PRESENCE

​Campos do webhook

​Exemplos de evento

​Limitações

​Exemplo completo

Presença

Requisição

Campos

Resposta da API

Webhook de confirmação

Campos da confirmação

Webhook CONTACT_PRESENCE

Campos do webhook

Exemplos de evento

Limitações

Exemplo completo