Voicebase /v2-beta REST API

Browser and node module for making API requests against Voicebase /v2-beta REST API.

Please note: This module uses Popsicle to make API requests. Promises must be supported or polyfilled on all target environments.

Installation

npm install voicebase-v-2-beta-rest-api --save
bower install voicebase-v-2-beta-rest-api --save

Usage

Node

var VoicebaseV2BetaRestApi = require('voicebase-v-2-beta-rest-api');

var client = new VoicebaseV2BetaRestApi();

Browsers

<script src="voicebase-v-2-beta-rest-api/index.js">

<script>
  var client = new window.VoicebaseV2BetaRestApi();
</script>

Options

You can set options when you initialize a client or at any time with the options property. You may also override options for a single request by passing an object as the second argument of any request method. For example:

var client = new VoicebaseV2BetaRestApi({ ... });

client.options = { ... };

client.resource('/').get(null, {
  baseUri: 'http://example.com',
  headers: {
    'Content-Type': 'application/json'
  }
});

Base URI

You can override the base URI by setting the baseUri property, or initializing a client with a base URI. For example:

new VoicebaseV2BetaRestApi({
  baseUri: 'https://example.com'
});

Base URI Parameters

If the base URI has parameters inline, you can set them by updating the baseUriParameters property. For example:

client.options.baseUriParameters.version = 'v2-beta';

Resources

All methods return a HTTP request instance of Popsicle, which allows the use of promises (and streaming in node).

resources.media

Collection of all media and associated analytical results.

var resource = client.resources.media;

GET

Retrieve from the media colection.

resource.get().then(function (res) { ... });

Query Parameters

resource.get({ ... });

• externalId string

A unique identifier in an external system, set in metadata on POST.

POST

Upload new new media to the service as an attachment or from a url.

resource.post().then(function (res) { ... });

Body

multipart/form-data

{
  "media": [
    {
      "description": "Media file attached to the request.",
      "type": "file",
      "required": true,
      "repeat": false,
      "displayName": "media"
    },
    {
      "description": "URL where media file can be downloaded.",
      "type": "string",
      "required": true,
      "repeat": false,
      "displayName": "media"
    }
  ],
  "configuration": {
    "description": "A JSON object with configuration options.\n",
    "type": "file",
    "required": false,
    "repeat": false,
    "example": "{\n  \"configuration\" : {              \n    \"template\" : {\n      \"name\" : \"default\"\n    },\n    \"transcripts\" : {\n      \"vocabularies\" : [\n\n        {\n          \"name\": \"earningsCalls\"\n        },\n        {\n          \"terms\" : [\n            \"Bob Okunski\",\n            \"Chuck Boynton\",\n            \"Tom Werner\"\n          ]\n        }\n\n      ]\n    },\n    \"keywords\" : {\n      \"groups\" : [ \"mobile-phone\" ]\n    },\n    \"predictions\" : {\n      \"models\" : {\n        \"sales-lead\" : {\n          \"output\" : \"extended.sales-followup\"\n        },\n        \"not-a-sales-lead\" : {\n          \"output\" : \"extended.sales-ignore\"\n        }\n      }\n    },\n    \"publish\" : {\n      \"callbacks\" : [\n        \"https://api.example.org/callbacks/{mediaId}\"\n      ]\n    }\n  }\n}\n",
    "displayName": "configuration"
  },
  "metadata": {
    "description": "Metadata about the file being posted.",
    "type": "file",
    "required": false,
    "repeat": false,
    "example": "{\n  \"metadata\": {\n    \"external\" : {\n      \"id\" : \"abc12312321412342315324563443\"\n    },\n    \"extended\" : {\n      \"customer\" : \"John Doe\",\n      \"channel\" : \"1 (800) EXAMPLE\",\n      \"IVR\" : [ \"existing customer\", \"account services\", \"change my address\" ]\n    }\n  }\n}\n",
    "displayName": "metadata"
  },
  "transcript": {
    "description": "attached transcript",
    "type": "file",
    "required": false,
    "repeat": false,
    "displayName": "transcript"
  }
}

