# Janela de 24h

Confira se o contato pode receber texto livre pelo número que fará o envio.

A janela define se você pode enviar texto livre. Fora dela, use um template aprovado. Estar dentro da janela não significa que a mensagem será gratuita: a cobrança depende das regras da Meta.

### GET /public/v1/window/{to}

## O fluxo

Consulte o mesmo número que fará o envio antes de escolher o formato da mensagem. A Meta confirma a permissão no momento do envio, porque a janela pode vencer entre as duas chamadas.

fluxo

```text
janela aberta   ->  POST /messages com "text" ou "template"
janela fechada  ->  POST /messages com "template" aprovado
```

curl

```bash
curl https://api.patrociniotech.com/public/v1/window/5521999999999 \
  -H "Authorization: Bearer SUA_CHAVE"
```

## Resposta

200

```text
{
  "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",
    "opt_in_at": "2026-08-02T11:14:22.000Z",
    "opt_in_source": "inbound",
    "opt_in_scope": "phone_number",
    "marketing_allowed": true,
    "marketing_block_reason": null
  }
}
```

| Campo | O que é |
| --- | --- |
| open | A janela está aberta agora. |
| can\_send\_text | Mesmo valor de `open`. Indica se o envio com `text` está permitido. |
| seconds\_left | Quantos segundos faltam para fechar. Zero quando está fechada. |
| expires\_at | Quando fecha, em UTC. Nulo se o contato nunca escreveu. |
| last\_inbound\_at | Última vez que o contato escreveu para o número consultado. |
| opt\_in | accepted, pending, declined ou nulo, conforme o cadastro no número consultado. Não define se a janela está aberta. |
| opt\_in\_at / opt\_in\_source | Data e origem do estado local. accepted com origem inbound indica que a pessoa escreveu; não comprova autorização para promoções. null significa informação não registrada. |
| opt\_in\_scope | phone\_number: estado do cadastro no número selecionado. Uma recusa em outro número da empresa também impede marketing. |
| marketing\_allowed | Ausência de bloqueio registrado para marketing. True não comprova consentimento, aprovação do template ou entrega. |
| marketing\_block\_reason | opted\_out\_or\_blocked quando existe recusa de promoções na empresa ou bloqueio no número consultado; nulo sem essa exclusão. |

## Janela aberta não é autorização de marketing

O contato pode ter `open: true` e `marketing_allowed: false`. A primeira informação permite responder ao atendimento com texto; a segunda impede novos templates promocionais pela API.

`opt_in` descreve o cadastro deste número. Uma saída de promoções registrada em outro número da mesma empresa também impede marketing: por isso, consulte `marketing_allowed`, não apenas `opt_in`.

> Para um contato pendente ou desconhecido, `marketing_allowed: true` significa apenas que não encontramos exclusão registrada. Não converta esse resultado em `accepted`. A origem e o consentimento da sua lista continuam sob responsabilidade da integração.

## O que abre a janela

A mensagem do **contato** renova a janela por 24 horas a partir do horário da mensagem. Envio, entrega e leitura de mensagens da empresa não estendem o prazo.

> Se não houver mensagem recebida registrada, a resposta será `open: false`. Para iniciar a conversa, use um template aprovado e respeite a permissão do destinatário.

## Vários números

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, consultamos o número padrão, seguindo a mesma seleção usada no envio. Não combinamos janelas de números diferentes.

O telefone em `to` deve conter DDI e DDD. Para cadastros locais, [normalize o telefone informando o país](https://patrociniotech.com/documentacao-api/mensagens.md); esta rota não deduz o país nem acrescenta 55.

curl

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

## Usar a janela recebida no webhook

A consulta é opcional. O evento [message.received](https://patrociniotech.com/documentacao-api/webhook.md) já informa `window_expires_at`. Mantenha a maior validade por contato e número da empresa para escolher entre texto e template sem consultar a cada resposta.

> Atenção: Perto do vencimento, confirme a janela com esta consulta. Trate o erro `outside_24h_window` caso o prazo termine antes do envio.

---

Fonte: https://patrociniotech.com/documentacao-api/janela
Índice para IA: https://patrociniotech.com/documentacao-api/llms.txt