imMail Meet Embedding

The imMail Meet is a video conferencing web software compatible with WebRTC.

The main goal here is to show you step by step how you can embed a video conference session in your own application.

Example Project

If you like some code example you can go to https://github.com/immail/meet-embedding and take a look at a simple project built in Node JS.

Authentication

For the imMail API we currently have two different flows of authentication.

• User Login: Generate a JWT Token by providing a valid username (email) and password.
  • https://docs.immail.ca/#req_917d786a32cc445db817b328eab9bddb
• Client Credentials: Generate a JWT Token by providing an API KEY.
  • https://docs.immail.ca/#req_0f8f42c457c3442e97ada4e52e39b2be

We strongly recommend you to use the Client Credentials flow. Do not expose the API Key in your client-side (frontend).

Embedding the meeting session on your HTML page:

Insert the snippet of code in your HTML page:

<iframe
    style="border: none"
    allow="camera; microphone; display-capture"
    allowfullscreen="true"
    webkitallowfullscreen="true"
    mozallowfullscreen="true"
    src="{ MEETING_URL }?first_name={ FIRST_NAME }&last_name={ LAST_NAME }&jwt={ JWT }&start_recording=true"
    width="100%" height="500">
  </iframe>

In order to compose the SRC attribute of the IFRAME you have to set some important params:

• MEETING_URL (Required):
  • For the meeting’s URL go to https://docs.immail.ca/#req_8625e52fab6244bc907c11c85568b6b6 and check out the API for creating/scheduling a new meeting.
  • Once you have created a new meeting you will get the meeting name from the request-response.
    Use the meeting’s URL base ( https://web.immail.ca/meet/ + name)

E.g.: https://web.immail.ca/meet/19wda8xxxs8eas8q

• jwt (required):
  • JWT Token is necessary for users authentication on the meeting session. The JWT Token also is responsible to indicate who in the session will be the moderator and who will be a simple guest.
  • For the JWT Token go to https://docs.immail.ca/#req_e7154ff832204b6c826e9082c46ebb62 and check out the API for generating meeting participants JWT Token.

Optional configurations

You can provide some optional configurations as query parameters in order to enable/disable initials features or show/hide some interface elements.

Configuration options

Name	Description	Default value
first_name	Set the first name of the participant	null
last_name	Set the last name of the participant	null
start_recording	Automatically start a recording on the participant’s first entry.	false
startWithAudioMuted	Start meeting with audio muted.	true
startWithVideoMuted	Start meeting with video muted	false
fileRecordingsEnabled	Disable the file recording option if false.	true
hideLogo	Hide imMail Meet logo	false
hideDesktopLink	Hide Open imMail Meet Desktop link on pre-meeting page	false
hideButtons	Provide an array of option buttons you want to hide. E.g.: ?hideButtons=invite,hangup Button options available for hiding: camera, chat, closedcaptions, desktop, download, embedmeeting, filmstrip, fullscreen, hangup, invite, livestreaming, microphone, mute-everyone, mute-video-everyone, participants-pane, raisehand, recording, security, select-background, settings, sharedvideo, shortcuts, stats, tileview, toggle-camera, videoquality, white-board	[]

Interface configuration options

Name	Description	Default value
HIDE_INVITE_MORE_HEADER	Hide the invite more participants button located on the top middle of the screen.	false

Events

You can pass events to the Iframe using the method postMessage() to execute a few real-time actions.

• stopRecording: Stops a current video recording session.
  E.g.:

// Get the iframe element via javascript
const iframe = document.getElementById('iframeMeet');

// Emit the event to the iframe
iframe.contentWindow.postMessage({type: 'stopRecording'}, '*');

• hangup: Ends a current video conference session.
  E.g.:

// Get the iframe element via javascript
const iframe = document.getElementById('iframeMeet');

// Emit the event to the iframe
iframe.contentWindow.postMessage({type: 'hangup'}, '*');

Getting the history of meeting sessions:

Meeting recordings:

You can get info about the recorded meeting and you can download the file. For recorded meeting file download, follow the steps below:

• Go to the API ( https://docs.immail.ca/#req_e4e970929d974e0f9d139286bac71180 ) and providing the VIDEO ROOM ID ( you got this from the meeting creation ) list the sessions related to this video room ( it is important to know that each created/scheduled video room can have one or more room sessions ).
• After you request the video room sessions list from the API, you will have access to a JSON response like this:

{
  total_completed: 1,
  total_in_progress: 1,
  total_row: 2,
  data: [
    {
      _id: '6094e661deec78bbbf717dsab',
      date: '2021-04-29T03:24:34.550Z',
      status: 'IN-PROGRESS',
      duration: 63,
      occupants: [
        { profile_id: '608a2a5c79dea68d3a4da353', name: 'Curtis' },
        { profile_id: '608a2a5c79dea68d3a4da354', name: 'Blanca' },
        { profile_id: '608a2a5c79dea68d3a4da34c', name: 'Buford' }
      ],
      video_room: {
        _id: '608b2eb8f793972a916714cb',
        name: '75769f9a-1f49',
        topic: 'Some meeting'
      },
      recording_files: [
        {
          _id: '6094e661deec78bbbf71716b',
          name: '6th.msf',
          size: 132602068,
          created_at: '2021-05-07T07:04:02.744Z'
        }
      ]
    }
  ]
}

• Find the recordings_files close to the end of the array. This is the list of the recorded video files during the video session ( Notice that one or more files can be generated if the moderator stop and restart the recording process )
• Get _id (this is the file id) and go to Download Files API (https://docs.immail.ca/#req_c57bbfeceec943069a5cb1dfbd21492f)

Meeting messages history:

You can get the meeting messages history by providing the VIDEO ROOM SESSION ID.

• Go to the API ( https://docs.immail.ca/#req_e4e970929d974e0f9d139286bac71180 ) and provide the VIDEO ROOM ID ( you got this from the meeting creation ) to list the sessions related to this video room ( it is important to know that each created/scheduled video room can have one or more rooms sessions ).
• After you request the video room sessions list from the API, you will have access to a JSON response like this:

{
  total_completed: 1,
  total_in_progress: 1,
  total_row: 2,
  data: [
    {
      _id: '6094e661deec78bbbf717dsab', <<<< VIDEO ROOM SESSION ID
      date: '2021-04-29T03:24:34.550Z',
      status: 'IN-PROGRESS',
      duration: 63,
      occupants: [
        { profile_id: '608a2a5c79dea68d3a4da353', name: 'Curtis' },
        { profile_id: '608a2a5c79dea68d3a4da354', name: 'Blanca' },
        { profile_id: '608a2a5c79dea68d3a4da34c', name: 'Buford' }
      ],
      video_room: {
        _id: '608b2eb8f793972a916714cb',
        name: '75769f9a-1f49',
        topic: 'Some meeting'
      },
      recording_files: [
        {
          _id: '6094e661deec78bbbf71716b',
          name: '6th.msf',
          size: 132602068,
          created_at: '2021-05-07T07:04:02.744Z'
        }
      ]
    }
  ]
}

• Find the _id ( This is the VIDEO ROOM SESSION ID). Take a look at the snippet above indicated by this mark ( <<<< VIDEO ROOM SESSION ID )
• Go to the Messages History API (https://docs.immail.ca/#req_b5b9fbcde84847088f59211787abb0b2) and provide the VIDEO ROOM SESSION ID to get the message history.