> ## 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

> Chat 1:1 e grupos dentro do seu app: identidade estável, JWT no seu backend e WebSocket em tempo real.

<Tip>
  Chat in-app é a **conversa dentro do seu produto**. Não é [Chat no site](/ai-web-widget/index) (widget com IA na página). Aqui o usuário já está autenticado no **seu** app.
</Tip>

## O que é Chat na Notifique?

É o canal para **mensagens 1:1 e grupos** no iOS, Android ou web do seu produto. Você cria um **Chat App** no workspace, cadastra usuários com um `externalUserId` estável e emite um **JWT no seu backend**. O app móvel ou o front **nunca** vê o signing secret.

Você pode:

* **Criar Chat Apps** com origens permitidas (CORS) e flags do que o JWT pode fazer
* **Sincronizar usuários** (`PUT /v1/chat/users`) e **agentes** da equipe (`POST /v1/chat/agents`)
* **Emitir JWT** (`POST /v1/chat/users/token`) com TTL de 60 s a 24 h (padrão 1 h)
* **Abrir conversas** 1:1 ou grupo pela API Key; o cliente só cria se você ligar as flags
* **Enviar e listar mensagens** por REST (`POST /v1/chat/messages`) ou WebSocket
* **Espelhar na Inbox** automaticamente
* **Receber webhooks** `chat.received` (usuário) e `chat.sent` (agente), mais ciclo de conversa e membros

<Note>
  Diferente do WhatsApp, chat **não usa instância** de canal. Basta Chat App, usuários e API Key (ou JWT do usuário) com os escopos certos.
</Note>

## Identidade

O identificador do usuário no **seu** sistema é `externalUserId` (immutável). A Notifique gera um `id` interno (`chatUserId`). O JWT leva:

| Claim  | Valor                   |
| ------ | ----------------------- |
| `iss`  | `notifique-chat`        |
| `aud`  | id do Chat App          |
| `sub`  | `chatUserId`            |
| `ext`  | `externalUserId`        |
| `kind` | `USER` ou `AGENT`       |
| `jti`  | id do token (revogável) |

O **secret de assinatura** fica só no servidor. Rotacione no painel ou com `POST /v1/chat/apps/{id}/rotate-secret` — tokens antigos param de valer.

## Tempo real

Conecte em `wss://api.notifique.dev/v1/chat/ws`. **Não** coloque o JWT na query string. O primeiro frame é:

```json theme={null}
{ "type": "auth", "token": "<jwt>" }
```

Resposta `auth.ok`. Depois: `subscribe` / `unsubscribe`, `message.send`, `message.read`, `typing.start` / `typing.stop`, `ping` → `pong`. Eventos da conversa chegam no mesmo socket (`message.new`, etc.).

Há teto de **conexões simultâneas** por plano (e um teto no host). Estouro → o gateway recusa a conexão.

## Cobrança e limites

Cada mensagem enviada consome o SKU **`CHAT_MESSAGE`**: **1 crédito** (ou **R\$ 0,01** no Pague pelo uso).

| Plano    | Apps | Conexões WS | Membros por grupo |
| -------- | ---- | ----------- | ----------------- |
| Free     | 1    | 25          | 32                |
| Basic    | 1    | 100         | 32                |
| Pro      | 2    | 400         | 128               |
| Business | 9    | 1.500       | 256               |

Os mesmos números aparecem em **Planos e preços** no painel.

## Flags padrão (restritivas)

No Chat App, por padrão:

* `allowClientCreateDirect` = **false**
* `allowClientCreateGroup` = **false**
* `allowClientAddMembers` = **false**

Com isso, o JWT **não** cria conversa nem adiciona membro. A API Key (backend) cria. JWT com flag desligada → **403** `CHAT_CLIENT_CREATE_DISABLED`.

## Quando usar?

Funciona para **inbox do produto**, **suporte 1:1** e **grupos pequenos**. Mensagem em massa, OTP ou reengajamento fora do app → [Push](/push-api/como-funciona/introducao), [e-mail](/emails-api/como-funciona/introducao) ou [WhatsApp](/whatsapp-api/como-funciona/introducao). Widget na landing page → [Chat no site](/ai-web-widget/index).

## Como funciona na prática

1. **Crie um Chat App** no painel (**Visão geral → Chat**) ou `POST /v1/chat/apps`
2. **Cadastre o usuário** com `externalUserId` quando ele existir no seu banco
3. **Emita o JWT** no seu backend e entregue só ao cliente autenticado
4. O app **abre o WebSocket**, autentica e **se inscreve** nas conversas
5. Sua API Key **abre a conversa 1:1** (dois `USER`) ou o grupo; o cliente envia mensagens

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

## O que dá para fazer

* **Conversas DIRECT** com exatamente dois usuários `USER` (idempotente por par: `CHAT_DIRECT_EXISTS` se já existe)
* **Grupos** com política de entrada (`OPEN`, `ADMIN_ADD`, `INVITE`) e de convite (`ANY_MEMBER`, `ADMINS_ONLY`)
* **Idempotência** de mensagem com `clientMessageId` (mesmo id → mesma mensagem)
* **Tipos** no envio PIV1: `text`, `image`, `audio`, `file` (`payload.mediaUrl` só HTTPS). A resposta usa `TEXT` / `IMAGE` / `AUDIO` / `FILE`.
* **Origens** no Chat App: se a lista não estiver vazia, o `Origin` do JWT precisa bater

## Depois da primeira mensagem

* **Acompanhe** por [webhooks](/chat-api/como-funciona/eventos-do-webhooks)
* **Responda no painel** (Chat ou Inbox) como agente
* **Teste** no [Sandbox](/guides/sandbox/index) com `sk_test_...` antes de produção

## Próximos passos

* [Quick Start](/chat-api/como-funciona/quick-start): app → usuários → JWT → mensagem
* [Usuário e agente](/chat-api/como-funciona/usuario-e-agente): `USER` vs `AGENT`
* [Enviar mensagens](/chat-api/como-funciona/enviar-mensagens): texto, imagem, áudio e arquivo
* [Escopos da API Key](/chat-api/como-funciona/escopos-da-api-key): permissões
* [Eventos dos webhooks](/chat-api/como-funciona/eventos-do-webhooks): o que chega na sua URL
* [Comece aqui](/guides/introducao/comece-aqui): integração geral da plataforma