> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Envie notificações push pelo painel ou API: crie apps, registre dispositivos e acompanhe entrega e cliques.

<Tip>
  Push é o **toque no ombro** do usuário: traz de volta para o site ou app sem depender de SMS ou e-mail, ideal para quem **já aceitou** notificações.
</Tip>

## O que é Push na Notifique?

É o canal para **avisar no navegador ou app** quem já deu permissão. Você organiza **Push App**, **dispositivos** e **envios** no mesmo workspace; sua integração guarda os **device IDs** (e pode vincular ao **contato CRM**) e dispara quando precisar.

Você pode:

* **Criar Push Apps** com VAPID Web (gerado automaticamente), **FCM (Android)** e **APNs (iOS)**
* **Registrar dispositivos** web (script) ou mobile (token FCM/APNs) e opcionalmente `contactId`
* **Enviar** para device IDs ou `toContacts` (todos os devices do contato)
* **Rich Web Push**: `image`, `badge`, `tag`, `actions`, `requireInteraction`, etc.
* **Agendar** e **cancelar** envios futuros
* **Acompanhar** entrega e clique por API ou [webhook](/push-api/como-funciona/eventos-do-webhooks)
* **BYOK**: Firebase/APNs em [Integrações](/byok/index) (como Resend/SES no e-mail)

Pense num lembrete na tela do celular: curto, direto, para quem já disse “sim” às notificações.

<Note>
  Diferente do WhatsApp, push **não usa instância** de canal. Basta Push App, dispositivos registrados e API Key com os escopos certos.
</Note>

<Info>
  Som customizado funciona em **mobile** (APNs/FCM). Nos browsers modernos, som customizado na Web Push é limitado ou indisponível.
</Info>

## Quando usar?

Funciona muito bem para **carrinho abandonado**, **atualização rápida** e **trazer o usuário de volta**. Se a pessoa nunca abriu o site ou negou permissão, use [e-mail](/emails-api/como-funciona/introducao) ou [SMS](/sms-api/como-funciona/introducao). Texto longo com HTML → e-mail.

## Como funciona na prática

1. **Crie um Push App**, o VAPID Web é gerado automaticamente (ou configure chaves próprias depois)
2. **Registre dispositivos** quando o navegador entregar a subscription ao seu backend, guarde o **device ID**
3. **Envie** com `to` (array de device IDs), **title** e/ou **body**
4. A plataforma **enfileira, envia e atualiza o status**; seu backend recebe avisos se configurou webhooks

<Info>
  Cada **API Key** pertence a **um** workspace. Na v1 **não envie** `x-workspace-id`.
</Info>

## Ciclo do envio

Depois do `POST`, a notificação passa por `QUEUED` ou `SCHEDULED`, depois `SENT`, `DELIVERED` ou `CLICKED` conforme o dispositivo reporta. Falhas viram `FAILED`; cancelamento de agendamento vira `CANCELLED`.

**Entrega e clique** podem ser reportados pelo **service worker** no cliente. Webhooks avisam seu backend (`push.delivered`, `push.clicked`).

## O que dá para fazer

* **Enviar** para 1 a 100 device IDs por chamada (1 crédito por notificação)
* **Agendar** com `schedule.sendAt`
* **Consultar** histórico ou um envio pelo id
* **Cancelar** agendamento enquanto status for **`SCHEDULED`**
* **Idempotência** com header `Idempotency-Key`
* **Prioridade** em `options.priority`: `high`, `normal`, `low`
* **Restringir por app** com `pushAppIds` na chave, fora da lista → **403** (`PUSH_APP_NOT_ALLOWED`)

Detalhe de campos e erros: **referência da API** na aba Push (menu lateral).

## Depois do primeiro envio

* **Acompanhe** por [webhooks](/push-api/como-funciona/eventos-do-webhooks) (`push.sent`, `push.delivered`, `push.clicked`, `push.failed`)
* **Remova devices** com subscription inválida ao receber `push.failed`
* **Teste** no [Sandbox](/guides/sandbox/index) com `sk_test_...` antes de produção

## Próximos passos

* [Integrar apps](/push-api/integracao/index): Android, iOS, Flutter, React Native e Web
* [Quick Start](/push-api/como-funciona/quick-start): app → dispositivo → envio (foco Web)
* [Escopos da API Key](/push-api/como-funciona/escopos-da-api-key): permissões
* [Eventos dos webhooks](/push-api/como-funciona/eventos-do-webhooks): o que chega na sua URL
* [Comece aqui](/guides/introducao/comece-aqui): integração geral da plataforma