Integration Documentation

// Node.js — using 'jose'
import * as jose from "jose";

const secret = new TextEncoder().encode(process.env.PROJECT_M_SECRET_KEY);

export async function signChatToken(user) {
  return await new jose.SignJWT({
    name: user.fullName,
    email: user.email,
    avatar_url: user.avatarUrl,
  })
    .setProtectedHeader({ alg: "HS256" })
    .setSubject(String(user.id))    // your internal user ID
    .setIssuedAt()
    .setExpirationTime("2h")
    .sign(secret);
}

<!-- Add the SDK script before the closing </body> tag -->
<script src="https://cdn.opiniom.io/sdk/v1.js"></script>

<script>
  // Fetch the JWT from your backend, then init
  fetch("/api/chat-token")
    .then((r) => r.json())
    .then((data) => {
      OpinioM.init({
        publicKey: "ok_live_your_public_key",
        token: data.token,
      });
    });
</script>

import { useEffect, useState } from "react";
import { OpinioMChat, ChatWidget } from "@opiniom/react";

export function App() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    fetch("/api/chat-token", { credentials: "include" })
      .then((r) => r.json())
      .then((data) => setToken(data.token));
  }, []);

  if (!token) return null;

  return (
    <OpinioMChat publicKey="ok_live_your_public_key" token={token}>
      <ChatWidget />
    </OpinioMChat>
  );
}

import * as jose from "jose";

const secret = new TextEncoder().encode(process.env.PROJECT_M_SECRET_KEY);

const token = await new jose.SignJWT({
  name: "Alice Johnson",
  email: "alice@yourapp.com",
  avatar_url: "https://yourapp.com/avatars/alice.png",
})
  .setProtectedHeader({ alg: "HS256" })
  .setSubject("user_42")
  .setIssuedAt()
  .setExpirationTime("2h")
  .sign(secret);

import jwt from "jsonwebtoken";

const token = jwt.sign(
  {
    sub: "user_42",
    name: "Alice Johnson",
    email: "alice@yourapp.com",
    avatar_url: "https://yourapp.com/avatars/alice.png",
  },
  process.env.PROJECT_M_SECRET_KEY,
  { algorithm: "HS256", expiresIn: "2h" }
);

import jwt
import time
import os

token = jwt.encode(
    {
        "sub": "user_42",
        "name": "Alice Johnson",
        "email": "alice@yourapp.com",
        "avatar_url": "https://yourapp.com/avatars/alice.png",
        "iat": int(time.time()),
        "exp": int(time.time()) + 7200,
    },
    os.environ["PROJECT_M_SECRET_KEY"],
    algorithm="HS256",
)

require "jwt"

payload = {
  sub: "user_42",
  name: "Alice Johnson",
  email: "alice@yourapp.com",
  avatar_url: "https://yourapp.com/avatars/alice.png",
  iat: Time.now.to_i,
  exp: Time.now.to_i + 7200
}

token = JWT.encode(payload, ENV["PROJECT_M_SECRET_KEY"], "HS256")

import (
    "os"
    "time"
    "github.com/golang-jwt/jwt/v5"
)

token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
    "sub":        "user_42",
    "name":       "Alice Johnson",
    "email":      "alice@yourapp.com",
    "avatar_url": "https://yourapp.com/avatars/alice.png",
    "iat":        time.Now().Unix(),
    "exp":        time.Now().Add(2 * time.Hour).Unix(),
})

signed, err := token.SignedString([]byte(os.Getenv("PROJECT_M_SECRET_KEY")))

<?php
use Firebase\JWT\JWT;

$payload = [
    "sub"        => "user_42",
    "name"       => "Alice Johnson",
    "email"      => "alice@yourapp.com",
    "avatar_url" => "https://yourapp.com/avatars/alice.png",
    "iat"        => time(),
    "exp"        => time() + 7200,
];

$token = JWT::encode($payload, $_ENV["PROJECT_M_SECRET_KEY"], "HS256");

<script src="https://cdn.opiniom.io/sdk/v1.js"></script>

npm install @projectm/sdk @opiniom/react

OpinioM.init({
  publicKey: "ok_live_your_public_key",
  token: jwtFromYourBackend,
  container: "#chat-container",
  onReady: () => console.log("Chat ready"),
  onError: (err) => console.error("Chat error:", err),
  onMessage: (msg) => console.log("New message:", msg),
});

