Project integration

Three steps to go from a fresh project + API key to a live chat session in your app. Step 1 your server mints a short-lived user JWT, Step 2 the client opens a WebSocket with that JWT, Step 3 your server listens for events via webhook. The API key never leaves your server.

Step 1 — Mint a user JWT (server-side)

Exchange your project API key (kl_live_*) for a per-user JWT. Pick a sample for your stack — the request/response shape is identical.

Node.js

// Node 18+
const res = await fetch('https://kardocloud.com/v1/me/channels/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.KARDOLIVE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: req.user.id,
    displayName: req.user.name,
    channelId: 'optional-channel-id',
  }),
});
const { token, chatUrl, expiresAt } = await res.json();
return res.json({ token, chatUrl });

Python

# Python (requests)
import os, requests
r = requests.post(
    'https://kardocloud.com/v1/me/channels/token',
    headers={
        'Authorization': f"Bearer {os.environ['KARDOLIVE_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'userId': user.id,
        'displayName': user.name,
        'channelId': channel_id,  # optional
    },
)
r.raise_for_status()
data = r.json()  # { token, chatUrl, expiresAt }

PHP

<?php
// PHP 8+ (curl)
$ch = curl_init('https://kardocloud.com/v1/me/channels/token');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('KARDOLIVE_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => $user->id,
    'displayName' => $user->name,
    'channelId' => $channelId,
  ]),
]);
$res = json_decode(curl_exec($ch), true);
// { token, chatUrl, expiresAt }

Go

// Go
import ( "bytes"; "encoding/json"; "net/http"; "os" )

body, _ := json.Marshal(map[string]string{
  "userId": userID,
  "displayName": userName,
  "channelId": channelID,
})
req, _ := http.NewRequest("POST", "https://kardocloud.com/v1/me/channels/token", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer " + os.Getenv("KARDOLIVE_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
// decode { token, chatUrl, expiresAt }

curl

curl -X POST https://kardocloud.com/v1/me/channels/token \
  -H "Authorization: Bearer $KARDOLIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_42","displayName":"Yousof","channelId":"chn_xyz"}'
# → { "token": "...", "chatUrl": "wss://chat.kardocloud.com", "expiresAt": "..." }

Step 2a — Drop-in browser widget

The fastest path. Add one element + one script to any HTML page.

<div id="kl-chat"
  data-channel-id="YOUR_CHANNEL_ID"
  data-token-url="/api/kardolive-token"
  data-user-id="user_42"
  data-display-name="Yousof"
></div>
<script src="https://kardocloud.com/widgets/chat.js" defer></script>

Step 2b — SDK (full UI control)

Use the SDK when you want to build your own UI. The browser/mobile client uses the JWT your server minted in Step 1 — never the API key.

// npm install @kardolive/sdk
import { Kardolive } from '@kardolive/sdk';

// Browser / mobile — uses the JWT your server minted (no API key here).
const kl = new Kardolive({ accessToken: jwtFromServer });

// Create a 1:1 channel between two users (idempotent).
const channel = await kl.channels.create({
  type: 'direct',
  memberIds: ['user_42', 'user_99'],
});

// Or a group channel with a name.
const room = await kl.channels.create({
  type: 'group',
  name: 'Order #1234',
  memberIds: ['user_42', 'support_agent_7'],
});

// Open WebSocket — Kardolive returns chatUrl from mintToken; pass token in query.
const ws = new WebSocket(`${chatUrl}/v1/chat/socket?room=${channel.id}&token=${jwtFromServer}`);
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.send(JSON.stringify({ type: 'chat.send', data: { body: 'hello' } }));

Step 3 — Webhook event subscription

// Register a webhook endpoint (one-time) and Kardolive POSTs to it.
const hook = await kl.webhooks.create({
  url: 'https://your-app.example.com/kardolive/events',
  events: ['chat.message.created', 'channel.member.joined', 'channel.member.left'],
});

See Webhooks for the full event catalog, signature verification, and retry semantics.