Partager via

Class SPXDialogServiceConnector

  • Article

Declaration

@class SPXDialogServiceConnector : SPXRecognizer;

Description

An object that communicates with a speech-enabled dialog system using either the Bot Framework or Custom Commands. This type receives speech-to-text results and also facilitates the asynchronous sending and receiving of non-speech dialog activity data.

See also: Integrate with a client application using Speech SDK, Voice assistants frequently asked questions, What is Custom Commands?

Methods

initWithDialogServiceConfiguration:error:

Initializes a new instance of dialog service connector that will use the default audio input device for any speech-to-text interactions.

- (instancetype _Nullable)initWithDialogServiceConfiguration:(SPXDialogServiceConfiguration * _Nonnull)dialogServiceConfiguration
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • dialogServiceConfiguration - the configuration object that includes information about the selected dialog system.
  • outError - error information.

Returns

an instance of a dialog service connector.

initWithDialogServiceConfiguration:

Initializes a new instance of dialog service connector that will use the default audio input device for any speech-to-text interactions.

- (instancetype _Nonnull)initWithDialogServiceConfiguration:(SPXDialogServiceConfiguration * _Nonnull)dialogServiceConfiguration

Parameters

  • dialogServiceConfiguration - the configuration object that includes information about the selected dialog system.

Returns

an instance of a dialog service connector.

initWithDialogServiceConfiguration:audioConfiguration:error:

Initializes a new instance of dialog service connector using the specified audio configuration.

- (instancetype _Nullable)initWithDialogServiceConfiguration:(SPXDialogServiceConfiguration * _Nonnull)dialogServiceConfiguration
    audioConfiguration:(SPXAudioConfiguration * _Nonnull)audioConfiguration
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • dialogServiceConfiguration - the configuration object that includes information about the selected dialog system.
  • audioConfiguration - the configuration object for input audio as used by speech-to-text interactions.
  • outError - error information.

Returns

an instance of a dialog service connector.

initWithDialogServiceConfiguration:audioConfiguration:

Initializes a new instance of dialog service connector using the specified audio configuration.

- (instancetype _Nonnull)initWithDialogServiceConfiguration:(SPXDialogServiceConfiguration * _Nonnull)dialogServiceConfiguration
    audioConfiguration:(SPXAudioConfiguration * _Nonnull)audioConfiguration

Parameters

  • dialogServiceConfiguration - the configuration object that includes information about the selected dialog system.
  • audioConfiguration - the configuration object for input audio as used by speech-to-text interactions.

Returns

an instance of a dialog service connector.

listenOnce:

Begins a speech-to-text interaction with this connector and blocks until a single speech-to-text final result is received. The speech-to-text result received is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (SPXSpeechRecognitionResult * _Nullable)listenOnce:(NSError * _Nullable * _Nullable)outError

Parameters

  • outError - error information.

Returns

the speech-to-text result from the single-shot speech interaction.

listenOnce

Begins a speech-to-text interaction with this connector and blocks until a single speech-to-text final result is received. The speech-to-text result received is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (SPXSpeechRecognitionResult * _Nonnull)listenOnce

Returns

the speech-to-text result from the single-shot speech interaction.

listenOnceAsync:error:

Asynchronously begins a speech-to-text interaction with this connector and immediately returns execution to the calling thread. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (BOOL)listenOnceAsync:(SPXDialogServiceConnectorRecognitionResultHandler _Nonnull)resultReceivedHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • resultReceivedHandler - the handler function called when a final speech-to-text result is received.
  • outError - error information.

Returns

a value indicating whether the request to listen started successfully. If NO, additional detail may be available in outError.

listenOnceAsync:

Asynchronously begins a speech-to-text interaction with this connector and immediately returns execution to the calling thread. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (void)listenOnceAsync:(SPXDialogServiceConnectorRecognitionResultHandler _Nonnull)resultReceivedHandler

Parameters

  • resultReceivedHandler - the handler function called when a final speech-to-text result is received.

stopListening:

Requests an immediate stop to any active listening operation. This may interrupt a speech-to-text interaction in progress and any speech-to-text result received may represent an incomplete speech input.

Synchronous methods should not be called when handling an event. Use stopListeningAsync if a stop is desired in response to an event.

- (BOOL)stopListening:(NSError * _Nullable * _Nullable)outError

Parameters

  • outError - error information.

Returns

a value indicating whether a request to stop was received successfully. If NO, additional information may be available in outError.

stopListening

Requests an immediate stop to any active listening operation. This may interrupt a speech-to-text interaction in progress and any speech-to-text result received may represent an incomplete speech input.

Synchronous methods should not be called when handling an event. Use stopListeningAsync if a stop is desired in response to an event.

- (void)stopListening

