Integrating Rocket.Chat with Pexip Infinity

Rocket.Chat can integrate with Pexip Infinity to allow users to quickly and easily add a Pexip VMR to their chat, enabling any meeting to be held over a secure video conference.

With the Pexip integration, users can:

  • Initiate an instant ad hoc video meeting from their current chat. These are held in single-use VMRs that are created specifically for the meeting and only available for its duration.
  • Schedule a meeting that can be joined from the Rocket.Chat client (in addition to other video devices). These can be held either in a single-use VMR or the user's personal VMR on Pexip Infinity.
  • Use Rocket.Chat's persistent chat feature to allow users to continue to chat in a dedicated discussion room while in a web app conference call.

Network architecture and firewalls

The Pexip integration app is a Rocket.Chat application that is downloaded from the Rocket.Chat Marketplace. It handles all communications and call requests between the Rocket.Chat platform and Pexip Infinity.

How it works

When the user starts a video meeting in Rocket.Chat, the Pexip integration app launches a RocketChat video window or a new browser tab, depending on how the desktop client is configured, and initiates a video call to a Pexip Conferencing Node. This triggers an external policy request from Pexip Infinity to Rocket.Chat and the policy server contained within the Pexip integration app responds with the meeting parameters (service type, themes, alias, PINs and so on) and a single-use VMR is created specifically for the meeting.

In all cases ensure that you have permitted an HTTPS, port 443 connection from the Pexip Infinity Conferencing Nodes to the Rocket.Chat external policy server.

The diagram below summarizes the connectivity required between the components of Pexip Infinity and a Rocket.Chat workspace.

Scheduled meetings

In scheduled meetings, the calendar invitation contains a link for joining via Rocket.Chat which launches the Rocket.Chat client, which in turn launches a Rocket.Chat video window or a new browser tab, depending on how the desktop client is configured, and initiates a video call to the Pexip Conferencing Node that is hosting the VMR. Other invitees can use alternative links (for example, video conferencing endpoints or the Pexip Webapp3) in the same invitation to join the meeting via their preferred video devices.

Note that for scheduled meetings, the launch process is direct from the Rocket.Chat client and does not use external policy.

Assumptions and prerequisites

The deployment instructions assume that you have:

  • Signed up to the Rocket.Chat platform and have access to an Admin account.
  • Performed a basic installation and configuration of Pexip Infinity. Any of Pexip Infinity's deployment models may be used (on-premises, cloud-hosted etc). See installation overview for more information.

  • Your Pexip Infinity platform and configuration must meet the following criteria:

    • Running version 30 or later.
    • Valid certificates and intermediate certificates installed. See Managing TLS and trusted CA certificates for more information about certificates.
    • Only one system location for each Rocket.Chat workspace, but that location can contain multiple Conferencing Nodes.
    • Configured to use Webapp3 by default.
    • Suitable network routability between Rocket.Chat and Pexip Infinity. See Pexip Infinity port usage and firewall guidance for more information.

  • If you are using scheduled meetings, then you must be using as a minimum:

    • Rocket.Chat server 6.0 or later.
    • Client 3.9.4 or later.
    • Rocket.Chat Pexip integration 1.5.0 or later.

Note that there are additional requirements if you also want use persistent chat.

Integration process

The configuration of the Rocket.Chat and the Pexip Infinity installations needs to align precisely (with certain shared configuration values) for the integration to work correctly.

  1. From the Rocket.Chat instance, enable and configure the Pexip App to use Pexip Infinity for video calls. Note that Pexip App is a Rocket.Chat application. For the purpose of this guide, Pexip App is referred to as the Pexip Integration app.

  2. Within Pexip Infinity, create the following:

    • Policy profile: to link Pexip Infinity to the Rocket.Chat external policy server.
    • Event Sink: to monitor conference status.

    • Theme: to apply Rocket.Chat themes or branding.

      Note that changes made to the Pexip Infinity platform take approximately 60 seconds to synchronize.

  3. You have completed the integration process. Log into a Rocket.Chat web browser or Rocket.Chat desktop client and click the handset icon to start a call. For more information see Conference Call User's Guide.
  4. To add scheduled meetings and configure your calendar invitations, follow the Enabling scheduled meetings instructions.
  5. If you want to enable persistent chat you must also follow the instructions in Persistent chat integration.

Configuring the Pexip integration app in Rocket.Chat

