Developer Documentation

Admin SDK

For trusted server-to-server communication. Requires your secret API key.

Installation

Install the Paanj Admin SDK for your server-side environment.

npm install @paanj/admin @paanj/chat-admin

Initialization & Connection

Initialize the client with your secret API key. This is a one-time setup for your server.

import { PaanjAdmin } from '@paanj/admin';
import { AdminChat } from '@paanj/chat-admin';

const admin = new PaanjAdmin('YOUR_SECRET_API_KEY');
await admin.connect();

const chat = new AdminChat(admin);

(async () => {
  try {
    // Listen to events
    chat.messages.onCreate((msg) => console.log('New message:', msg));
    console.log('Successfully connected to Paanj!');
  } catch (error) {
    console.error('Failed to connect:', error);
  }
})();

Create a Participant

Provision a new participant (user) in your system.

(async () => {
  const newUser = await chat.users.create({
    email: 'john@example.com',
    name: 'John Doe',
    userData: { avatar: 'https://example.com/avatar.png' }
  });
  console.log('Participant created:', newUser.userId);
})();

Update a Participant

Update an existing participant's data.

(async () => {
  await chat.users.update('user-123', {
    email: 'newemail@example.com',
    userData: {
        name: 'Johnathan Doe',
        avatar: 'https://example.com/new-avatar.png',
        status: 'online'
    }
  });
  console.log('Participant updated successfully.');
})();

Delete a Participant

Permanently delete a participant from your system. This action cannot be undone.

(async () => {
  await chat.users.delete('user-123');
  console.log('Participant deleted successfully.');
})();

Create a Conversation

Create a new conversation for your participants.

(async () => {
  const groupChat = await chat.conversations.create({
    name: 'Project Phoenix',
    memberIds: ['user-123', 'user-456'],
    metadata: { department: 'engineering' }
  });
  console.log('Group chat created:', groupChat.id);
})();

Update a Conversation

Manage participants and their permissions within a conversation.

Add Participants

const conv = chat.conversation('group-abc');
await conv.addParticipant('user-789');

await admin.conversations.update('group-abc', 
    add_participants=[{'id': 'user-789', 'permissions': ['receive']}]
)

err := admin.Conversations.Update("group-abc", paanjrtc.ConversationUpdate{
    AddParticipants: []paanjrtc.ParticipantInfo{
        {ID: "user-789", Permissions: []string{"receive"}},
    },
})

Remove Participants

const conv = chat.conversation('group-abc');
await conv.removeParticipant('user-456');

await admin.conversations.update('group-abc', 
    remove_participants=['user-456']
)

err := admin.Conversations.Update("group-abc", paanjrtc.ConversationUpdate{
    RemoveParticipants: []string{"user-456"},
})

Delete a Conversation

Permanently delete a conversation and all its associated messages. This action cannot be undone.

await chat.conversations.delete('group-abc');

await admin.conversations.delete('group-abc')

err := admin.Conversations.Delete("group-abc")

Manage Blocks

As an admin, you can unilaterally block or unblock communication between any two participants.

Block User

// Block 'user-456' on behalf of 'user-123'
await chat.users('user-123').block('user-456');

# Block 'user-123' from contacting 'user-456'
await admin.participants.block('user-123', 'user-456')

// Block 'user-123' from contacting 'user-456'
err := admin.Participants.Block("user-123", "user-456")

Unblock User

// Allow 'user-456' to contact 'user-123' again
await chat.users('user-123').unblock('user-456');

# Allow 'user-123' to contact 'user-456' again
await admin.participants.unblock('user-123', 'user-456')

// Allow 'user-123' to contact 'user-456' again
err := admin.Participants.Unblock("user-123", "user-456")

Listen for Admin Events

Listen for system-level events to build audit trails, monitoring, or automated workflows.

chat.users.onCreate((user) => {
  console.log('A new participant was created:', user);
});
chat.conversations.onCreate((conversation) => {
  console.log('A new conversation was created:', conversation);
});

@admin.participants.on_create
def handle_participant_created(participant: paanjrtc.Participant):
    print(f"A new participant was created: {participant}")

@admin.conversations.on_create
def handle_conversation_created(conversation: paanjrtc.Conversation):
    print(f"A new conversation was created: {conversation}")