stopListeningAsync:error:

Requests an immediate stop to any active listening operation. This may interrupt a speech-to-text interaction in progress and any speech-to-text result received may represent an incomplete speech input.

- (BOOL)stopListeningAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • completionHandler - the handler function called when the stop request has completed.
  • outError - error information.

Returns

a value indicating whether a request to stop was received successfully. If NO, additional information may be available in outError.

stopListeningAsync:

Requests an immediate stop to any active listening operation. This may interrupt a speech-to-text interaction in progress and any speech-to-text result received may represent an incomplete speech input.

- (void)stopListeningAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler

Parameters

  • completionHandler - the handler function called when the stop request has completed.

sendActivity:error:

Sends a data payload to dialog implementation that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation and the contents of a sent activity should be populated with knowledge about the format and content expectations of the dialog system.

Sent activities are not associated with any other interaction and will generate their own standalone interaction identifier when processed by the service. Correlation of conversations and other interactions should be accomplished via the activity payload itself using the capabilities of the dialog implementation used.

See also: Bot Framework -- Activity schema, Quickstart: Create a custom voice assistant (with sendActivity example)

- (NSString * _Nullable)sendActivity:(NSString * _Nonnull)activity
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • activity - the serialized payload of an activity to send.
  • outError - error information.

Returns

an interaction identifier acquired when the activity is sent to the service. This may occur before the activity is processed and evaluated by the dialog implementation and the receipt of an interaction identifier does not indicate any success or failure in processing the activity. Information about success or failure may be obtained via response activities with correlation data or with TurnStatusReceived events that correlate to this interaction identifier.

sendActivity:

Sends a data payload to dialog implementation that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation and the contents of a sent activity should be populated with knowledge about the format and content expectations of the dialog system.

Sent activities are not associated with any other interaction and will generate their own standalone interaction identifier when processed by the service. Correlation of conversations and other interactions should be accomplished via the activity payload itself using the capabilities of the dialog implementation used.

See also: Bot Framework -- Activity schema, Quickstart: Create a custom voice assistant (with sendActivity example)

- (NSString * _Nonnull)sendActivity:(NSString * _Nonnull)activity

Parameters

  • activity - the serialized payload of an activity to send.

Returns

an interaction identifier acquired when the activity is sent to the service. This may occur before the activity is processed and evaluated by the dialog implementation and the receipt of an interaction identifier does not indicate any success or failure in processing the activity. Information about success or failure may be obtained via response activities with correlation data or with TurnStatusReceived events that correlate to this interaction identifier.

sendActivityAsync:interactionIdReceivedHandler:error:

Sends a data payload to dialog implementation that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation and the contents of a sent activity should be populated with knowledge about the format and content expectations of the dialog system.

Sent activities are not associated with any other interaction and will generate their own standalone interaction identifier when processed by the service. Correlation of conversations and other interactions should be accomplished via the activity payload itself using the capabilities of the dialog implementation used.

- (BOOL)sendActivityAsync:(NSString * _Nonnull)activity
    interactionIdReceivedHandler:(SPXDialogServiceConnectorInteractionIdHandler _Nonnull)interactionIdReceivedHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • activity - the serialized payload of an activity to send.
  • interactionIdReceivedHandler - a handler function called when the activity is sent to the service. This may occur before the activity is processed and evaluated by the dialog implementation and the receipt of an interaction identifier does not indicate any success or failure in processing the activity. Information about success or failure may be obtained via response activities with correlation data or with TurnStatusReceived events that correlate to this interaction identifier.
  • outError - error information.

Returns

a value indicating whether the request to send an activity started successfully. If NO, additional information may be available in outError.

sendActivityAsync:interactionIdReceivedHandler:

Sends a data payload to dialog implementation that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation and the contents of a sent activity should be populated with knowledge about the format and content expectations of the dialog system.

Sent activities are not associated with any other interaction and will generate their own standalone interaction identifier when processed by the service. Correlation of conversations and other interactions should be accomplished via the activity payload itself using the capabilities of the dialog implementation used.

See also: Bot Framework -- Activity schema, Quickstart: Create a custom voice assistant (with sendActivityAsync example)

- (void)sendActivityAsync:(NSString * _Nonnull)activity
    interactionIdReceivedHandler:(SPXDialogServiceConnectorInteractionIdHandler _Nonnull)interactionIdReceivedHandler

Parameters

  • activity - the serialized payload of an activity to send.
  • interactionIdReceivedHandler - a handler function called when the activity is sent to the service. This may occur before the activity is processed and evaluated by the dialog implementation and the receipt of an interaction identifier does not indicate any success or failure in processing the activity. Information about success or failure may be obtained via response activities with correlation data or with TurnStatusReceived events that correlate to this interaction identifier.

