Skip to main content

Key Concepts

Before diving into the API, here's a quick rundown of the terms and concepts you'll encounter throughout the docs.

Rooms​

A room is a live classroom session. It's where the instructor broadcasts and students watch.

  • Each room has a unique roomId that you define (like math-101 or session-2024-01-15)
  • Rooms must be created via the Create Room API before participants can join
  • A room can have multiple teachers, moderators, and students
  • When a teacher ends the class, the room closes for everyone

Think of it like a Zoom meeting, but optimized for the one-to-many education scenario.

{
  "roomId": "math-101",
  "roomName": "Introduction to Algebra",
  "roomDescription": "Covering chapters 1-3"
}

Participants​

A participant is anyone in a room—instructor or student.

Every participant has:

  • A name that's displayed to others
  • A uid for unique identification
  • A role that determines their permissions
  • An optional photo for their avatar
{
  "participant": {
    "uid": "student-456",
    "name": "Jane Smith",
    "role": "STUDENT",
    "photoURL": "https://example.com/jane.jpg"
  }
}

Roles​

There are three roles in Verriflo:

RoleWhat They Can Do
TEACHERPublish video/audio, screen share, control recordings, manage participants, end the class
MODERATORSame as teacher, but can't end the class or start recordings
STUDENTWatch the stream, raise hand, participate in polls
ADMINFull control over the room and settings

Multiple teachers can be in a room at the same time.

Tokens​

A token is a short-lived credential that lets a participant join a room.

When you call our API to join a class, we return:

  • A token (used for auth purposes)
  • An iframeUrl (used for web iframe embedding)
  • An expiresAt timestamp
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "iframeUrl": "https://live.verriflo.com/iframe/live?token=...",
    "expiresAt": "2024-12-31T23:59:59.000Z"
  }
}
Security Note

Generate tokens server-side, not in your frontend. Your Organization ID should never be exposed to end users.

Tracks​

A track is a single media stream—either audio or video.

When an instructor joins:

  • They publish a video track (their camera)
  • They publish an audio track (their microphone)
  • Optionally, they publish a screen share track

Students subscribe to these tracks. Our infrastructure handles the subscription automatically—students don't need to request specific tracks.

In the Flutter SDK, you'll see events like trackSubscribed and trackUnsubscribed when streams become available or stop.

Organizations​

An organization is your account on Verriflo. It's how we track your usage and group your rooms.

Every API call requires your Organization ID in the VF-ORG-ID header. You can find this in your Verriflo Dashboard.

curl -X POST https://api.verriflo.com/v1/room/math-101/join \
  -H "VF-ORG-ID: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '...'

Organizations have:

  • Credits for usage billing
  • Verified domains for security
  • Branding settings (logo, colors) shown in the classroom UI

Classroom States​

During a session, participants move through different states:

idle → connecting → connected → [reconnecting] → ended/kicked
StateMeaning
idleNot connected to any room
connectingJoining the room, establishing connection
connectedActive in the room, receiving streams
reconnectingConnection dropped, attempting to recover
endedInstructor ended the class
kickedRemoved from the room by instructor/moderator
errorSomething went wrong

The Flutter SDK provides callbacks for each state change so you can update your UI accordingly.

Events​

Events are notifications about things happening in the classroom:

  • connected / disconnected — Connection lifecycle
  • participant_joined / participant_left — Roster changes
  • class_ended — Instructor ended the session
  • participant_removed — Someone was kicked
  • recording_started / recording_stopped — Recording state
  • quality_changed — Video quality adjusted

On the web (iframe embedding), these arrive as postMessage events. In Flutter, they come through the onEvent callback.

Recordings​

When enabled, we capture the live session for later playback.

  • Recordings start when the instructor clicks "Record" (or via API)
  • They're processed in real-time alongside the live stream
  • Download URLs are available via API within minutes of the class ending
  • 6-hour window: Recordings are deleted after 6 hours. Download them to your storage if you need them longer.
{
  "success": true,
  "data": {
    "roomId": "math-101",
    "files": [
      {
        "filename": "recording-2024-01-15.mp4",
        "downloadUrl": "https://storage.verriflo.com/...",
        "size": 157286400
      }
    ],
    "expiresIn": "4h 23m"
  }
}

Got the concepts down? Let's build something: