anchorObtain an Access Token

Developers can obtain an access token by leveraging Common Identity, which employs the OAuth 2.0 authorization framework for secure and standardized token-based authentication. To get up and running with the OAuth 2.0 flow, you can refer to this detailed guide which runs through the necessary steps, including user consent and redirection, to generate a short-lived authorization code.

After receiving the authorization code, you can use the curl utility with the following example API call to exchange it for an access token:

curl -X POST https://webexapis.com/v1/access_token \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Once you obtain the access token, it acts as the credential for secure API interactions with various Webex services, including the CallingClient module. The developer.webex.com website serves as a comprehensive resource throughout this OAuth 2.0 process, enabling you to seamlessly integrate Webex features into your application while mitigating security concerns.

anchorAuthorize with Webex Calling

Registering an endpoint with Webex Calling is a pivotal step in authorizing a user to access voice and video communication features. Once a user is provisioned in an organization licensed for Webex Calling, the CallingClient module can be used to initiate the registration process. That involves obtaining an access token via OAuth 2.0 authentication. Upon successful authentication, the CallingClient module registers the endpoint, thereby enabling it to place and receive calls through the Webex cloud. Once registration is complete, the SDK automatically sends requests at regular intervals to maintain the endpoint's active registration status.

Additional details regarding the registration process can be found below.

Obtaining a Line Object

A line object is created at the time of the callingClient initialization itself. It can be obtained by fetching the list of all the lines using getLines method in the callingClient module. However, the SDK only supports a single line at the moment.

For example:

const callingClient  = calling.callingClient;
const lines = callingClient.getLines();

The constant, lines, is an object where the keys are the lineId of each line and the values are the line Objects themselves.

Each of the line objects contain the following information:

anchorRegister a Device

The line object can be used to perform various line operations including device registration. The device registration process can be begun by using the line object's `register()' method:

line.register();

Determine if Registration is Successful

The register method only begins the registration process. To verify that the device registration is successful, register a callback to listen for the registered event:

line.on('registered', (line: ILine) => {
    // Store the line registration details
}

With the help of the registered event, you'll know the both that the registration has completed sucessfully and also have access to the line detials.

anchorDeregister a Device

You can derigister a registered device using the line object's deregister() method:

line.deregister();

Determine if Deregistration is Successful

The deregister method only begins the registration process. To verify that the device registration is successful, register a callback to listen for the unregistered event:

line.on('unregistered', () => {
    // Add any action that should happen after a line is unregistered
}

anchorThe Connecting Event

By listening for the connecting event, the app can determine that it's in the connecting state once the register() call is made:

line.on('connecting', () => {
    // Store the line registration details
}

This event has no payload. If the event listener is triggered, it means the line is connecting.

anchorThe Error Event

By listening for the error event, the app can monitor any errors encountered during the registration process:

line.on('error', (error) => {
    // Try to re-connect and/or show error to end user
}

This event returns an error payload. If this event listener is triggered, it means the line connection encountered one of the following errors:

An example error object is returned in JSON:

{
    "status": "inactive",
    "type": "tokenError",
    "msg": "Token expired. Authentication/Authorization error."
}