OneSpan Sign Developers: Virtual Room – Part 1

Duo Liang,

OneSpan Sign Virtual Room (VR) delivers a secure and interactive user experience where signers and the meeting host can collaborate through a video conference call and sign documents within a co-browsing session from different locations. It recreates the power of a face-to-face meeting by combining electronic signature, video conferencing, identity proofing, session recording, and audit trails.

The entire experience journey includes an easy 5-step process. When the sender fully prepares the transaction and sets the date and time for the virtual signing session, recipients will get invited by email notification. Once both parties joined the Virtual Room, recipients can optionally be prompted to authenticate themselves via selected methods, and the host will help signers to review and understand the agreement in real-time.  Signers will follow an intuitive and guided workflow and complete signing the documents.

In this blog, we will dive into this new and exciting feature and show how to prepare a Virtual Room signing transaction. Without further delay, let’s get started!

Virtual Room Signing in Action

Before reading today’s blog, take few minutes and watch our step-by-step video tutorial where we demonstrated how to prepare and configure a transaction for Virtual Room through the sender UI and how the to launch and sign in a Virtual Room session in real action. 

Note: The Virtual Room feature is turned off by default. Contact our team to get started with OneSpan Sign Virtual Room.

Best Practice for Integrated Users

In terms of the transaction preparation, similar to the UI experience, integrators can also implement this workflow via REST APIs. In this section, we will walk through the necessary steps and highlight the differences compared to the normal transaction creation.

Step 1: Create a Transaction

The first step is to trigger the Virtual Room setting during your normal transaction creation and leave the transaction at ”draft” status with the API below: 

HTTP Request

POST /api/packages

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json
Content-Type: multipart/form-data

Example Payload

{
  "roles": [
    {
      "id": "Owner",
      "name": "Owner",
      "signers": [
        {
          "email": "sender's email",
          "firstName": "Duo",
          "lastName": "Liang",
          "company": "OneSpan Sign",
          "id": "Owner"
        }
      ]
    },
    {
      "id": "Signer1",
      "name": "Signer1",
      "signers": [
        {
          "email": "[email protected]",
          "firstName": "1.firstname",
          "lastName": "1.lastname",
          "company": "OneSpan Sign",
          "id": "Signer1"
        }
      ]
    }
  ],
  "documents": [
    {
      "approvals": [
        {
          "role": "Signer1",
          "fields": [
            {
              "page": 0,
              "top": 100,
              "subtype": "FULLNAME",
              "height": 50,
              "left": 100,
              "width": 200,
              "type": "SIGNATURE"
            }
          ]
        }
      ],
      "name": "Test Document"
    }
  ],
  "name": "Example Package",
  "type": "PACKAGE",
  "language": "en",
  "emailMessage": "",
  "description": "New Package",
  "autocomplete": true,
  "virtualRoom": true,
  "status": "DRAFT"
}

Note:

  • Explicitly add the virtual room host and specify the role ID. In our case, the virtual room host is the transaction owner, however the virtual room host could be any email as long as they have an OneSpan Sign sender profile.
  • Remember to turn on the flag "virtualRoom" : true 

Step 2: Set up Virtual Room Settings

The next step is to configure Virtual Room related settings, including whether to enable cameras during the session, whether to allow video recording, and specifying the host ID, start time, and duration of the meeting. These can be specified via the API below:

HTTP Request

PUT /api/packages/{packageId}/virtual-room/config

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json
Content-Type: application/json

Example Payload

{
    "video": true,
    "videoRecording": false,
    "startDatetime": "2022-02-14T03:14:00.000Z",
    "hostUid": "Owner",
    "sessionTime": 60,
    "sessionTimeoutWarning": 15
}

Note:

  1. Convert the session start time in GMT time in the format of “yyyy-MM-dd’T’HH:mm:ss’Z’”
  2. When the start date has been specified and will appear in the invitation email to all the meeting's participants, participants can still hold and access the meeting at another date and time.

Step 3: Send the Transaction

HTTP Request

PUT /api/packages/{packageId}

HTTP Headers

Authorization: Basic api_key / Bearer access_token
Accept: application/json
Content-Type: application/json

Example Payload

{"status":"SENT"}

Features Work in Tandem with VR

In the transaction preparation step, the owner has additional options to design the signing flow. They can request that signers upload attachments to the workflow, such as a copy of their driver’s license, and optionally to authenticate signer’s identity before they are permitted to join the session. The transaction owner can select from a number of authentication options, such as email, SMS, Q&A, and government ID verification with face comparison. 

This concludes today’s blog. By now, you should be able to create a Virtual Room signing transaction via REST API. In the next blog, I will walk through the equivalent workflow in SDK code and demonstrate more features of Virtual Room signing. If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

Duo Liang is a Technical Evangelist and Partner Integrations Developer at OneSpan where he creates and maintains integration guides and code shares, helps customers and partners integrate OneSpan products into their applications, and builds integrations within third party platforms.