Set up your server

Install the SDK

Install the SDK for the language of your choice. We provide libraries for Node and Python.
It's also possible to use the bare REST API, in this case you can skip this step.

NPM

npm install @fishjam-cloud/js-server-sdk

YARN

yarn add @fishjam-cloud/js-server-sdk

PIP

pip install fishjam-server-sdk

POETRY

poetry add fishjam-server-sdk

Setup your client

Let's setup everything you need to start communicating with a Fishjam instance.
First of all, view your app in the Fishjam developer panel and copy your Fishjam URL and the Management Token.
They are required to proceed. Now, we are ready to dive into the code.

Typescript

import { FishjamClient } from '@fishjam-cloud/js-server-sdk';

const fishjamUrl = process.env.FISHJAM_URL;
const managementToken = process.env.FISHJAM_MANAGEMENT_TOKEN;

const fishjamClient = new FishjamClient({ fishjamUrl, managementToken });

Python

import os
from fishjam import FishjamClient

fishjam_url = os.environ["FISHJAM_URL"]
management_token = os.environ["FISHJAM_MANAGEMENT_TOKEN"]

fishjam_client = FishjamClient(fishjam_url, management_token)

cURL

AUTH_HEADER="Authorization: Bearer $FISHJAM_MANAGEMENT_TOKEN"

curl -i "$FISHJAM_URL/room" -H $AUTH_HEADER

Managing rooms

Create a room to get the roomId and be able to start adding peers.

Typescript

const createdRoom = await fishjamClient.createRoom();

const theSameRoom = await fishjamClient.getRoom(createdRoom.id);

await fishjamClient.deleteRoom(theSameRoom.id)

// puff, it's gone!

Python

created_room = fishjam_client.create_room()

the_same_room = fishjam_client.get_room(created_room.id)

fishjam_client.delete_room(the_same_room.id)

# puff, it's gone!

cURL

curl -X POST "$FISHJAM_URL/room" -H $AUTH_HEADER

curl "$FISHJAM_URL/room/$ROOM_ID" -H $AUTH_HEADER

curl -X DELETE "$FISHJAM_URL/room/$ROOM_ID" -H $AUTH_HEADER

# puff, it's gone!

Managing peers

Create a peer to obtain the peer token allowing your user to join the room. At any time you can terminate user's access by deleting the peer.

Typescript

const { peer, peerToken } = await fishjamClient.createPeer(roomId);

await fishjamClient.deletePeer(roomId, peer.id);

Python

peer, token = fishjam_client.create_peer(room_id)

fishjam_url.delete_peer(room_id, peer.id)

cURL

curl -X POST "$FISHJAM_URL/room/$ROOM_ID/peer" -H $AUTH_HEADER

curl -X DELETE "$FISHJAM_URL/room/$ROOM_ID/peer/$PEER_ID" -H $AUTH_HEADER

Listening to events

Fishjam instance is a stateful server that is emitting messages upon certain events.
You can listen for those messages and react as you prefer.
There are two options to obtain these.

Webhooks

Simply pass the your webhook url as a webhookUrl parameter when creating a room.

Typescript

const webhookUrl = "https://example.com";
await fishjamClient.createRoom({ webhookUrl });

Python

from fishjam import RoomOptions

options = RoomOptions(webhook_url="https://example.com")

fishjam_client.create_room(options)

cURL

PAYLOAD='{"webhookUrl": "https://example.com" }'
curl -X POST -H "Content-Type: application/json" -H $AUTH_HEADER --data $PAYLOAD  "$FISHJAM_URL/room"

SDK Notifier

Our SDKs come equipped with a Notifier allowing you to subscribe for messages. It sets up a websocket connection with a Fishjam instance and provides a simple interface allowing you to handle messages.

Typescript

import { FishjamWSNotifier } from '@fishjam-cloud/js-server-sdk';

const onClose = console.log;
const onError = console.error;
const onConnectionFailed = console.error;

const fishjamNotifier = new FishjamWSNotifier({ fishjamUrl, managementToken }, onError, onClose, onConnectionFailed);

fishjamNotifier.on('roomCreated', console.log);

Python

import asyncio
from fishjam import FishjamNotifier

notifier = FishjamNotifier(server_address=fishjam_url, server_api_token=management_token)

@notifier.on_server_notification
def handle_notification(notification):
    match notification:
        case ServerMessageRoomCreated():
            print(notification)
        case _:
            ...

async def run_notifier():
  notifier_task = asyncio.create_task(notifier.connect())

  # Wait for notifier to be ready to receive messages
  await notifier.wait_ready()

  await notifier_task

asyncio.run(run_notifier())