You need to configure the Base URL so Rocket.Chat can route calls to the correct Pexip Infinity address.

  1. From the Rocket.Chat instance, enable the Pexip integration app. See the Rocket.Chat Pexip app guide for more information.

  2. Go to the Settings tab and configure the following information:

    • Base URL: https://<FQDN>.

      This FQDN must match the FQDN of your Conferencing Node.

      If you are using multiple Conferencing Nodes, then we recommend setting up a common hostname and associated round robin DNS SRV records. The TLS certificate installed on each Conferencing Node must include this common hostname in addition to the node's individual FQDN. See DNS record examples for more information.

    • API Username and API Password: specify the credentials required to access the external policy server and the event sink. You will need this information when creating a policy profile and adding an event sink.

  3. In the Details tab, the highlighted part of the URL in the GET events and POST events section is required to create a Policy profile and Event Sink.

Configuring a policy profile and an event sink in Pexip Infinity

You only need to create one policy profile and one event sink for each Rocket.Chat workspace.

  1. From the Pexip Infinity Administrator interface, go to Call control > Policy profiles.

  2. Select Add Policy profile and then configure that profile. The options are:

    Option Description
    Name The name used to refer to this policy profile in the Pexip Infinity Administrator interface.
    Description An optional description of the policy profile.
    External policy server
    URL

    Enter the GET URL from the Rocket.Chat-Pexip integration app.

    Do not include the /policy/v1/service/configuration path of the URL.

    Example: https://policy.example.com/api/apps/public/UUID

    Username

    Password

    		 Enter the API Username and API Password from the Rocket.Chat Pexip integration app.
    Service configuration policy
    Enable external service configuration lookup

    Ensure this option is selected.

    The other configuration options are not required for the Rocket.Chat integration.
  3. Select Save.
  4. Go to Platform > Locations.
  5. Select your location and assign the Policy profile.
  6. Go to System > Event Sinks.

  7. Select Add Event sink and configure the event sink. The options are:

    Option Description
    Name The name used to refer to this event sink. Each event sink must have a unique name.
    Description An optional description of this event sink.
    Version Default: Version 2
    URL

    Use the POST URL from the Rocket.Chat-Pexip app configuration.

    Example: https://policy.example.com/api/apps/public/UUID/events
    Username and Password Enter the API Username and API Password from the Rocket.Chat Pexip integration app.
    Verify TLS Ensure this option is selected.
    Location Select all of the possible locations that can handle media for Rocket.Chat calls, including any overflow locations.
  8. Select Save.

Enabling scheduled meetings

To include Rocket.Chat-based invitations in scheduled meetings you need to use Pexip's Secure Scheduler for Exchange feature, and configure your VMR joining instructions template to include the appropriate links for joining via Rocket.Chat.