go func() {
    participantChan, _ := admin.Participants.OnCreate()
    for participant := range participantChan {
        log.Printf("A new participant was created: %+v\n", participant)
    }
}()

go func() {
    conversationChan, _ := admin.Conversations.OnCreate()
    for conversation := range conversationChan {
        log.Printf("A new conversation was created: %+v\n", conversation)
    }
}()

Subscribe to a Conversation

Subscribe to all messages sent to a specific conversation. Listen for real-time message events.

(async () => {
  const conversation = chat.conversation('group-abc');
  conversation.onMessage((message) => {
    console.log('New message:', message);
  });
})();

subscription = paanjrtc.Subscription(conversation_id='group-abc')
messages = await admin.messages.subscribe(subscription)
async for message in messages:
    print(f"New message: {message}")

subscription := paanjrtc.Subscription{ConversationID: "group-abc"}
messages, err := admin.Messages.Subscribe(subscription)
for message := range messages {
    log.Printf("New message: %+v\n", message)
}

Send a Message

Send a message to a specific conversation from the admin.

(async () => {
  const conversation = chat.conversation('group-abc');
  await conversation.send('Hello, world!');
  console.log('Message sent successfully.');
})();

Note: The SDK currently only supports sending string content. If you want to send JSON, please stringify it first.

message = paanjrtc.Message(
    conversation_id='group-abc',
    sender_id='admin-system',
    payload='Hello, world!'
)
await admin.messages.send(message)

message := paanjrtc.Message{
    ConversationID: "group-abc",
    SenderID:       "admin-system",
    Payload:        "Hello, world!",
}
err := admin.Messages.Send(message)

Client SDK

For client-side applications. Requires a public API key.

Installation

Install the Paanj Client SDK to build your front-end application.

npm install @paanj/client @paanj/chat-client

Initialization

Initialize the client with your public API key.

import { PaanjClient } from '@paanj/client';
import { ChatClient } from '@paanj/chat-client';

const client = new PaanjClient({
  apiKey: 'YOUR_PUBLIC_API_KEY'
});
const chat = new ChatClient(client);

Authentication

Create an anonymous user to start interacting. This will return a session with an access token.

// Create an anonymous user with private data
// Private data is not stored but sent to webhooks
const session = await client.authenticateAnonymous({
    name: 'John Doe',
    metadata: { email: 'john@example.com' }
}, {
    internalId: 'u_789'
});

console.log('User ID:', session.userId);
console.log('Access Token:', session.accessToken);

Create a Conversation

Create a new conversation. You can add other users by their ID.

// Create a conversation
const conversation = await chat.conversations.create({
  name: 'Team Project',
  participantIds: [
    session.userId, // Add yourself
    'user_456'      // Add another user
  ],
  metadata: { isPrivate: false }
});

// You are automatically subscribed to this conversation
console.log('Conversation created:', conversation.id);

List Conversations

Retrieve a list of conversations you are a member of.

// List conversations with fluent API
const conversations = await chat.conversations.list()
    .limit(10)
    .offset(0);
console.log('Conversations:', conversations);

Real-time Messaging

Connect to the WebSocket server to send and receive messages in real-time.

// Connect to WebSocket
await client.connect();

// Listen for messages globally
chat.conversations.onMessage((msg) => {
    console.log('New message:', msg.content);
    console.log('From User:', msg.senderId);
});

// Send a message
const ctx = chat.conversations(conversation.id);
await ctx.send('Hello, world!');

List Messages

Retrieve message history with a fluent API.

// List messages with fluent API
const messages = await chat.conversations(conversation.id)
    .messages()
    .list()
    .limit(20)
    .page(1);

console.log('History:', messages);

Manage Conversations

Manage conversation membership and settings.

const cnv = chat.conversations(conversation.id);

// Leave a conversation
await cnv.leave();

// List participants
const participants = await cnv.participants().list();
console.log('Participants:', participants);

// Add a participant (if you have permission)
await cnv.participants().add('user_789', 'member');

// Get conversation details
const details = await cnv.get();
console.log('Details:', details);

// Listen for updates
cnv.onUpdate((update) => {
    console.log('Conversation updated:', update);
});

Block and Unblock Users

Users can block other users to prevent unwanted communication.

// Block a user
await chat.users('user_456').block();

// Get
console.log('Blocked users:', blockedUsers);

// Unblock a user
await chat.users('user_456').unblock();