resources.media.mediaId(mediaId)

• mediaId string

Media item and associated analytical results.

var resource = client.resources.media.mediaId(mediaId);

GET

Get this media item and associated analytics.

resource.get().then(function (res) { ... });

DELETE

Delete this media.

resource.delete().then(function (res) { ... });

POST

Upload new configuration, metadata and/or transcript for re-processing of a media document.

resource.post().then(function (res) { ... });

Body

multipart/form-data

{
  "configuration": {
    "description": "A JSON object with configuration options.\n",
    "type": "file",
    "required": false,
    "repeat": false,
    "example": "{\n  \"configuration\" : {              \n    \"template\" : {\n      \"name\" : \"default\"\n    },\n    \"transcripts\" : {\n      \"vocabularies\" : [\n\n        {\n          \"name\": \"earningsCalls\"\n        },\n        {\n          \"terms\" : [\n            \"Bob Okunski\",\n            \"Chuck Boynton\",\n            \"Tom Werner\"\n          ]\n        }\n\n      ]\n    },\n    \"keywords\" : {\n      \"groups\" : [ \"mobile-phone\" ]\n    },\n    \"predictions\" : {\n      \"models\" : {\n        \"sales-lead\" : {\n          \"output\" : \"extended.sales-followup\"\n        },\n        \"not-a-sales-lead\" : {\n          \"output\" : \"extended.sales-ignore\"\n        }\n      }\n    },\n    \"publish\" : {\n      \"callbacks\" : [\n        \"https://api.example.org/callbacks/{mediaId}\"\n      ]\n    }\n  }\n}\n",
    "displayName": "configuration"
  },
  "metadata": {
    "description": "Metadata about the file being posted.",
    "type": "file",
    "required": false,
    "repeat": false,
    "example": "{\n  \"metadata\": {\n    \"external\" : {\n      \"id\" : \"abc12312321412342315324563443\"\n    },\n    \"extended\" : {\n      \"customer\" : \"John Doe\",\n      \"channel\" : \"1 (800) EXAMPLE\",\n      \"IVR\" : [ \"existing customer\", \"account services\", \"change my address\" ]\n    }\n  }\n}\n",
    "displayName": "metadata"
  },
  "transcript": {
    "description": "attached transcript",
    "type": "file",
    "required": false,
    "repeat": false,
    "displayName": "transcript"
  }
}

resources.media.mediaId(mediaId).transcripts

Collection of transcripts available for this media item.

var resource = client.resources.media.mediaId(mediaId).transcripts;

GET

Get available transcripts.

resource.get().then(function (res) { ... });

resources.media.mediaId(mediaId).transcripts.transcriptId(transcriptId)

• transcriptId string, default: latest

var resource = client.resources.media.mediaId(mediaId).transcripts.transcriptId(transcriptId);

GET

Get a specific transcript.

resource.get().then(function (res) { ... });

resources.media.mediaId(mediaId).progress

Collection of processing phases.

var resource = client.resources.media.mediaId(mediaId).progress;

GET

Get progress phases.

resource.get().then(function (res) { ... });

resources.media.mediaId(mediaId).streams

Streaming formats for uploaded media.

var resource = client.resources.media.mediaId(mediaId).streams;

GET

Get available media URLs.

resource.get().then(function (res) { ... });

resources.media.mediaId(mediaId).streams.original

Redirects to the original version of the file.

var resource = client.resources.media.mediaId(mediaId).streams.original;

GET

resource.get().then(function (res) { ... });

Query Parameters

resource.get({ ... });

• access_token string, default: WLtrGY1UB1VUXkDaf0LSxDIhIWb-z4TSS8tERTMMvAjnCiRgRoa9AF125YRjITrhKAMkh2TtmhR-qelXK9XteA

Used to send a valid OAuth 2 Bearer token.