// Programmatic methods
OpinioM.open();              // Open the chat panel
OpinioM.close();             // Close the chat panel
OpinioM.toggle();            // Toggle open/close
OpinioM.openConversation("conv_abc123");  // Jump to a specific conversation
OpinioM.sendMessage("conv_abc123", "Hello!");
OpinioM.destroy();           // Tear down the widget

import { useEffect, useState } from "react";
import { OpinioMChat, ChatWidget, useChatClient } from "@opiniom/react";

function App() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    fetch("/api/chat-token", { credentials: "include" })
      .then((r) => r.json())
      .then((data) => setToken(data.token));
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <OpinioMChat publicKey="ok_live_your_public_key" token={token}>
      <YourApp />
      <ChatWidget />
    </OpinioMChat>
  );
}

// Use the chat client from any child component
function ChatButton() {
  const chat = useChatClient();
  return <button onClick={() => chat.open()}>Open chat</button>;
}

<OpinioMChat
  publicKey="ok_live_your_public_key"
  getToken={async () => {
    const res = await fetch("/api/chat-token", { credentials: "include" });
    const data = await res.json();
    return data.token;
  }}
>
  <ChatWidget />
</OpinioMChat>

import { OpinioMProvider } from "@opiniom/react";

function App() {
  return (
    <OpinioMProvider
      projectKey="ok_live_YOUR_KEY"
      getToken={async () => {
        const res = await fetch("/api/chat-token", { credentials: "include" });
        return (await res.json()).jwt;
      }}
    >
      <YourCustomChatUI />
    </OpinioMProvider>
  );
}

import { useState, useEffect, useRef } from "react";
import {
  OpinioMProvider,
  useConnectionStatus,
  useConversations,
  useMessages,
  useTyping,
  useUnreadByConversation,
  useSendMessage,
  useSetTyping,
  useMarkRead,
  useCurrentUser,
} from "@opiniom/react";

// ─── App shell ─────────────────────────────────────────────

export default function App() {
  return (
    <OpinioMProvider
      projectKey="ok_live_YOUR_KEY"
      getToken={async () => {
        const res = await fetch("/api/chat-token", { credentials: "include" });
        return (await res.json()).jwt;
      }}
    >
      <ChatApp />
    </OpinioMProvider>
  );
}

function ChatApp() {
  const status = useConnectionStatus();
  const [activeId, setActiveId] = useState(null);

  if (status === "connecting" || status === "authenticating") {
    return <div>Connecting to chat...</div>;
  }

  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <Sidebar activeId={activeId} onSelect={setActiveId} />
      {activeId ? (
        <Thread conversationId={activeId} />
      ) : (
        <div style={{ flex: 1, display: "grid", placeItems: "center" }}>
          Select a conversation
        </div>
      )}
    </div>
  );
}

// ─── Sidebar ───────────────────────────────────────────────

// Conversations are created by your app (backend or your own UI logic),
// not by end-users in the chat interface. The sidebar just renders
// whatever conversations already exist for the current user.

function Sidebar({ activeId, onSelect }) {
  const conversations = useConversations();
  const unread = useUnreadByConversation();

  return (
    <aside style={{ width: 280, borderRight: "1px solid #e5e5e5", overflow: "auto" }}>
      {conversations.map((conv) => (
        <div key={conv.id} onClick={() => onSelect(conv.id)}>
          <span>{conv.title || "Untitled"}</span>
          {(unread[conv.id] ?? 0) > 0 && <span className="badge">{unread[conv.id]}</span>}
        </div>
      ))}
    </aside>
  );
}

// ─── Thread ────────────────────────────────────────────────

function Thread({ conversationId }) {
  const { messages, loadMore, hasMore, isLoading } = useMessages(conversationId);
  const typingUsers = useTyping(conversationId);
  const { markRead } = useMarkRead(conversationId);
  const user = useCurrentUser();

  // Mark newest message as read
  useEffect(() => {
    const last = messages[messages.length - 1];
    if (last) markRead(last.id);
  }, [messages, markRead]);

  return (
    <main style={{ flex: 1, display: "flex", flexDirection: "column" }}>
      <div style={{ flex: 1, overflow: "auto", padding: 16 }}>
        {hasMore && <button onClick={loadMore}>{isLoading ? "Loading..." : "Load more"}</button>}
        {messages.map((msg) => (
          <div
            key={msg.id}
            style={{
              textAlign: msg.sender_id === user?.id ? "right" : "left",
              opacity: msg.status === "pending" ? 0.6 : 1,
              marginBottom: 8,
            }}
          >
            <strong>{msg.sender?.name}: </strong>
            {msg.is_deleted ? <em>deleted</em> : msg.content}
            {msg.status === "failed" && <span style={{ color: "red" }}> (failed)</span>}
          </div>
        ))}
        {typingUsers.length > 0 && <div><em>Someone is typing...</em></div>}
      </div>
      <ComposeBar conversationId={conversationId} />
    </main>
  );
}

