Using a simple REST API, you can easily generate Instant Connect URLs for one or multiple hosts and guests. The API allows for a variety of customizations via its request payload, including:

• A configurable meeting subject
• Not before and expiration times for the authorization JWT
• Automatic addition of Cisco devices to a meeting
• Parameters to set the number of hosts and guests up to a combined maximum of 25 (you can use the same API call to generate another 25 if necessary)
• An option to generate short URLs
• Various advanced encryption options

The guide includes a step by step example using Postman, if you're new to REST APIs. Alternatively, if you're a REST veteran, you can skip directly to the API Reference materials at the end of this document.

anchorPrerequisites

Before you can use Instant Connect, your Webex Admin will need to login to the Instant Connect webpage and choose Activate Instant Connect here:https://instant.webex.com/integrate/.

Next, you'll need to generate an access token which is required to make the API call to retrieve the encrypted part of the URLs. You've got two options for access tokens:

• A 12 hour time limited Personal Access token for development purposes
• A 100 year Bot token for production use

In addition, optionally, to enable adding devices to the meeting, you'll need to configure Instant Rounding as described in the following help.webex.com article Configure Virtual Rounding.

Retrieve a Personal Access Token for Development

To obtain a Webex Personal Access Token (valid for 12 hours), navigate to the Webex Developer Portal, login with your Webex org admin account, and copy the Bearer token value:

Retrieve a Bot Token for Production Usage

For a production-level implementation, we recommend creating a new Webex Bot and using the Bot’s access token (valid for 100 years). You can copy the Bot access token once you've created your new bot:

anchorStep by Step Instant Connect API Call Using Postman

With your access token, you use the Instant Connect API to retrieve the encrypted ciphers that you'll append to the base URLs for hosts and guests. In this section we'll use Postman to walk you through an example REST call that generates ciphers for a single host and a single participant using the minimum required request payload.

To retrieve the encrypted ciphers using Postman:

1. Open Postman and select New.

   

2. Choose Environment.

   

3. Name your new environment, in this case InstantConnect and define the two following variables with the corresponding values:

   • Name: mtg-broker-url; Value: https://mtg-broker-a.wbx2.com
   • Name: bot-token; Value: your personal access token or bot token

   Click Save.

   

4. Choose your new environment from the drop down list.

   

5. Choose New.

   

6. Choose HTTP Request.

   

7. Configure the request as follows:

   • Choose POST as the request type.
   • Enter {{mtg-broker-url}}/api/v2/joseencrypt as the URL.
   • Select Auth, choose Bearer Token as the Type, and enter {{bot-token}} as the value for the token.

   