resources.media.mediaId(mediaId).metadata

The metadata for the media item.

var resource = client.resources.media.mediaId(mediaId).metadata;

GET

Get the media metadata.

resource.get().then(function (res) { ... });

PUT

Update the media metadata.

resource.put().then(function (res) { ... });

Body

application/json

resources.definitions

Allows definition of complex behaviors or reusable data sets.

var resource = client.resources.definitions;

GET

resource.get().then(function (res) { ... });

resources.definitions.keywords

var resource = client.resources.definitions.keywords;

GET

Get definition types for keywords.

resource.get().then(function (res) { ... });

resources.definitions.keywords.groups

Define keyword groups for spotting important topics.

var resource = client.resources.definitions.keywords.groups;

GET

Get all defined keyword groups.

resource.get().then(function (res) { ... });

resources.definitions.keywords.groups.groupId(groupId)

• groupId string

A group of a set of related keywords.

var resource = client.resources.definitions.keywords.groups.groupId(groupId);

GET

Get the keyword group.

resource.get().then(function (res) { ... });

PUT

Create or update group from a set of keywords.

resource.put().then(function (res) { ... });

Body

application/json

DELETE

Delete this keyword group.

resource.delete().then(function (res) { ... });

resources.definitions.transcripts

var resource = client.resources.definitions.transcripts;

GET

Get definition types for transcripts.

resource.get().then(function (res) { ... });

resources.definitions.transcripts.vocabularies

Define custom vocabularies for more accurate transcription.

var resource = client.resources.definitions.transcripts.vocabularies;

GET

Get all defined custom vocabularies.

resource.get().then(function (res) { ... });

resources.definitions.transcripts.vocabularies.vocabularyId(vocabularyId)

• vocabularyId string

A custom vocabulary based on a set of documents or recordings.

var resource = client.resources.definitions.transcripts.vocabularies.vocabularyId(vocabularyId);

GET

Get the custom vocabulary.

resource.get().then(function (res) { ... });

PUT

Create a custom vocabulary from a set of media.

resource.put().then(function (res) { ... });

Body

application/json

DELETE

Delete this custom vocabulary.

resource.delete().then(function (res) { ... });

resources.definitions.media

var resource = client.resources.definitions.media;

GET

Get definition types for media.

resource.get().then(function (res) { ... });

resources.definitions.media.search

Define extended metadata searchable fields.

var resource = client.resources.definitions.media.search;

GET

Get searchable fields.

resource.get().then(function (res) { ... });

PUT

Create or update custom parameters of metadata for search.

resource.put().then(function (res) { ... });

Body

application/json

resources.definitions.predictions

var resource = client.resources.definitions.predictions;

GET

Get definition types for predictions.

resource.get().then(function (res) { ... });

resources.definitions.predictions.models

Retrieve available predicitive models.

var resource = client.resources.definitions.predictions.models;

GET

Get all available predictive models.

resource.get().then(function (res) { ... });

resources.definitions.predictions.models.modelName(modelName)

• modelName string

A predictive model.

var resource = client.resources.definitions.predictions.models.modelName(modelName);

GET

Get the predictive model.

resource.get().then(function (res) { ... });

resources.profile

Manage profile keys.

var resource = client.resources.profile;

GET

Profile keys operations.

resource.get().then(function (res) { ... });

resources.profile.keys

var resource = client.resources.profile.keys;

GET

Returns all current Api keys for current user.

resource.get().then(function (res) { ... });

POST

Create a new Api key for the current user.

resource.post().then(function (res) { ... });

Body

application/json

resources.profile.keys.keyId(keyId)

• keyId string

var resource = client.resources.profile.keys.keyId(keyId);

GET

Get information about this Api key.

resource.get().then(function (res) { ... });

DELETE

Delete and revoke this Api key.

resource.delete().then(function (res) { ... });

Custom Resources

You can make requests to a custom path in the API using the #resource(path) method.

client.resource('/example/path').get();

License

Apache 2.0