Skip to main content
From zero to the first message: Chat App → users → JWT on your backend → conversation → send.

​
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. Scopes: API Key scopes.

​
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 if you are starting out
Never embed the signing secret in the app. Only your server signs JWTs.

​
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

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

​
2. Upsert users

Repeat for user_bob. Scope: chat:users.

​
3. Issue a JWT (your backend)

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).
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):
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)

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

​
Next steps