startKeywordRecognition:error:

Begins a speech-to-text interaction with this connector using a keyword. This interaction will use the provided keyword model to listen for a keyword indefinitely, during which audio is not sent to the speech service and all processing is performed locally. When a keyword is recognized, the DialogServiceConnector will automatically connect to the speech service and begin sending audio data from just before the keyword as if listenOnceAsync() were invoked. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (BOOL)startKeywordRecognition:(SPXKeywordRecognitionModel * _Nonnull)keywordModel
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • keywordModel - the keyword recognition model.
  • outError - error information.

Returns

a value indicating whether the requested keyword recognition successfully started. If NO, outError may contain additional information.

startKeywordRecognition:

Begins a speech-to-text interaction with this connector using a keyword. This interaction will use the provided keyword model to listen for a keyword indefinitely, during which audio is not sent to the speech service and all processing is performed locally. When a keyword is recognized, the DialogServiceConnector will automatically connect to the speech service and begin sending audio data from just before the keyword as if listenOnceAsync() were invoked. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (void)startKeywordRecognition:(SPXKeywordRecognitionModel * _Nonnull)keywordModel

Parameters

  • keywordModel - the keyword recognition model.

startKeywordRecognitionAsync:completionHandler:error:

Asynchronously begins a speech-to-text interaction with this connector and immediately returns execution to the calling thread. This interaction will use the provided keyword model to listen for a keyword indefinitely, during which audio is not sent to the speech service and all processing is performed locally. When a keyword is recognized, the DialogServiceConnector will automatically connect to the speech service and begin sending audio data from just before the keyword as if listenOnceAsync() were invoked. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (BOOL)startKeywordRecognitionAsync:(SPXKeywordRecognitionModel * _Nonnull)keywordModel
    completionHandler:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • keywordModel - the keyword recognition model.
  • completionHandler - the handler function called when keyword recognition has started.
  • outError - error information.

Returns

a value indicating whether the request to start keyword recognition was received successfully. If NO, additional information may available in outError.

startKeywordRecognitionAsync:completionHandler:

Asynchronously begins a speech-to-text interaction with this connector and immediately returns execution to the calling thread. This interaction will use the provided keyword model to listen for a keyword indefinitely, during which audio is not sent to the speech service and all processing is performed locally. When a keyword is recognized, the DialogServiceConnector will automatically connect to the speech service and begin sending audio data from just before the keyword as if listenOnceAsync() were invoked. When received, speech-to-text results may be processed by the provided result handler or retrieved via a subscription to the recognized event. The speech-to-text result produced by this operation is also provided to the configured dialog implementation and that dialog system may produce any number of activity payloads in response to the speech interaction. Speech interactions may be correlated with activities via dialog-specific data in the activity payload.

- (void)startKeywordRecognitionAsync:(SPXKeywordRecognitionModel * _Nonnull)keywordModel
    completionHandler:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler

Parameters

  • keywordModel - the keyword recognition model.
  • completionHandler - the handler function called when keyword recognition has started.

stopKeywordRecognition:

Stops any active keyword recognition.

- (BOOL)stopKeywordRecognition:(NSError * _Nullable * _Nullable)outError

Parameters

  • outError - error information.

Returns

a value indicating whether keyword recognition was stopped successfully. If NO, additional information may be available in outError.

stopKeywordRecognition

Stops any active keyword recognition.

- (void)stopKeywordRecognition

stopKeywordRecognitionAsync:error:

Stops any active keyword recognition.

- (BOOL)stopKeywordRecognitionAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • completionHandler - the handler function called when keyword recognition has stopped.
  • outError - error information.

Returns

a value indicating whether the request to stop was received successfully. If NO, additional error information may be available in outError.

stopKeywordRecognitionAsync:

Stops any active keyword recognition.

- (void)stopKeywordRecognitionAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler

Parameters

  • completionHandler - the handler function called when keyword recognition has stopped.

connect:

Establishes a connection with the service. Connection is automatically performed when needed, but this manual call can be useful to make sure the connection is active before its first use to help reduce inital latency.

Calling connect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling open(false). The Connection object also provides events to monitor connections and disconnections.

- (BOOL)connect:(NSError * _Nullable * _Nullable)outError

Parameters

  • outError - error information.

Returns

a value indicating whether connection was successful. If NO, additional information may be available in outError.

connect

Establishes a connection with the service. Connection is automatically performed when needed, but this manual call can be useful to make sure the connection is active before its first use to help reduce inital latency.

Calling connect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling open(false). The Connection object also provides events to monitor connections and disconnections.

- (void)connect

connectAsync:error:

