logo
Documentation
Guides

How to use an explorer in the NewVoiceMedia Developer Portal

What is an explorer?

An explorer is a tool that enables you to experiment with making API calls to NewVoiceMedia APIs.

An explorer contains a list of all the requests you can make using the API; authorization details; a description of all the request parameters, both required and optional; and what you might expect in both successful and failed responses. Most importantly the explorer contains a Send a Test Request section in which you can do just that!

An explorer

How do I find one of these explorers?

Unfortunately you can’t rely on this type of explorer to find you.

Fortunately you can find explorers in the Explorer section within an API’s documentation site.

Not all of the APIs have an explorer.

Using the Authentication API’s explorer to get a bearer access token

To use any NewVoiceMedia API, you need a bearer access token. Your bearer access token authenticates your request to the API. So, getting hold of a bearer access token is really important.

In this example, we get a bearer access token to use with the Insights Stats API using the Authentication API’s explorer.

Using the Authentication API explorer to get a bearer access token

To get a bearer access token using the Authentication API explorer, perform the following steps:

  1. On the Settings tab, define values for the following variables:
Variable Description Example
username and password For information about getting these values, see Getting your client credentials from NewVoiceMedia. Use Client Id as the value in username and Client Secret in password.
region The subdomain for your region. emea
scope The scope for the API you want to use the bearer access token with. stats
  1. Click Send. The explorer makes a request to the /oauth2/token endpoint and returns a bearer access token:
{
	"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"expires_in": 7200,
	"token_type": "bearer"
}

Your bearer access token is valid for use for only two hours after being issued. You can see when the token will expire in the expires_in item. (The expires_in item is expressed in seconds.) After this time, the token expires and you must request a new token.

Copy the token to use it to make a request to the Insights Stats API in the following explorer example.

Using the Insights Stats API’s explorer to make a request using the Insights Stats API

NewVoiceMedia’s Insights Stats API enables you to access data about your agents, interactions and queues.

In this example, we use the bearer access token we got using the Authentication API’s explorer to make a request to the GET /agent-status endpoint.

The GET /agent-status endpoint has two optional parameters: limit and page. Endpoints other than GET /agent-status have required query parameters that you must define. Required and optional parameters appear on the Query tab. If you do not define required parameters, the request will result in an error; the body of the error message specifies the missing parameter or parameters.

Using the Insights Stats API's explorer to make a request using the Insights Stats API

To make a request to the GET /agent-status endpoint, perform the following steps:

  1. On the Settings tab, define values for the following environmental variables:

    • region. The subdomain for your region, for example, emea.
    • Authorization. Paste the bearer access token returned by the Authentication API (using the explorer above). The Authorization header uses this value to authenticate your request to the Insights Stats API.
  2. Click Send. The explorer makes a request to the GET /agent-status endpoint and returns information about the current status of all agents within your account:

{
  "meta": {
    "page": 1,
    "count": 2,
    "pageCount": 1,
    "totalCount": 2
  },
  "items": [
    {
      "agentId": "0001",
      "presence": {
        "since": "2018-09-14T13:03:31.663Z",
        "name": "ExtendedAway",
        "description": "Training"
      },
      "workload": {
        "since": "2018-09-14T13:03:31.663Z",
        "calls": 0
      },
      "interaction": []
    },
    {
      "agentId": "115",
      "presence": {
        "since": "2018-09-25T09:01:38.308Z",
        "name": "Ready",
        "description": "Ready"
      },
      "workload": {
        "since": "2018-10-12T08:13:41.141Z",
        "calls": 1
      },
      "interaction": [
        {
          "guid": "585ae869-fa1b-5edc-ac39-f46d9edcbafb",
          "since": "2018-09-14T06:31:47.731Z",
          "type": "Call",
          "direction": "Outbound",
          "state": "Wrap",
          "reason": null
        }
      ]
    }
  ],
  "upTo": "2018-10-12T10:03:52.314Z"
}