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

# Introduction

> 1:1 and group chat inside your app: stable identity, JWT on your backend, and realtime WebSocket.

<Tip>
  In-app chat is the **conversation inside your product**. It is not [Web chat](/en/ai-web-widget/index) (AI widget on a page). Here the user is already signed into **your** app.
</Tip>

## What is Chat on Notifique?

The channel for **1:1 messages and groups** in your iOS, Android, or web product. You create a **Chat App** in the workspace, upsert users with a stable `externalUserId`, and issue a **JWT from your backend**. The mobile app or frontend **never** sees the signing secret.

You can:

* **Create Chat Apps** with allowed origins (CORS) and flags for what the JWT may do
* **Sync users** (`PUT /v1/chat/users`) and team **agents** (`POST /v1/chat/agents`)
* **Issue JWTs** (`POST /v1/chat/users/token`) with TTL from 60 s to 24 h (default 1 h)
* **Open conversations** 1:1 or group with the API Key; the client only creates them if you turn the flags on
* **Send and list messages** over REST (`POST /v1/chat/messages`) or WebSocket
* **Mirror to Inbox** automatically
* **Receive webhooks** `chat.received` (user) and `chat.sent` (agent), plus conversation lifecycle and members

<Note>
  Unlike WhatsApp, chat **does not use a channel instance**. You need a Chat App, users, and an API Key (or user JWT) with the right scopes.
</Note>

## Identity

Your system's user id is `externalUserId` (immutable). Notifique stores an internal `chatUserId`. The JWT carries:

| Claim  | Value                |
| ------ | -------------------- |
| `iss`  | `notifique-chat`     |
| `aud`  | Chat App id          |
| `sub`  | `chatUserId`         |
| `ext`  | `externalUserId`     |
| `kind` | `USER` or `AGENT`    |
| `jti`  | token id (revocable) |

Keep the **signing secret** on the server. Rotate it in the dashboard or with `POST /v1/chat/apps/{id}/rotate-secret` — old tokens stop working.

## Realtime

Connect to `wss://api.notifique.dev/v1/chat/ws`. **Do not** put the JWT in the query string. First frame:

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

Then `auth.ok`. After that: `subscribe` / `unsubscribe`, `message.send`, `message.read`, `typing.start` / `typing.stop`, `ping` → `pong`. Conversation events arrive on the same socket (`message.new`, etc.).

There is a **concurrent connection** cap per plan (and a host cap). Over the limit, the gateway refuses the socket.

## Billing and limits

Each sent message uses SKU **`CHAT_MESSAGE`**: **1 credit** (or **R\$ 0.01** pay-as-you-go).

| Plan     | Apps | WS connections | Members per group |
| -------- | ---- | -------------- | ----------------- |
| Free     | 1    | 25             | 32                |
| Basic    | 1    | 100            | 32                |
| Pro      | 2    | 400            | 128               |
| Business | 9    | 1,500          | 256               |

The same numbers appear under **Plans and pricing** in the dashboard.

## Default flags (restrictive)

On a Chat App, by default:

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

The JWT **cannot** create a conversation or add members. The API Key (backend) does. JWT with the flag off → **403** `CHAT_CLIENT_CREATE_DISABLED`.

## When to use it

Product **inbox**, **1:1 support**, and **small groups**. Broadcast, OTP, or re-engagement outside the app → [Push](/en/push-api/como-funciona/introducao), [email](/en/emails-api/como-funciona/introducao), or [WhatsApp](/en/whatsapp-api/como-funciona/introducao). Widget on a landing page → [Web chat](/en/ai-web-widget/index).

## How it works

1. **Create a Chat App** in the dashboard (**Overview → Chat**) or `POST /v1/chat/apps`
2. **Upsert the user** with `externalUserId` when they exist in your database
3. **Issue the JWT** on your backend and give it only to the signed-in client
4. The app **opens the WebSocket**, authenticates, and **subscribes** to conversations
5. Your API Key **opens the 1:1** (two `USER`s) or the group; the client sends messages

<Info>
  Each **API Key** belongs to **one** workspace. In v1 **do not send** `x-workspace-id`.
</Info>

## What you can do

* **DIRECT** chats with exactly two `USER` members (`CHAT_DIRECT_EXISTS` if the pair already exists)
* **Groups** with join policy (`OPEN`, `ADMIN_ADD`, `INVITE`) and add policy (`ANY_MEMBER`, `ADMINS_ONLY`)
* **Idempotent** messages with `clientMessageId`
* PIV1 send types: `text`, `image`, `audio`, `file` (`payload.mediaUrl` HTTPS only). The response uses `TEXT` / `IMAGE` / `AUDIO` / `FILE`.
* **Origins** on the Chat App: if the list is not empty, the JWT request `Origin` must match

## After the first message

* **Follow along** with [webhooks](/en/chat-api/como-funciona/eventos-do-webhooks)
* **Reply in the dashboard** (Chat or Inbox) as an agent
* **Test** in [Sandbox](/en/guides/sandbox/index) with `sk_test_...` before production

## Next steps

* [Quick Start](/en/chat-api/como-funciona/quick-start)
* [User and agent](/en/chat-api/como-funciona/usuario-e-agente): `USER` vs `AGENT`
* [Send messages](/en/chat-api/como-funciona/enviar-mensagens): text, image, audio, and file
* [API Key scopes](/en/chat-api/como-funciona/escopos-da-api-key)
* [Webhook events](/en/chat-api/como-funciona/eventos-do-webhooks)
* [Start here](/en/guides/introducao/comece-aqui)