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

# Quick Start

> Primeira conversa in-app: Chat App, dois usuários, JWT e uma mensagem.

<Tip>
  Do **zero à primeira mensagem** em poucos passos: **Chat App** → **usuários** → **JWT no seu backend** → **conversa** → **envio**.
</Tip>

## Em poucas palavras

* **Crie um Chat App** e guarde `id`, `publicKey` e o **signing secret** (só no servidor).
* **Cadastre usuários** com `externalUserId` estável.
* **Emita o JWT** no seu backend (`POST /v1/chat/users/token`). O app só recebe o token.
* **Abra a conversa 1:1 com a API Key** (flags de criação pelo JWT vêm desligadas).
* **Envie** com a API Key (`senderExternalUserId`) ou com o JWT do membro.

Contexto: [Introdução](/chat-api/como-funciona/introducao). Escopos: [Escopos da API Key](/chat-api/como-funciona/escopos-da-api-key).

## Antes de começar

* Chave com **`chat:apps:create`**, **`chat:users`**, **`chat:conversations:write`** e **`chat:messages:send`** (ou admin em teste)
* Autenticação: `Authorization: Bearer sk_live_...` ou `x-api-key`
* Base URL: `https://api.notifique.dev`. Use `sk_test_...` no [Sandbox](/guides/sandbox/index) se estiver começando

<Warning>
  Nunca embuta o signing secret no app. Só o seu servidor assina JWT.
</Warning>

***

## 1. Criar Chat App

#### 1A. Pelo painel

1. **Visão geral → Chat** → **Novo app**
2. Informe o **nome** do produto
3. Copie a **chave pública** e o **signing secret** (este último só uma vez, ou rotacione depois)

#### 1B. Pela API

```http theme={null}
POST /v1/chat/apps
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "name": "Meu App",
  "allowedOrigins": ["https://app.seusite.com"]
}
```

Resposta **200** com `signingSecret` (só nesta criação ou no rotate):

```json theme={null}
{
  "success": true,
  "data": {
    "id": "clxxapp...",
    "name": "Meu App",
    "publicKey": "…",
    "signingSecret": "…",
    "status": "ACTIVE",
    "allowedOrigins": ["https://app.seusite.com"],
    "allowClientCreateDirect": false,
    "allowClientCreateGroup": false,
    "allowClientAddMembers": false
  }
}
```

Escopo: **`chat:apps:create`**. Guarde o **`id`**.

***

## 2. Cadastrar usuários

```http theme={null}
PUT /v1/chat/users
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "chatAppId": "clxxapp...",
  "externalUserId": "user_alice",
  "name": "Alice"
}
```

Repita para `user_bob`. Escopo: **`chat:users`**. O `PUT` é upsert.

***

## 3. Emitir JWT (no seu backend)

```http theme={null}
POST /v1/chat/users/token
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "chatAppId": "clxxapp...",
  "externalUserId": "user_alice",
  "ttlSec": 3600
}
```

```json theme={null}
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2026-09-06T02:00:00.000Z",
    "jti": "…"
  }
}
```

Entregue `data.token` só ao cliente logado como Alice. TTL padrão **3600** s; máximo **86400**.

***

## 4. Abrir conversa 1:1 (API Key)

O JWT, com as flags padrão, **não** cria conversa (**403** `CHAT_CLIENT_CREATE_DISABLED`).

```http theme={null}
POST /v1/chat/conversations
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "chatAppId": "clxxapp...",
  "type": "DIRECT",
  "members": ["user_alice", "user_bob"]
}
```

`DIRECT` exige **exatamente dois** usuários `USER`. Já existir o par → **409** `CHAT_DIRECT_EXISTS`.

Escopo: **`chat:conversations:write`**.

***

## 5. Enviar mensagem

Contrato PIV1, igual aos outros canais: `from` (id do Chat App), `to` (id da conversa), `type` e `payload`.

**Pela API Key** (precisa `senderExternalUserId`):

```http theme={null}
POST /v1/chat/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "from": "clxxapp...",
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": { "message": "Oi, Alice" },
  "senderExternalUserId": "user_bob",
  "clientMessageId": "msg_001"
}
```

Cada envio consome **1 crédito** (`CHAT_MESSAGE`). Escopo: **`chat:messages:send`**. O path antigo `POST /v1/chat/conversations/{id}/messages` continua funcionando.

Imagem, áudio e arquivo: [Enviar mensagens](/chat-api/como-funciona/enviar-mensagens). Quem fala na sala: [Usuário e agente](/chat-api/como-funciona/usuario-e-agente).

**Pelo JWT do membro:**

```http theme={null}
POST /v1/chat/messages
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```

```json theme={null}
{
  "to": ["cnv_xxxxx"],
  "type": "text",
  "payload": { "message": "Oi, Bob" },
  "clientMessageId": "msg_002"
}
```

Sem API Key. O remetente é o usuário do token. Listar mensagens: `GET /v1/chat/conversations/{id}/messages` com o JWT.

***

## 6. WebSocket (opcional)

```text theme={null}
wss://api.notifique.dev/v1/chat/ws
```

1. Conecte **sem** `?token=`
2. Envie `{ "type": "auth", "token": "<jwt>" }`
3. `{ "type": "subscribe", "conversationId": "…" }`
4. `{ "type": "message.send", "conversationId": "…", "body": "oi", "clientMessageId": "…" }`

***

## 7. Webhooks (opcional)

Ative `chat.received`, `chat.sent`, `chat.conversation.created` e os demais `chat.*` que sua integração usa.

Guia: [Eventos dos webhooks](/chat-api/como-funciona/eventos-do-webhooks).

## Próximos passos

* [Introdução](/chat-api/como-funciona/introducao): identidade, limites e flags
* [Usuário e agente](/chat-api/como-funciona/usuario-e-agente)
* [Enviar mensagens](/chat-api/como-funciona/enviar-mensagens)
* [Escopos](/chat-api/como-funciona/escopos-da-api-key): permissões da chave
* [Eventos dos webhooks](/chat-api/como-funciona/eventos-do-webhooks)
* [Respostas de erro](/guides/conceitos/resposta-de-erros): códigos HTTP e `code`