Skip to main content
Version: 0.20.0

Testing with the Sandbox API

How-to Guide - Use Sandbox API to test your Fishjam integration quickly without a backend

The Sandbox API is a development tool that lets you create rooms and peers for testing without setting up your own backend server. This guide shows you how to use it effectively.

Prerequisites​

Step 1: Get your Fishjam ID​

  1. Log in to Fishjam Dashboard
  2. Navigate to your Sandbox Environment
  3. Copy your Fishjam ID
note

FISHJAM_ID is your unique sandbox identifier. Anyone who knows this ID can join your rooms, so keep it secure during development.

Step 2: Create a room and get peer tokens​

With the useSandbox hook​

import { useSandbox } from '@fishjam-cloud/react-native-client';

// ...

const { getSandboxPeerToken } = useSandbox({ fishjamId: FISHJAM_ID });
const peerToken = await getSandboxPeerToken(roomName, peerName);

Required parameters​

  • roomName - Name of the room to create/join
  • peerName - Name for the peer joining the room

Optional parameters​

  • roomType - Type of room to create (defaults to conference)

Room types available​

  • conference - For video/audio conferencing (default)
  • audio-only - For audio-only conferencing
  • livestream - For one-to-many video/audio streaming

Step 3: Handle the response​

The Sandbox API returns a JSON response with connection details:

{
  "peerToken": "<PEER_TOKEN>",
  "url": "wss://fishjam.io/api/v1/connect/${YOUR_APP_UUID}",
  "room": {
    "id": "<ROOM_ID>",
    "name": "foo"
  },
  "peer": {
    "id": "<PEER_ID>",
    "name": "bar"
  }
}

Step 4: Use the tokens in your client app​

Below are examples on how to use tokens from the Sandbox API in your frontend applications:

import { useSandbox } from "@fishjam-cloud/react-native-client";

export default function TestScreen() {
  const [peerToken, setPeerToken] = useState<string | null>(null);
  const { getSandboxPeerToken } = useSandbox({ fishjamId: FISHJAM_ID });

  useEffect(() => {
    const fetchPeerToken = async () => {
      try {
        const token = await getSandboxPeerToken(roomName, peerName);
        setPeerToken(token);
      } catch (error) {
        console.error("Failed to create room:", error);
      }
    };

    fetchPeerToken();
  }, []);

  if (!peerToken) {
    return <Text>Creating room...</Text>;
  }

  return (
    <RoomView peerToken={peerToken} />
  );
}

Step 5: Test different room types​

Testing audio-only rooms​

const audioOnlyUrl = await getSandboxPeerToken(
  "audioTest",
  "user1",
  "audio_only",
);

Testing livestream rooms​


const livestreamName = "livestream1";
// For the streamer
const streamerUrl = await getSandboxLivestream(livestreamName);

// For viewers, you need a viewer token (different endpoint)
const viewerTokenUrl = await getSandboxViewerToken(livestreamName);

Step 6: Handle multiple peers​

To test with multiple participants, create multiple peer tokens with different peer names:

// First peer
const peer1Response = await getSandboxPeerToken("multiTest", "alice");

// Second peer
const peer2Response = await getSandboxPeerToken("multiTest", "bob");

Both peers will join the same room (multiTest) and can communicate with each other.

Common testing patterns​

Pattern 1: Random room names for isolation​

const roomName = `test_${Math.random().toString(36).substring(7)}`;
const peerName = `user_${Date.now()}`;

Pattern 2: Consistent naming for repeated tests​

const roomName = "development-room";
const peerName = `developer_1`;

Pattern 3: Feature-specific room names​

const roomName = `screenshare-test-${Date.now()}`;
const roomName = `audio-only-test`;
const roomName = `livestream-demo`;

Troubleshooting​

Issue: Room not found errors​

Problem: Rooms might not persist between requests.

Solution: Always create rooms fresh for each test session.

Issue: Connection failures​

Problem: Invalid Fishjam ID or network issues.

Solution:

  1. Verify your Fishjam ID in the Fishjam Dashboard
  2. Check network connectivity
  3. Ensure you're using the sandbox environment

Security reminder​

danger

The Sandbox API is not safe for production!

  • No authentication required
  • Anyone with your Fishjam ID can join rooms
  • Identical room/peer names get the same tokens
  • No rate limiting or abuse protection

Only use the Sandbox API for development and testing.

Resetting your app​

If you need to reset your Sandbox API:

  1. Go to Fishjam Dashboard
  2. Click Settings
  3. Click Reset App
  4. Get your new Fishjam ID

This will invalidate all existing tokens (including the management token!) and give you a fresh sandbox environment.

Next steps​

Once you've tested your integration with the Sandbox API:

For production deployment: