Fixar mensagem no WhatsApp pela API: regras do grupo, aviso do dia e conversa no topo

Pela API não oficial do WhatsApp você fixa uma mensagem no topo de uma conversa ou grupo com POST /{key}/message/pin (informando o id e, se quiser, a duração em segundos — o padrão é 7 dias), desafixa com POST /{key}/message/unpin, marca com estrela com POST /{key}/message/{id}/keep e fixa a conversa inteira no topo da sua lista com PATCH /{key}/chat?action=pin. Regras do grupo, aviso do dia e pedido em aberto passam a ficar sempre à vista.

Grupo sem mensagem fixada é grupo onde a mesma pergunta é feita dez vezes por semana. Conversa importante sem destaque é conversa que o atendente perde no meio de outras cem. Fixar resolve os dois — e, por API, dá para automatizar a troca do que está fixado.

A camada não oficial da WAME é independente e não é afiliada, endossada ou suportada pelo WhatsApp ou pela Meta. O uso é de responsabilidade de quem envia.

Quatro recursos que parecem iguais

A distinção importa: fixar mensagem é comunicação com os participantes; estrela e conversa fixada são organização do seu lado.

Fixar uma mensagem

Para fixar, você precisa do id da mensagem. Ele vem de dois lugares: da resposta do envio (quando a mensagem é sua) ou do webhook (quando a mensagem chegou). O fluxo mais comum é enviar e fixar em seguida:

# 1. Envia as regras no grupo
curl -X POST "https://us.api-wa.me/SUA_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "text": "📌 Regras do grupo\n1. Só assuntos da turma\n2. Nada de propaganda\n3. Dúvidas no privado com a coordenação"
  }'

# 2. Fixa a mensagem usando o id retornado no envio
curl -X POST "https://us.api-wa.me/SUA_KEY/message/pin" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ID_DA_MENSAGEM", "duration": 2592000 }'

A duration é em segundos e, se omitida, a mensagem fica fixada por 7 dias (604800). Alguns valores úteis:

O WhatsApp trabalha com prazos próprios para mensagens fixadas; se você passar um valor fora do que o app aceita, confira na documentação como a API trata. Para uma regra permanente, o caminho mais seguro é refixar periodicamente, com um job simples.

Em Node, envio e fixação juntos:

const BASE = 'https://us.api-wa.me/SUA_KEY';

async function post(path, body) {
  const r = await fetch(`${BASE}${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  return r.json();
}

async function publicarEFixar(grupo, texto, duracao = 604800) {
  const enviada = await post('/message/text', { to: grupo, text: texto });
  // A resposta do envio traz o id da mensagem no campo `id`.
  const { id } = enviada;
  await post('/message/pin', { id, duration: duracao });
  return id;
}

Guarde o id fixado no seu banco. Você vai precisar dele para desafixar depois.

Desafixar e trocar o aviso

curl -X POST "https://us.api-wa.me/SUA_KEY/message/unpin" \
  -H "Content-Type: application/json" \
  -d '{ "id": "ID_DA_MENSAGEM" }'

O padrão "aviso do dia" junta tudo: todo dia de manhã, o sistema desafixa o aviso de ontem, publica o de hoje e fixa.

async function trocarAvisoDoDia(grupo, textoDeHoje, idDeOntem) {
  if (idDeOntem) await post('/message/unpin', { id: idDeOntem });
  return publicarEFixar(grupo, textoDeHoje, 86400);
}

Funciona para cardápio do dia no grupo de clientes de um restaurante, escala do plantão no grupo da equipe, pauta da aula no grupo da turma. Com duração de 24 horas, mesmo que o job falhe um dia, o aviso velho não fica pendurado.

Casos de uso em grupos

• Regras do grupo. O caso clássico. Fixe na criação do grupo e refixe quando mudar. Combina com o !regras do bot de comandos para grupo: quem pergunta recebe a resposta citando a mensagem fixada.
• Link de convite ou de inscrição. Em comunidades, o link da próxima turma fixado no grupo de avisos.
• Evento da semana. Envie o convite de evento e fixe até o dia.
• Comunicado importante. Mudança de horário, feriado, manutenção programada.

Um detalhe de permissão: em grupos configurados para que só administradores editem as informações (setting=locked no PATCH /groups/{id}), fixar mensagem exige que o número da instância seja admin. Se o pin não aparecer, é a primeira coisa a conferir. A gestão de configurações e admins está em automatizar grupos pela API.

Casos de uso no atendimento 1:1

Em conversa individual, fixar mensagem é menos comum, mas tem usos bons:

• Pedido em aberto. Fixe o resumo do pedido na conversa com o cliente até a entrega. Ele não precisa rolar a conversa para lembrar o que pediu.
• Dados de pagamento. A chave Pix ou o link de pagamento fixados até a confirmação — o guia de cobrança está em cobrança por Pix pela API.
• Combinado de serviço. Data da visita técnica fixada até o dia.

Estrela e conversa fixada: organização do seu lado

Marcar com estrela é o "favoritos" do WhatsApp — só o seu número vê:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/ID_DA_MENSAGEM/keep"

Útil quando a equipe também usa o app no celular: o bot marca com estrela os comprovantes que chegaram, e quem abre o WhatsApp encontra tudo na lista de mensagens com estrela. Se você usa o celular e a API no mesmo número, esse tipo de sinal ajuda os dois lados a trabalharem juntos.

Fixar a conversa coloca o chat no topo da sua lista:

curl -X PATCH "https://us.api-wa.me/SUA_KEY/[email protected]&action=pin&value=true"

Com value=false, desafixa. Um uso prático: fixar automaticamente as conversas de clientes com problema em aberto, e desafixar quando o ticket fecha. O mesmo endpoint também marca conversa como lida ou não lida (action=markRead). Combinado com labels para organizar conversas, dá uma triagem visual sem CRM.

Fixar mensagem coloca o número em risco?

Não. Fixar, desafixar e marcar com estrela são ações comuns de qualquer usuário. O que pesa no anti-spam do WhatsApp é para quem você manda e como: mensagens não solicitadas, fan-out para desconhecidos, texto idêntico em massa. Num grupo que você administra, com gente que entrou por escolha, fixar as regras é o oposto de spam — é organização. Nesse tipo de uso, a taxa de bloqueio é muito baixa para quem usa do jeito certo. Os fatores reais estão em o que derruba um número.

Só evite o exagero de automação: desafixar e refixar a cada poucos minutos, em dezenas de grupos, é um padrão que nenhum humano faz. Um aviso por dia é natural.

Conclusão

Fixar é um recurso pequeno com efeito grande na organização: POST /{key}/message/pin coloca regras, avisos e pedidos no topo para todos, message/unpin troca o que está fixado, message/{id}/keep marca com estrela no seu número e PATCH /chat?action=pin deixa as conversas prioritárias à vista. Automatizando a troca, o aviso do dia se atualiza sozinho e o grupo para de repetir as mesmas perguntas. Os parâmetros completos estão na documentação, e os outros recursos da camada não oficial estão em API do WhatsApp não oficial: vantagens.