Janela de 24h

A consulta que decide quanto você vai pagar. Dentro da janela, texto livre não custa nada. Fora dela, só template, e template é cobrado por mensagem.

GET/public/v1/window/{to}

O fluxo (link para esta seção)

Pergunte antes de escolher o que mandar. É uma chamada barata que evita gastar template com quem responderia de graça.

fluxo
janela aberta   ->  POST /messages com "text"      (gratuito)
janela fechada  ->  POST /messages com "template"  (cobrado)
curl
curl https://api.patrociniotech.com/public/v1/window/5521999999999 \
  -H "Authorization: Bearer ptk_live_..."

Resposta (link para esta seção)

200
{
  "success": true,
  "data": {
    "to": "5521999999999",
    "open": true,
    "can_send_text": true,
    "seconds_left": 84141,
    "expires_at": "2026-08-03T11:14:22.000Z",
    "last_inbound_at": "2026-08-02T11:14:22.000Z",
    "opt_in": "accepted"
  }
}
CampoO que é
openA janela está aberta agora.
can_send_textO mesmo que open, com o nome do que você quer saber. Use este.
seconds_leftQuantos segundos faltam para fechar. Zero quando está fechada.
expires_atQuando fecha, em UTC. Nulo se o contato nunca escreveu.
last_inbound_atÚltima vez que o contato escreveu para você.
opt_inaccepted, pending, declined ou nulo. Vale para campanha, não para a janela.

O que abre a janela (link para esta seção)

Só a mensagem do contato. Cada vez que ele escreve, a janela reabre por 24 horas a partir daquele instante. Mensagem que você envia não abre nem estende nada, por mais que ele receba e leia.

Contato que nunca escreveu devolve open: false. Não é erro: é o estado normal de quem você ainda não conversou, e a resposta certa é mandar template.

Vários números (link para esta seção)

Se a sua conta tem mais de um número conectado, a janela é por número. Passe phone_number_id para consultar a de um específico; sem ele, respondemos pela conversa mais recente daquele contato.

curl
curl "https://api.patrociniotech.com/public/v1/window/5521999999999?phone_number_id=1234567890" \
  -H "Authorization: Bearer ptk_live_..."

Dá para não consultar? (link para esta seção)

Dá. Mande o texto direto: fora da janela o envio volta 422 e aí você tenta o template. Funciona, mas custa uma ida e volta a mais em cada mensagem, e o erro só aparece depois da tentativa.

Existe um caminho ainda melhor quando você está respondendo alguém: o evento message.received já traz window_expires_at. Guardando esse valor, você sabe até quando pode responder de graça sem consultar nada.