This is a high-level overview of the Client Library API. The specifics depend on the Client Library being used, but all Client Libraries implement this API subject to some platform specific variations.

Methods

The most important methods especially for new users involve initialising the client, as well as registering a segment handler with onSegmentChange.

initialize(app_id: string | proj_id: string)

Creates and initialises the Client. In most of our Client Libraries this is implemented by the constructor of the client object. For most applications you must pass as argument the app_id (available from the Dashboard or Command Line Tool). All connections initiated by the client will be targeted to this app_id.

You can also pass a project_id. This is a more advanced feature, where you must identify the application for each context separately (see startContext).

onSegmentChange(segment_handler: function)

Define the segment handling callback function. How this is precisely done varies a little across Client Libraries. See Basic usage for a brief example for each Client library. In general, segment_handler is passed a Segment object from which you can look up the intent and entities.

startContext(app_id: string?)

Starts an “audio context”, i.e., opens the microphone, starts streaming audio, and starts receiving events (intents, entities and segment changes) from the gRPC API. If you have initialised the client by providing a proj_id, you must also give the app_id to which the recording is directed. If you initialised the client by providing an app_id, no arguments are needed.

stopContext()

Stops the “audio context”, i.e., closes the microphone, stops streaming audio. Events are still being received until the server stops the stream.

onClientStateChanged(state_handler: function)

Defines a callback function for handling client state changes.

The Segment data structures

The callback function registered with onSegmentChange is called repeatedly with a Segment object that is updated with new transcript, intent, and entities as the user speaks.

Segment

Segment {
    contextId: string (UUID),
    id: int,
    isFinal: boolean,
    intent: Intent,
    entities: list of Entity objects,
    words: list of Transcript objects
}

Intent

Intent { name: string, isFinal: boolean }

Entity

Entity { name: string, value: string, isFinal: boolean,
         startIndex: int, endIndex: int }

Transcript

Transcript { index: int, value: string, isFinal: boolean }