// ─── Compose bar ───────────────────────────────────────────

function ComposeBar({ conversationId }) {
  const [text, setText] = useState("");
  const { send, isLoading, error } = useSendMessage(conversationId);
  const { onKeystroke, stopTyping } = useSetTyping(conversationId);

  const handleSubmit = async (e) => {
    e.preventDefault();
    if (!text.trim() || isLoading) return;
    await send({ content: text });
    setText("");
    stopTyping();
  };

  return (
    <form onSubmit={handleSubmit} style={{ display: "flex", gap: 8, padding: 16 }}>
      <input
        value={text}
        onChange={(e) => { setText(e.target.value); onKeystroke(); }}
        onBlur={stopTyping}
        placeholder="Type a message..."
        style={{ flex: 1 }}
        onKeyDown={(e) => {
          if (e.key === "Enter" && !e.shiftKey) { e.preventDefault(); handleSubmit(e); }
        }}
      />
      <button type="submit" disabled={isLoading || !text.trim()}>
        {isLoading ? "..." : "Send"}
      </button>
      {error && <span style={{ color: "red" }}>{error.message}</span>}
    </form>
  );
}

import { useSendMessageWithAttachments } from "@opiniom/react";

function ComposerWithFiles({ conversationId }) {
  const [text, setText] = useState("");
  const [files, setFiles] = useState([]);
  const { send, isUploading, isSending, isLoading, error } =
    useSendMessageWithAttachments(conversationId);

  const handleSubmit = async (e) => {
    e.preventDefault();
    await send(text, files.length > 0 ? files : undefined);
    setText("");
    setFiles([]);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <input type="file" multiple onChange={(e) => setFiles(Array.from(e.target.files))} />
      {files.length > 0 && (
        <div>{files.map((f, i) => <span key={i}>{f.name} </span>)}</div>
      )}
      <button disabled={isLoading}>
        {isUploading ? "Uploading..." : isSending ? "Sending..." : "Send"}
      </button>
      {error && <p style={{ color: "red" }}>{error.message}</p>}
    </form>
  );
}

import { useReactions, useAddReaction, useRemoveReaction, useCurrentUser } from "@opiniom/react";

function ReactionBar({ messageId }) {
  const reactions = useReactions(messageId);
  const user = useCurrentUser();
  const { addReaction } = useAddReaction();
  const { removeReaction } = useRemoveReaction();

  const toggle = (emoji) => {
    const users = reactions[emoji] ?? [];
    if (user && users.includes(user.id)) {
      removeReaction(messageId, emoji);
    } else {
      addReaction(messageId, emoji);
    }
  };

  return (
    <div style={{ display: "flex", gap: 4 }}>
      {Object.entries(reactions).map(([emoji, userIds]) => (
        <button
          key={emoji}
          onClick={() => toggle(emoji)}
          style={{ fontWeight: userIds.includes(user?.id) ? "bold" : "normal" }}
        >
          {emoji} {userIds.length}
        </button>
      ))}
      <button onClick={() => addReaction(messageId, "👍")}>+</button>
    </div>
  );
}

import { useChatClient } from "@opiniom/react";
import { useEffect } from "react";

function NotificationListener() {
  const client = useChatClient();

  useEffect(() => {
    if (!client) return;
    const unsub = client.on("message:new", (message) => {
      if (message.sender_id !== client.user?.id) {
        new Notification(message.sender?.name + ": " + message.content);
      }
    });
    return unsub;
  }, [client]);

  return null;
}

// Available events:
// ready, message:new, message:updated, message:deleted,
// reaction:added, reaction:removed, typing:update,
// presence:changed, unread:changed, connection:changed,
// auth:required, error

import { createClient } from "@opiniom/core";

const client = await createClient({
  projectKey: "ok_live_YOUR_KEY",
  jwt: yourJwt,
});

// Subscribe to events
client.on("message:new", (msg) => { /* update your UI */ });
client.on("typing:update", (data) => { /* show indicator */ });
client.on("presence:changed", (state) => { /* update status */ });

