# Notificações



<ToolHero tool="notify" />

## Como funciona

Uma notificação tem `title`, `message` e `priority` (`normal` ou `high`), e opcionalmente uma `url` para o humano abrir. Ela sai por um **canal**:

* **Canal escolhido:** o `channel` do pedido, pelo nome do canal.
* **Canal padrão:** o canal marcado com `is_default`, quando o pedido não traz `channel`.
* **E-mail da conta:** sem canal nenhum configurado, a notificação vai para o e-mail da conta.

Também está disponível no [MCP](/agentes-de-ia) como a tool `notify` (toolset `notify`): o agente avisa que terminou uma tarefa longa ou que precisa de uma decisão.

<EndpointList tool="notify" />

## Canais

Cada canal tem um `name` único na conta e um `kind`:

| `kind`    | Campos            | Como entrega                                                                        |
| --------- | ----------------- | ----------------------------------------------------------------------------------- |
| `email`   | nenhum            | Envia **só para o e-mail da conta**. Não é possível escolher outro destinatário.    |
| `webhook` | `url`, `secret`   | Faz um `POST` na URL, assinado como no [Webhook Relay](/ferramentas/webhook-relay). |
| `ntfy`    | `server`, `topic` | Publica no tópico do [ntfy](https://ntfy.sh), no servidor informado.                |

`is_default` marca o canal usado quando o pedido não indica um, e `enabled: false` desativa o canal sem apagá-lo. O `secret` do webhook nunca volta nas respostas: guarde-o ao criar o canal.

<Callout type="warn" title="O tópico do ntfy é a senha">
  Em servidores públicos do ntfy, quem souber o tópico lê as notificações. Use um nome longo e imprevisível, ou um servidor seu.
</Callout>

## Limites, retry e histórico

* **Rate limit:** há um limite de notificações por período; acima dele o envio falha com `notify.rate_limited`.
* **Retry do webhook:** uma entrega que falha é tentada de novo algumas vezes antes de virar `notify.delivery_failed`. O receptor deve tratar repetições e conferir a assinatura.
* **Histórico:** `GET /messages` lista os envios (canal, prioridade, status e data), paginado com `page` e `page_size` (até 100). O histórico **não guarda o título nem o corpo da mensagem**.

## Custos

Cada envio pela API é cobrado conforme o valor indicado no endpoint. Canais e histórico são grátis, e a falha na entrega não é cobrada.

## Endpoints

### Enviar notificação

<Endpoint id="notify.send" example={{ body: `{ "title": "Deploy concluído", "message": "A versão 2.4 está no ar.", "priority": "normal" }` }}>
  `title` e `message` são obrigatórios; `priority` é `normal` ou `high`; `url` e `channel` são opcionais. Sem `channel`, usa o canal padrão e, sem nenhum canal, o e-mail da conta.
</Endpoint>

### Histórico de envios

<Endpoint id="notify.messages" example={{ query: { page: "1", page_size: "20" } }}>
  Paginado por `page` e `page_size` (até 100). Não traz o corpo das mensagens.
</Endpoint>

### Listar canais

<Endpoint id="notify.channels.list" />

### Criar canal

<Endpoint id="notify.channels.create" example={{ body: `{ "name": "celular", "kind": "ntfy", "server": "https://ntfy.sh", "topic": "meu-topico-secreto", "is_default": true }` }}>
  `name` e `kind` são obrigatórios. `url` e `secret` valem para `webhook`; `server` e `topic`, para `ntfy`. Campos que não combinam com o `kind` respondem `notify.invalid_channel`.
</Endpoint>

### Consultar canal

<Endpoint id="notify.channels.get" />

### Alterar canal

<Endpoint id="notify.channels.update" example={{ body: `{ "enabled": false }` }}>
  Envie só os campos que mudam. Um canal desativado responde `notify.channel_disabled` quando escolhido num envio.
</Endpoint>

### Excluir canal

<Endpoint id="notify.channels.delete" />

### Testar canal

<Endpoint id="notify.channels.test">
  Envia uma notificação de teste pelo canal, para conferir a configuração antes de depender dele.
</Endpoint>

## Erros

<ErrorTable tool="notify" />