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

• Access to Fishjam Dashboard
• A Sandbox environment set up

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

React Native

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

// ...

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

React

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

// ...

const { getSandboxPeerToken } = useSandbox();
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:

React Native

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} />
  );
}

React

import { FishjamProvider, useConnection, useSandbox } from "@fishjam-cloud/react-client";

function VideoCallComponent() {
  const { joinRoom, peerStatus } = useConnection();
  const { getSandboxPeerToken } = useSandbox();

  const handleJoinRoom = async () => {
    const roomName = "testRoom";
    const peerName = `user_${Date.now()}`;

    try {
      const peerToken = await getSandboxPeerToken(roomName, peerName)
      await joinRoom({ peerToken });
    } catch (error) {
      console.error("Failed to join room:", error);
    }
  };

  const isConnected = peerStatus === "connected";

  return (
    <div>
      {isConnected ? <p>Connected to room!</p> : <button onClick={handleJoinRoom}>Join Room</button>}
    </div>
  );
}

export default function App() {
  return (
    <FishjamProvider>
      <VideoCallComponent />
    </FishjamProvider>
  );
}

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:

• Set up your own backend
• Learn more about the Sandbox API
• Understand security implications

For production deployment:

• How to set up a production server
• How to implement proper authentication