// Perform actions
await client.sendMessage(conversationId, { content: "Hello!" });
await client.createConversation({ type: "direct", member_ids: ["user_123"] });
client.setTyping(conversationId, true);
client.markRead(conversationId, messageId);

// Get current state
const conversations = client.listConversations();
const messages = client.getMessages(conversationId);

curl -X POST https://api.opiniom.io/api/v1/sdk/init \
  -H "X-Public-Key: ok_live_your_public_key" \
  -H "Authorization: Bearer <jwt-signed-by-your-backend>"

# Response:
# {
#   "success": true,
#   "data": {
#     "session_token": "eyJ...",
#     "user_id": "ext_user_42",
#     "widget_config": { ... },
#     "project_name": "My Chat App"
#   }
# }

import { io } from "socket.io-client";

const socket = io("https://api.opiniom.io", {
  path: "/ws",
  auth: { token: sessionToken },  // From step 1
});

socket.on("connect", () => {
  console.log("Connected:", socket.id);
});

socket.on("connect_error", (err) => {
  console.error("Auth failed:", err.message);
});

// Send a message
socket.emit("message:send", {
  conversation_id: "conv_abc123",
  content: "Hello, world!",
}, (response) => {
  if (response.error) {
    console.error("Send failed:", response.error);
  } else {
    console.log("Message sent:", response.data);
  }
});

// Listen for incoming messages
socket.on("message:new", (msg) => {
  console.log(`${msg.sender.name}: ${msg.content}`);
});

{
  "id": "evt_01HNZF7K2P3B4Q5R6S7T8U9V",
  "type": "message.created",
  "created_at": "2026-04-06T12:00:00Z",
  "project_id": "proj_abc123",
  "data": {
    "message_id": "msg_xyz789",
    "conversation_id": "conv_abc123",
    "sender_id": "ext_user_42",
    "content": "Hello!",
    "created_at": "2026-04-06T12:00:00Z"
  }
}

// reaction.added
{
  "data": {
    "message_id": "msg_xyz789",
    "user_id": "ext_user_42",
    "emoji": "👍",
    "reacted_at": "2026-04-06T12:00:05Z"
  }
}

// member.joined
{
  "data": {
    "conversation_id": "conv_abc123",
    "user_id": "ext_user_42",
    "joined_at": "2026-04-06T11:59:00Z"
  }
}

// user.presence.changed
{
  "data": {
    "user_id": "ext_user_42",
    "status": "online",
    "last_seen_at": "2026-04-06T12:00:00Z"
  }
}

import express from "express";
import crypto from "node:crypto";

const app = express();

// IMPORTANT: capture the raw body, not the parsed JSON
app.use("/webhooks/projectm", express.raw({ type: "application/json" }));

app.post("/webhooks/projectm", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = req.body;  // Raw Buffer

  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.PROJECT_M_WEBHOOK_SECRET)
    .update(body)
    .digest("hex");

  // Use timing-safe comparison to prevent timing attacks
  const valid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );

  if (!valid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(body.toString());
  console.log("Received:", event.type, event.id);

  // Acknowledge immediately, process async
  res.status(200).send("OK");

  // Process the event in the background
  handleEvent(event).catch(console.error);
});

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["PROJECT_M_WEBHOOK_SECRET"].encode()

@app.route("/webhooks/projectm", methods=["POST"])
def webhook():
    signature = request.headers.get("X-Signature", "")
    body = request.get_data()  # raw bytes

    expected = "sha256=" + hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.get_json()
    print(f"Received: {event['type']} {event['id']}")

    # Process async / enqueue a job, then return 200 fast
    return "OK", 200

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def projectm
    signature = request.headers["X-Signature"]
    body = request.raw_post

    expected = "sha256=" + OpenSSL::HMAC.hexdigest(
      "SHA256",
      ENV["PROJECT_M_WEBHOOK_SECRET"],
      body
    )

    unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
      head :unauthorized and return
    end

    event = JSON.parse(body)
    Rails.logger.info("Received: #{event['type']} #{event['id']}")

    # Enqueue async processing
    head :ok
  end
end

# Start your local server
npm run dev

# In another terminal, expose it via ngrok
ngrok http 3000

# Use the https://...ngrok-free.app URL when creating the webhook

<div id="my-chat-container" style="width: 100%; height: 600px;"></div>

<script>
  OpinioM.init({
    publicKey: "ok_live_your_public_key",
    token: jwtFromYourBackend,
    container: "#my-chat-container",
  });
</script>