8. Select Body, select the type as raw JSON and enter the following JSON string (you can change the sub (subject) string to whatever you'd like as long as it is unique for each meeting):

   {
     "jwt": {
     "sub": "Subject goes here."
     },
     "aud": "a4d886b0-979f-4e2c-a958-3e8c14605e51"
   }
   

   

9. Select Send. You'll see the response in the Body tab of the Postman console.

   

Your response will look something like:

{
    "host": [
        {
            "cipher": "eyJwMnMiOiJiLVZB...-xtzA"
        }
    ],
    "guest": [
        {
            "cipher": "eyJwMnMiOiJuNmxv...FaqA"
        }
    ]
}

You'll notice you've got two cipher values, one for the host and one for a single guest. Those are the values that you'll append to the meeting URL after &data=.

For the host URL after appending the cipher, you'll get:

https://instant.webex.com/gen/v1/login?int=jose&v=1&data=eyJwMnMiOiJiLVZB...-xtzA

For the guest URL after appending the cipher, you'll get:

https://instant.webex.com/gen/v1/talk?int=jose&v=1&data=eyJwMnMiOiJuNmxv...FaqA

The remaining sections describe additional configurations and contain complete reference materials.

anchorInstant Connect URL REST API Reference

This section contains the full reference for all of the Instant Connect URL REST API including example requests and responses.

Request Endpoint

The REST API endpoint is:

• POST https://mtg-broker-a.wbx2.com/api/v2/joseencrypt

Request Headers

Use the following headers in your request:

• Content-Type: application/json
• Authorization: Bearer <Personal or Bot access token goes here>

Body Parameters

Use the following body parameters to customize your REST request:

Response

A successful request returns:

• A response message of type 200 OK

• A response payload of typeapplication/json

Request and Response Payload Examples

The following examples show various request payloads as a formatting reference as well as their resultant responses.

Minimum Request Body Payload

{
  "jwt": {
    "sub": "Subject goes here."
  },
  "aud": "a4d886b0-979f-4e2c-a958-3e8c14605e51"
}

Response from the Minimal Request Body

{
    "host": [
        {
            "cipher": "eyJwMnMiOiJiLVZB...-xtzA"
        }
    ],
    "guest": [
        {
            "cipher": "eyJwMnMiOiJuNmxv...FaqA"
        }
    ]
}

Complete Sample JSON Request Payload Without Device Support

To create multiple host and guest URLs in the same response, increase the value of numHost and numGuest up to a maximum of 25.

{
  "jwt": {
    "sub": "Subject goes here.",
    "Nbf": 1671480433000,
    "Exp": 1671480433000
  },
  "aud": "a4d886b0-979f-4e2c-a958-3e8c14605e51",
  "numGuest": 1,
  "numHost": 1,
  "provideShortUrls": false,
  "verticalType": "gen",
  "loginUrlForHost": false,
  "jweAlg": "PBES2-HS512+A256KW",
  "saltLength": 8,
  "iterations": 1000,
  "enc": "A256GCM",
  "jwsAlg": "HS512"
}

Complete Sample JSON Response Payload Without Device Support

In this case the response will appear similar to the minimal request payload response above. The cipher provided, however will reflect the additional configuration options. In addition, increasing the values for numHost and numGuest will return multiple cipher instances that you can use to create multiple Instant Connect URLs.

Sample Request Payload Generating Short URLs

Adding the parameter provideShortUrls generates short URLs in addition to the regular cipher.

{
  "jwt": {
    "sub": "Subject goes here."
  },
  "aud": "a4d886b0-979f-4e2c-a958-3e8c14605e51",
  "provideShortUrls": true,
  "verticalType": "gen",
  "loginUrlForHost": false
}

Short URL Response Payload

The short values are combined with the baseUrl value in the response payload to generate "short" URLs as described below. The cipher values can be used as described below as well.

{
    "host": [
        {
            "cipher": "eyJwMnMiOiJQUnJX ... EbZaQ",
            "short": "Kuyqdx3"
        }
    ],
    "guest": [
        {
            "cipher": "eyJwMnMiOiJPamRX ... xVfyA",
            "short": "LCFCNRz"
        }
    ],
    "baseUrl": "https://instant.webex.com/visit/"
}

Complete Sample JSON Request Payload Including Device Support

To enable device support, add the flow element to the jwt element in your regular request body.

{
  "jwt": {
    "sub": "Subject goes here.",
    "Nbf": 1671480433000,
    "Exp": 1671480433000,
    "flow": {
      "id": "sip-no-knock",
      "data": [
        {
          "uri": "example1@intadmin.room.wbx2.com"
        },
        {
          "uri": "example2@intadmin.room.wbx2.com"
        }
      ]
    }
  },
  "aud": "a4d886b0-979f-4e2c-a958-3e8c14605e51",
  "numGuest": 1,
  "numHost": 1,
  "provideShortUrls": true,
  "verticalType": "gen",
  "loginUrlForHost": false,
  "jweAlg": "PBES2-HS512+A256KW",
  "saltLength": 8,
  "iterations": 1000,
  "enc": "A256GCM",
  "jwsAlg": "HS512"
}

Complete Sample JSON Response Payload Including Device Support

As with the other complete payload, the response will appear similar to the minimal request payload response above. The cipher provided, however will reflect the additional configuration options and the SIP addresses are added once the host joins the meeting.

anchorBuild Instant Connect URLs

Depending upon whether you've generated regular or "short" URLs you can build final Instant Connect URLs in one of two ways.

Build Long URLs

The following URLs are used as bases for the complete host and guest URLs. The API generates a cipher which you then append to the &data= portion of the base URL:

• Host: https://instant.webex.com/gen/v1/login?int=jose&v=1&data=
• Guest: https://instant.webex.com/gen/v1/talk?int=jose&v=1&data=

Append your API response cipher values as the &data= parameter value to form your Webex Instant Connect meeting for host and guest long URLs.

Long URL Examples

• Host URL:https://instant.webex.com/gen/v1/login?int=jose&v=1&data=eyJwMnMiOiJfRFN ... ufUvar_w
• Guest URL:https://instant.webex.com/gen/v1/talk?int=jose&v=1&data=eyJwMnMiOiJYZVp ... dL_GqSw

Build Short URLs

To construct a final short URL, append the short key values to the baseUrl generated in the response.

Short URL Examples

• Host URL: https://instant.webex.com/visit/m8iHTzH
• Guest URL: https://instant.webex.com/visit/oJCP7UY