Pular para o conteúdo

Mostrar presençaPRO

POST/connections/{id}/presence

Mostra ao contato “digitando…” (composing) ou “gravando áudio…” (recording) até paused ou até uma mensagem ser enviada; available mostra o número online para todos (e to não é usado). Os envios já mostram “digitando…” antes de sair (veja typingDelay no envio): esta operação serve para uma pausa que você controla, como um atendente escrevendo uma resposta. Escopo necessário: messages:send.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número).

Corpo da requisição

tostringobrigatório

A conversa: um número de telefone com código do país e DDD, só dígitos (a API usa o endereço que o WhatsApp registrou para ele, como no envio), ou um JID usado como está: o de um grupo (…@g.us) ou o jid de um evento de webhook, que pode ser um …@lid.

mínimo de 1 caractere
statestringobrigatório

A presença: composing (digitando), recording (gravando áudio), paused (para de mostrar as duas) ou available (online, para todos).

Valores: "composing", "recording", "paused", "available"

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200A presença foi enviada: {"success": true}.
400FST_ERR_VALIDATIONO corpo não segue o schema da operação (um campo obrigatório ausente, ou um valor fora dos limites); message diz o que está errado.
400A conexão não está open: o corpo traz Connection not ready (status: …). Espere o evento connection.status com open e repita.
400not_on_whatsappO número de to não está no WhatsApp: o corpo traz code: not_on_whatsapp.
401Sem chave de API, ou com uma chave inválida (desconhecida, revogada ou expirada).
402subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Regularize o pagamento no painel e repita.
403A chave de API não tem o escopo messages:send; a mensagem do erro cita o escopo que falta.
403plan_feature_requiredO plano da organização dona da conexão não inclui as operações de mensagem: o corpo traz code: plan_feature_required e feature: message_ops. Elas fazem parte do plano PRO (e do período de teste).
404A conexão não existe ou não é de quem chama (o recurso de outra pessoa responde igual a um que não existe).
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere Retry-After segundos.Cabeçalho: Retry-After
500O WhatsApp recusou a operação ou não respondeu (Failed to send the presence). Pode repetir.
501unsupported_by_providerO provedor da conexão não oferece esta operação.
503A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere Retry-After segundos e tente de novo.Cabeçalho: Retry-After

Detalhes

Com available, to continua obrigatório no corpo, mas o valor é ignorado.

Recurso do plano PRO: exige que a organização dona da conexão tenha o recurso message_ops; sem ele, a resposta é 403 com code: plan_feature_required. A verificação da organização em dia (402 subscription_inactive) vem antes da do plano.

Não passa pela fila: não é uma mensagem nova para ninguém, então o ritmo de envio, o aquecimento e o limite de destinatários novos não se aplicam. Se o WhatsApp recusar a operação, a resposta é 500.

Plano PRO: exige um plano com o recurso message_ops; sem ele, a resposta é 403 com code: plan_feature_required.

Guia: Operações de mensagem

Esta página ajudou? · Atualizado em 28 set 2026