Establishes a connection with the service. Connection is automatically performed when needed, but this manual call can be useful to make sure the connection is active before its first use to help reduce inital latency.

Calling connect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling open(false). The Connection object also provides events to monitor connections and disconnections.

- (BOOL)connectAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • completionHandler - the handler function called when connection is complete.
  • outError - error information.

Returns

a value indicating whether the request to connect started successfully. If NO, additional information may be available in outError.

connectAsync:

Establishes a connection with the service. Connection is automatically performed when needed, but this manual call can be useful to make sure the connection is active before its first use to help reduce inital latency.

Calling connect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling open(false). The Connection object also provides events to monitor connections and disconnections.

- (void)connectAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler

Parameters

  • completionHandler - the handler function called when connection is complete.

disconnect:

Disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.

Calling disconnect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling close(). The Connection object also provides events to monitor connections and disconnections.

- (BOOL)disconnect:(NSError * _Nullable * _Nullable)outError

Parameters

  • outError - error information.

Returns

a value indicating whether disconnection was successful. If NO, additional information may be available in outError.

disconnect

Disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.

Calling disconnect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling close(). The Connection object also provides events to monitor connections and disconnections.

- (void)disconnect

disconnectAsync:error:

Disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.

Calling disconnect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling close(). The Connection object also provides events to monitor connections and disconnections.

- (BOOL)disconnectAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • completionHandler - the handler function called when disconnection is complete.
  • outError - error information.

Returns

a value indicating whether the request to disconnect was received successfully. If NO, additional information may be available in outError.

disconnectAsync:

Disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.

Calling disconnect() on a DialogServiceConnector is functionally equivalent to initializing a Connection using initFromDialogServiceConnector and then calling close(). The Connection object also provides events to monitor connections and disconnections.

- (void)disconnectAsync:(SPXDialogServiceConnectorAsyncCompletionHandler _Nonnull)completionHandler

Parameters

  • completionHandler - the handler function called when disconnection is complete.

addRecognizedEventHandler:

Registers a provided handler function to be called when a final speech-to-text-result is received by this DialogServiceConnector instance.

- (void)addRecognizedEventHandler:(SPXDialogServiceConnectorRecognitionEventHandler _Nonnull)eventHandler

addRecognizingEventHandler:

Registers a provided handler function to be called when an intermediate speech-to-text-result is received by this DialogServiceConnector instance. A single speech-to-text interaction may receive many intermediate 'recognizing' results that correspond to a single, final 'recognized' result.

- (void)addRecognizingEventHandler:(SPXDialogServiceConnectorRecognitionEventHandler _Nonnull)eventHandler

addCanceledEventHandler:

Registers a provided handler function to be called when an interaction is abnormally terminated. This may happen for expected conditions, such as the end of provided file or audio stream input, or for unexpected error conditions. More information about the reason for the canceled event may be retrieved from the event data.

- (void)addCanceledEventHandler:(SPXDialogServiceConnectorCanceledEventHandler _Nonnull)eventHandler

addTurnStatusReceivedEventHandler:

Registers a provided handler function to be called when a turn status update is received from the dialog implementation that this DialogServiceConnector is connected to. A turn is a single execution session within the dialog implementation that may generate any number of activities over its course. The information in this payload represents success or failure conditions encountered by the dialog implementation over the course of this execution. This data facilitates the indication of completion or error conditions within the dialog implementation even when no explicit activity data is produced as part of a turn.

- (void)addTurnStatusReceivedEventHandler:(SPXDialogServiceConnectorTurnStatusReceivedEventHandler _Nonnull)eventHandler

addActivityReceivedEventHandler:

Registers a provided handler function to be called when an activity payload is received from the dialog implementation that this DialogServiceConnector is connected to. Activities may be sent by a dialog implementation at any time during a connection and there may be a many-to-one relationship between activities received and input, such as speech utterances, sent by this object.

- (void)addActivityReceivedEventHandler:(SPXDialogServiceConnectorActivityReceivedEventHandler _Nonnull)eventHandler

Properties

authorizationToken

@property (readwrite, copy, nonatomic) NSString * _Nullable authorizationToken;

The authorization token used to communicate with the speech service.

Note: The caller needs to ensure that the authorization token is valid. Before the authorization token expires, the caller needs to refresh it by calling this setter with a new valid token.

speechActivityTemplate

@property (readwrite, copy, nonatomic) NSString * _Nullable speechActivityTemplate;

A JSON template for activity payload data that will be provided to the speech service for the next conversation. The service will attempt to merge this template into all activities sent to the dialog backend, whether originated by the client with SendActivityAsync or generated by the service, as is the case with speech-to-text results. This allows a client to ensure consistent metadata information is provided to the dialog implementation across interactions.