Quick Start

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

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. Escopos: 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 se estiver começando

Nunca embuta o signing secret no app. Só o seu servidor assina JWT.

1. Criar Chat App

1A. Pelo painel

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

1B. Pela API

POST /v1/chat/apps
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Meu App",
  "allowedOrigins": ["https://app.seusite.com"]
}

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

{
  "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

PUT /v1/chat/users
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "chatAppId": "clxxapp...",
  "externalUserId": "user_alice",
  "name": "Alice"
}

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

3. Emitir JWT (no seu backend)

POST /v1/chat/users/token
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "chatAppId": "clxxapp...",
  "externalUserId": "user_alice",
  "ttlSec": 3600
}

{
  "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).

POST /v1/chat/conversations
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "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):

POST /v1/chat/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "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. Quem fala na sala: Usuário e agente. Pelo JWT do membro:

POST /v1/chat/messages
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "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)

wss://api.notifique.dev/v1/chat/ws

Conecte sem ?token=
Envie { "type": "auth", "token": "<jwt>" }
{ "type": "subscribe", "conversationId": "…" }
{ "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.

Próximos passos

Introdução: identidade, limites e flags
Usuário e agente
Enviar mensagens
Escopos: permissões da chave
Eventos dos webhooks
Respostas de erro: códigos HTTP e code

API Chat

Chat Apps

Chat Users

Conversas

Bloqueios

Mensagens

Em poucas palavras

Antes de começar

1. Criar Chat App

1A. Pelo painel

1B. Pela API

2. Cadastrar usuários

3. Emitir JWT (no seu backend)

4. Abrir conversa 1:1 (API Key)

5. Enviar mensagem

6. WebSocket (opcional)

7. Webhooks (opcional)

Próximos passos

​Em poucas palavras

​Antes de começar

​1. Criar Chat App

​1A. Pelo painel

​1B. Pela API

​2. Cadastrar usuários

​3. Emitir JWT (no seu backend)

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

​5. Enviar mensagem

​6. WebSocket (opcional)

​7. Webhooks (opcional)

​Próximos passos

Em poucas palavras

Antes de começar

1. Criar Chat App

1A. Pelo painel

1B. Pela API

2. Cadastrar usuários

3. Emitir JWT (no seu backend)

4. Abrir conversa 1:1 (API Key)

5. Enviar mensagem

6. WebSocket (opcional)

7. Webhooks (opcional)

Próximos passos