DialogServiceConnector Class

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.

Inheritance

builtins.object

DialogServiceConnector

Constructor

DialogServiceConnector(dialog_service_config: DialogServiceConfig, audio_config: AudioConfig | None = None)

Parameters

Name	Description
dialog_service_config Required	The config for the dialog service, either for bot framework or custom commands.
audio_config	The config for the audio input. Default value: None

Methods

connect	Synchronously 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 initial latency. On return, the connection might not be ready yet. Please subscribe to the connected event of the Connection instance to be notified when the connection to service is established. Please use Connection to retrieve instance by using from_dialog_service_connector method.
connect_async	Asynchronously 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 initial latency.
disconnect	Synchronously disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.
disconnect_async	Asynchronously disconnects from the service. Subsequent calls that require a connection will still automatically reconnect after manual disconnection.
listen_once	Synchronously starts 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.
listen_once_async	Asynchronously starts 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.
send_activity	Synchronously sends a data payload to dialog backend service that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation in the service 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.
send_activity_async	Asynchronously sends an activity to the backing dialog, see description details at send_activity
start_keyword_recognition	Synchronously starts 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 listen_once_async 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. Call stop_keyword_recognition_async to stop the keyword initiated recognition.
start_keyword_recognition_async	Asynchronously configures the dialog service connector with the given keyword model. After calling this method, the connector is listening for the keyword to start the recognition. Call stop_keyword_recognition_async to stop the keyword initiated recognition. See start_keyword_recognition for detailed description of the functionality.
stop_keyword_recognition	Synchronously stops the keyword initiated recognition.
stop_keyword_recognition_async	Asynchronously stops the keyword initiated recognition.
stop_listening	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 stop_listening_async if a stop is desired in response to an event.
stop_listening_async	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.

connect

Synchronously 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 initial latency.

On return, the connection might not be ready yet. Please subscribe to the connected event of the Connection instance to be notified when the connection to service is established. Please use Connection to retrieve instance by using from_dialog_service_connector method.

connect()

connect_async

Asynchronously 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 initial latency.

connect_async()

Returns

Type	Description
	A future that is fulfilled once connection has been initialized.

disconnect

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

disconnect()

disconnect_async

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

disconnect_async()

Returns

Type	Description
	A future that is fulfilled when disconnected.

listen_once

Synchronously starts 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.

listen_once() -> SpeechRecognitionResult

Returns

Type	Description
	the speech-to-text result from the speech recognition.

listen_once_async

Asynchronously starts 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.

listen_once_async() -> ResultFuture

Returns

Type	Description
	A future containing the speech-to-text result value of the asynchronous recognition.

send_activity

Synchronously sends a data payload to dialog backend service that this DialogServiceConnector instance is connected to. This is usually a JSON document with its schema determined by the dialog implementation in the service 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.

send_activity(activity: str) -> str

Parameters

Name	Description
activity Required	the serialized payload of an activity to send.

Returns

Type

Description

an interaction identifier acquired when the activity is acknowledged by 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.

send_activity_async

Asynchronously sends an activity to the backing dialog, see description details at send_activity

send_activity_async(activity: str) -> ResultFuture

Parameters

Name	Description
activity Required	the serialized payload of an activity to send.

Returns

Type	Description
	A future containing the result value of the asynchronous activity sending operation.

start_keyword_recognition

Synchronously starts 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 listen_once_async 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.

Call stop_keyword_recognition_async to stop the keyword initiated recognition.

start_keyword_recognition(model: KeywordRecognitionModel)

Parameters

Name	Description
model Required	the keyword recognition model that specifies the keyword to be recognized.

start_keyword_recognition_async

Asynchronously configures the dialog service connector with the given keyword model. After calling this method, the connector is listening for the keyword to start the recognition. Call stop_keyword_recognition_async to stop the keyword initiated recognition.

See start_keyword_recognition for detailed description of the functionality.

start_keyword_recognition_async(model: KeywordRecognitionModel)

Parameters

Name	Description
model Required	the keyword recognition model that specifies the keyword to be recognized.

Returns

Type	Description
	A future that is fulfilled once recognition has been initialized.

stop_keyword_recognition

Synchronously stops the keyword initiated recognition.

stop_keyword_recognition()

stop_keyword_recognition_async

Asynchronously stops the keyword initiated recognition.

stop_keyword_recognition_async()

Returns

Type	Description
	A future that is fulfilled once recognition has been stopped.

stop_listening

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 stop_listening_async if a stop is desired in response to an event.

stop_listening()

Returns

Type	Description
	A future that is fulfilled once listening has been stopped.

stop_listening_async

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.

stop_listening_async()

Returns

Type	Description
	A future that is fulfilled once listening has been stopped.

Attributes

activity_received

Signals that an activity was received from the backend.

Callbacks connected to this signal are called with a ActivityReceivedEventArgs, instance as the single argument, dependent on the type of recognizer.

authorization_token

The authorization token that will be used for connecting to the 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. Otherwise, the recognizer will encounter errors during recognition.

canceled

Signal for events containing canceled recognition results (indicating a recognition attempt that was canceled as a result or a direct cancellation request or, alternatively, a transport or protocol failure).

Callbacks connected to this signal are called with a SpeechRecognitionCanceledEventArgs, instance as the single argument.

recognized

Signal for events containing final recognition results (indicating a successful recognition attempt).

Callbacks connected to this signal are called with a SpeechRecognitionEventArgs, instance as the single argument, dependent on the type of recognizer.

recognizing

Signal for events containing intermediate recognition results.

Callbacks connected to this signal are called with a SpeechRecognitionEventArgs, instance as the single argument.

session_started

Signal for events indicating the start of a recognition session (operation).

Callbacks connected to this signal are called with a SessionEventArgs instance as the single argument.

session_stopped

Signal for events indicating the end of a recognition session (operation).

Callbacks connected to this signal are called with a SessionEventArgs instance as the single argument.

speech_activity_template

Gets the JSON template 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.

speech_end_detected

Signal for events indicating the end of speech.

Callbacks connected to this signal are called with a RecognitionEventArgs instance as the single argument.

speech_start_detected

Signal for events indicating the start of speech.

Callbacks connected to this signal are called with a RecognitionEventArgs instance as the single argument.

turn_status_received

Signals that a turn status update was received from the backend.

Callbacks connected to this signal are called with a TurnStatusReceivedEventArgs, instance as the single argument.