To enable joining scheduled meetings via Rocket.Chat:

  1. Configure your Pexip Infinity platform in the standard manner to use Secure Scheduler for Exchange. See Pexip Secure Scheduler for Exchange for full details.
  2. Ensure it is configured for personal use VMRs and/or for single-use VMRs as appropriate.

  3. Configure your VMR joining instructions templates to include the appropriate links for joining via Rocket.Chat:

    You need to add the link for Rocket.Chat users to the Personal VMR joining instructions template field and/or Single-use VMR joining instructions template field in your Secure Scheduler for Exchange configuration.

    The link itself takes the format:

    <a href="https://go.rocket.chat/conference?host=rc.pexample.com&path=conference%2F{{numeric_alias}}%3FcallUrl%3Dhttps%253A%252F%252F{{addin_server_domain}}%252Fmybrandingpath%252Fconference%253Fconference%253D{{numeric_alias}}%26callProvider%3DPexip">

    where:

    • rc.pexample.com must be replaced with the FQDN of your Rocket.Chat workspace.
    • mybrandingpath must be replaced with the Path identifier you have set up for your branding path. (If you don't have a branding path then remove %252Fmybrandingpath from the link completely.)

    The href URL must be fully HTML-encoded, for example any "/" path characters must be represented by "%2F" instead, and the callUrl parameter double-encoded e.g. "%252F".

    Here is some example template script that adds the Rocket.Chat link (modify as required, and as described above):

    Copy to clipboard 
    <tr>
      <td class="left-column">
        <img src="https://[your link to Rocket.Chat icon]" width="42" height="42" alt="Rocket.Chat">
      </td>
      <td class="center-column">
        <p>
          <span class="pexip-heading">
            From a Rocket.Chat client:
          </span>
          <br>
          <a href="https://go.rocket.chat/conference?host=rc.pexample.com&path=conference%2F{{numeric_alias}}%3FcallUrl%3Dhttps%253A%252F%252F{{addin_server_domain}}%252Fmybrandingpath%252Fconference%253Fconference%253D{{numeric_alias}}%26callProvider%3DPexip">
          <span class="pexip-info">
             go.rocket.chat{{alias}}
          </span>
          </a>
        </p>
      </td>
      <td class="pexip-cell"/>
    </tr>

    Pexip Webapp3 links

    If your template also includes links for the Pexip Webapp3, they should take the following format:

    <a href="https://{{addin_server_domain}}/mybrandingpath/m/{{numeric_alias}}">

    where mybrandingpath should be replaced with the Path identifier of your branding path.

    If you don't have a branding path (you are using the default branding), the link should take the following format:

    <a href="https://{{addin_server_domain}}/webapp/m/{{numeric_alias}}">

Changing the branding and themes of a video conference in Pexip Infinity

The look and feel of the web app and the Pexip Infinity platform can be customized, for example to apply language translations or to change the color scheme for buttons, icons and other graphic indicators on the home page of the web app via branding. The in-call elements, such as the splash screens, are customized via themes.

Themes

The Rocket.Chat external policy server will request a theme called rocket.chat as one of the requirements for the one-time VMR. You can use the Pexip branding portal to apply a range of customizations and then go to Services > Themes and select Add theme. The name of your theme must be rocket.chat — see Customizing using themes for more information.

When you upload the theme to Pexip Infinity, you do not need to apply it to any Services or Call Routing Rules.

If there is no theme with the name rocket.chat in Pexip Infinity, the theme set as default in Global Settings is used.

Branding the Pexip app

The branding and styling of the web app can be customized to give the Rocket.Chat look and feel. You can do this by applying the branding to Pexip Infinity or using a reverse proxy to host the branding. See Customizing and branding the Pexip apps for more information.

Persistent chat integration

You can also optionally enable Rocket.Chat's persistent chat feature. This allows users to continue to chat while in a conference call. When starting and joining a meeting from the Rocket.Chat client, a dedicated discussion room is created for the meeting and you can continue to chat from within a Rocket.Chat conversation panel embedded within the Webapp3 client. The persistent meeting discussion is available within the workspace post meeting after the call has ended and is accessible to anyone on that same channel.

Requirements

There are some additional requirements for persistent chat:

  • Version 35 or later of Pexip Infinity.
  • Rocket.Chat server 6.11 or later.
  • Rocket.Chat Pexip integration 1.6.1 or later.
  • You must install a Webapp3 plugin that loads the Rocket.Chat integration.
  • All users need a valid Rocket.Chat workspace account. This is not a Rocket.Chat omnichannel focused feature.

Enabling persistent chat

Several additional steps are required to enable persistent chat.

Pexip Infinity

Within the Pexip Infinity environment you must:

  1. Retrieve and install the Rocket.Chat integration plugin for Webapp3 from https://developer.pexip.com/docs/plugins/webapp-3/plugin-gallery.
  2. Create a branding file containing the webapp plugin, and apply that branding to Pexip Infinity. See Customizing and branding the Pexip apps for more information on applying branding.
  3. Update the HTTP Content-Security-Policy (CSP) headers applied to Conferencing Nodes. Go to Platform > Global settings > Security and add the FQDN of your Rocket.Chat server to the list in HTTP Content Security Policy Header.

Rocket.Chat

Within the Rocket.Chat environment you must:

  1. Enable the persistent chat integration via Administration > Workspace > Settings > Conference call > Enable persistent chat.
  2. Ensure that discussions are enabled on your workspace via Administration > Workspace > Settings > Discussion.
  3. Go to Administration > Workspace > Setting > General and disable Restrict access inside any Iframe.

For more information, see https://docs.rocket.chat/docs/pexip-app#persistent-chat-with-pexip-app.

Using persistent chat

  1. Launch and join the video conference from within a Rocket.Chat workspace as usual.

  2. Continue to chat while in the Pexip meeting:

    • Select the Rocket.Chat icon that appears in the Webapp3 toolbar.
    • It opens within the web app the dedicated discussion created on the Rocket.Chat workspace. First-time users are required to log in.
    • You can view any previous messages in the discussion and continue exchanging messages with other participants during the call.

  3. Post meeting you can continue the discussion offline within the Rocket.Chat workspace. Discussions are named "Conference Call Chat History - <date-time>".

Note that:

  • The Rocket.Chat plugin will not work when joining a Pexip scheduled meeting, or via deeplinks. For the plugin to work the conversation must start from a Rocket.Chat workspace.
  • This feature does not work with breakout rooms — you will stay in the Rocket.Chat discussion from where you joined.
  • The web app's standard inbuilt chat functionality is also still available. If required you can disable this at the VMR or global level.