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

> First in-app conversation: Chat App, two users, JWT, and one message.

<Tip>
  From **zero to the first message**: **Chat App** → **users** → **JWT on your backend** → **conversation** → **send**.
</Tip>

## In short

* **Create a Chat App** and store `id`, `publicKey`, and the **signing secret** (server only).
* **Upsert users** with a stable `externalUserId`.
* **Issue the JWT** on your backend (`POST /v1/chat/users/token`). The app only receives the token.
* **Open the 1:1 with the API Key** (JWT create flags are off by default).
* **Send** with the API Key (`senderExternalUserId`) or with a member JWT.

Context: [Introduction](/en/chat-api/como-funciona/introducao). Scopes: [API Key scopes](/en/chat-api/como-funciona/escopos-da-api-key).

## Before you start

* Key with **`chat:apps:create`**, **`chat:users`**, **`chat:conversations:write`**, and **`chat:messages:send`** (or admin while testing)
* Auth: `Authorization: Bearer sk_live_...` or `x-api-key`
* Base URL: `https://api.notifique.dev`. Use `sk_test_...` in [Sandbox](/en/guides/sandbox/index) if you are starting out

<Warning>
  Never embed the signing secret in the app. Only your server signs JWTs.
</Warning>

***

## 1. Create a Chat App

#### 1A. Dashboard

1. **Overview → Chat** → **New app**
2. Enter the product **name**
3. Copy the **public key** and **signing secret** (secret only at create time, or rotate later)

#### 1B. API

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

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

**200** with `signingSecret` (only on create or rotate). Scope: **`chat:apps:create`**. Save the **`id`**.

***

## 2. Upsert users

```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"
}
```

Repeat for `user_bob`. Scope: **`chat:users`**.

***

## 3. Issue a JWT (your 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
}
```

Give `data.token` only to the client signed in as Alice. Default TTL **3600** s; max **86400**.

***

## 4. Open a 1:1 (API Key)

With default flags the JWT **cannot** create a conversation (**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` requires **exactly two** `USER` members. Pair already exists → **409** `CHAT_DIRECT_EXISTS`. Scope: **`chat:conversations:write`**.

***

## 5. Send a message

Same PIV1 contract as other channels: `from` (Chat App id), `to` (conversation id), `type`, and `payload`.

**API Key** (requires `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": "Hi, Alice" },
  "senderExternalUserId": "user_bob",
  "clientMessageId": "msg_001"
}
```

Each send costs **1 credit** (`CHAT_MESSAGE`). Scope: **`chat:messages:send`**. The older `POST /v1/chat/conversations/{id}/messages` path still works.

**Member JWT:** `POST /v1/chat/messages` with `Authorization: Bearer <jwt>` and `{ "to": ["cnv_xxxxx"], "type": "text", "payload": { "message": "Hi, Bob" } }` — no API Key. List: `GET /v1/chat/conversations/{id}/messages` with the JWT.

***

## 6. WebSocket (optional)

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

1. Connect **without** `?token=`
2. Send `{ "type": "auth", "token": "<jwt>" }`
3. `{ "type": "subscribe", "conversationId": "…" }`
4. `{ "type": "message.send", "conversationId": "…", "body": "hi", "clientMessageId": "…" }`

***

## Next steps

* [Introduction](/en/chat-api/como-funciona/introducao)
* [User and agent](/en/chat-api/como-funciona/usuario-e-agente)
* [Send messages](/en/chat-api/como-funciona/enviar-mensagens)
* [Scopes](/en/chat-api/como-funciona/escopos-da-api-key)
* [Webhook events](/en/chat-api/como-funciona/eventos-do-webhooks)