Comandos

Comandos são operações especiais que você envia para controlar a sessão do WhatsApp conectada ao seu canal. Diferente de mensagens (que enviam conteúdo para contatos), comandos executam ações como consultar contatos, verificar o status da conexão, iniciar ou encerrar sessões, entre outros.

Como enviar um comando

Todos os comandos são enviados através do mesmo endpoint:

POST /api/v1/message/SendCommand

O corpo da requisição segue o formato padrão do Package:

{
  "channelId": "uuid-do-canal",
  "idempotency": {
    "key": "comando-status-canal-x",
    "ttl": "5m"
  },
  "content": {
    "type": "TIPO_DO_COMANDO",
    "commandType": "TIPO_DO_COMANDO",
    ...campos_especificos
  }
}

Os campos type e commandType determinam qual comando será executado.

Idempotência

Use o campo idempotency para evitar comandos duplicados quando houver falha de rede ou timeout. A API rejeita requisições com o mesmo key dentro do ttl com status 409 Conflict.

string

Chave única que identifica a requisição. Use um valor determinístico (por exemplo, ID do comando ou combinação de canal + tipo). Requisições subsequentes com o mesmo key dentro do ttl retornam 409 Conflict.

string

required

Tempo de vida da chave em formato compacto: s (segundos), m (minutos), h (horas), d (dias), w (semanas). Exemplos: "5m", "1h", "30m". Máximo: 4h.

Comandos como STATUS ou GET_CHATS são naturalmente idempotentes, mas comandos que modificam estado (como MARK_READ ou DISCONNECT) se beneficiam do controle de idempotência para evitar efeitos colaterais em retries.

Resposta da API

A API retorna imediatamente um packageId confirmando que o comando foi recebido:

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

A resposta da API não contém o resultado do comando. O resultado real é entregue de forma assíncrona via webhook, associado ao packageId retornado.

Comandos disponíveis

Comando	type / commandType	Descrição
Status	`STATUS`	Consulta o estado da conexão
Iniciar Sessão	`SESSION_START_QR_CODE` / `SESSION_START_PAIR_CODE` / `SESSION_START_LINK`	Inicia a conexão com WhatsApp
Importar Sessão	`SESSION_IMPORT`	Importa uma sessão WhatsApp Web já autenticada
Confirmar Passkey	`PASSKEY_CONFIRM`	Confirma o pareamento por passkey do WhatsApp
Contatos	`CONTACTS`	Lista os contatos do dispositivo
Grupos	`GROUPS`	Lista os grupos do dispositivo
Info do Contato	`CONTACT_INFO`	Obtem detalhes de um contato
Info do Grupo	`GROUP_INFO`	Obtem detalhes de um grupo
Conversas	`GET_CHATS`	Lista as conversas recentes
Últimas Mensagens	`GET_LAST_MESSAGES`	Obtem mensagens de uma conversa
Marcar como Lido	`MARK_READ`	Marca mensagens como lidas
Presença	`PRESENCE_SUBSCRIPTION`	Inscreve-se para receber presença de um contato
Digitação	`START_TYPING` / `STOP_TYPING`	Simula indicador de digitação
Desconectar	`DISCONNECT`	Encerra a sessão do WhatsApp
Flows	`FLOWS`	Gerencia WhatsApp Flows (apenas WhatsApp Oficial)

Autenticação

Todas as requisicoes devem incluir o header API-KEY com sua chave de API valida.

curl -X POST https://api-dev.messagefy.io/api/v1/message/SendCommand \
  -H "Content-Type: application/json" \
  -H "API-KEY: sua-api-key" \
  -d '{
    "channelId": "uuid-do-canal",
    "content": {
      "type": "STATUS",
      "commandType": "STATUS"
    }
  }'

Certifique-se de configurar a URL de webhook no seu canal para receber as respostas dos comandos. Consulte a secao Webhooks para mais detalhes.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Cobranças

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Visão Geral dos Comandos

Comandos

Como enviar um comando

Idempotência

Resposta da API

Comandos disponíveis

Autenticação

​Comandos

​Como enviar um comando

​Idempotência

​Resposta da API

​Comandos disponíveis

​Autenticação

Comandos

Como enviar um comando

Idempotência

Resposta da API

Comandos disponíveis

Autenticação