CallSession class

Package:

botbuilder-calling

Manages the bots conversation with a user.

Constructors

CallSession(ICallSessionOptions)

Creates an instance of the session.

Properties

conversationData	Shared conversation data that's visible to all members of the conversation.
dialogData	Data that's only visible to the current dialog.
library	The bots root library of dialogs.
message	The message recieved from the user. For bot originated messages this may only contain the "to" & "from" fields.
privateConversationData	Private conversation data that's only visible to the user.
sessionState	Sessions current state information.
userData	Data for the user that's persisted across all conversations with the bot.

Methods

answer()	Manually answers the call. The call will be automatically answered when the bot takes an action.
beginDialog<T>(string, T)	Passes control of the conversation to a new dialog. The current dialog will be suspended until the child dialog completes. Once the child ends the current dialog will receive a call to dialogResumed() where it can inspect any results returned from the child.
dispatch(ISessionState, IEvent)	Dispatches a message for processing. The session will call any installed middleware before the message to the active dialog for processing.
endConversation(string | string[] | IAction | IIsAction, any[])	Ends the current conversation and optionally sends a message to the user. The call will be automatically hungup or rejected.
endDialog(string | string[] | IAction | IIsAction, any[])	Ends the current dialog and optionally sends a message to the user. The parent will be resumed with an IDialogResult.resumed reason of completed.
endDialogWithResult(IDialogResult<any>)	Ends the current dialog and optionally returns a result to the dialogs parent.
error(Error)	Signals that an error occured. The bot will signal the error via an on('error', err) event.
gettext(string, any[])	Loads a localized string for the messages language. If arguments are passed the localized string will be treated as a template and formatted using sprintf-js (see their docs for details.)
hangup()	Manually ends an established call. The call will be automatically ended when the bot stops prompting the user for input.
isReset()	Returns true if the session has been reset.
messageSent()	Returns true if a message has been sent for this session.
ngettext(string, string, number)	Loads the plural form of a localized string for the messages language. The output string will be formatted to include the count by replacing %d in the string with the count.
on(string, Function)	Registers an event listener.
reject()	Rejects an incoming call.
replaceDialog<T>(string, T)	Ends the current dialog and starts a new one its place. The parent dialog will not be resumed until the new dialog completes.
reset(string, any)	Clears the sessions callstack and restarts the conversation with the configured dialogId.
save()	Triggers saving of changes made to dialogData, userData, conversationdata, or [privateConversationData'(#privateconversationdata).
send(string | string[] | IAction | IIsAction, any[])	Sends a PlayPrompt action to the user.
sendBatch()	Immediately ends the current batch and delivers any queued up messages.

Constructor Details

CallSession(ICallSessionOptions)

Creates an instance of the session.

new CallSession(options: ICallSessionOptions)

Parameters

options

ICallSessionOptions

Sessions configuration options.

Property Details

conversationData

Shared conversation data that's visible to all members of the conversation.

conversationData: any

Property Value

any

dialogData

Data that's only visible to the current dialog.

dialogData: any

Property Value

any

library

The bots root library of dialogs.

library: Library

Property Value

Library

message

The message recieved from the user. For bot originated messages this may only contain the "to" & "from" fields.

message: IEvent

Property Value

IEvent

privateConversationData

Private conversation data that's only visible to the user.

privateConversationData: any

Property Value

any

sessionState

Sessions current state information.

sessionState: ISessionState

Property Value

ISessionState

userData

Data for the user that's persisted across all conversations with the bot.

userData: any

Property Value

any

Method Details

answer()

Manually answers the call. The call will be automatically answered when the bot takes an action.

function answer()

Returns

CallSession

beginDialog<T>(string, T)

Passes control of the conversation to a new dialog. The current dialog will be suspended until the child dialog completes. Once the child ends the current dialog will receive a call to dialogResumed() where it can inspect any results returned from the child.

function beginDialog<T>(id: string, args?: T)

Parameters

id

string

Unique ID of the dialog to start.

args

T

(Optional) arguments to pass to the dialogs begin() method.

Returns

CallSession

dispatch(ISessionState, IEvent)

Dispatches a message for processing. The session will call any installed middleware before the message to the active dialog for processing.

function dispatch(sessionState: ISessionState, message: IEvent)

Parameters

sessionState

ISessionState

The current session state. If null a new conversation will be started beginning with the configured dialogId.

message

IEvent

The message to dispatch.

Returns

CallSession

endConversation(string | string[] | IAction | IIsAction, any[])

Ends the current conversation and optionally sends a message to the user. The call will be automatically hungup or rejected.

function endConversation(action?: string | string[] | IAction | IIsAction, args: any[])

Parameters

action

string | string[] | IAction | IIsAction

(Optional)

• action: {string} - Text of the message to send. The message will be localized using the sessions configured localizer. If arguments are passed in the message will be formatted using sprintf-js.
• action: {string[]} - The sent message will be chosen at random from the array.
• action: {IAction|IIsAction} - Action to send.

args

any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

CallSession

endDialog(string | string[] | IAction | IIsAction, any[])

Ends the current dialog and optionally sends a message to the user. The parent will be resumed with an IDialogResult.resumed reason of completed.

function endDialog(action?: string | string[] | IAction | IIsAction, args: any[])

Parameters

action

string | string[] | IAction | IIsAction

(Optional)

• action: {string} - Text of the message to send. The message will be localized using the sessions configured localizer. If arguments are passed in the message will be formatted using sprintf-js.
• action: {string[]} - The sent message will be chosen at random from the array.
• action: {IAction|IIsAction} - Action to send.

args

any[]

(Optional) arguments used to format the final output text when message is a {string|string[]}.

Returns

CallSession

endDialogWithResult(IDialogResult<any>)

Ends the current dialog and optionally returns a result to the dialogs parent.

function endDialogWithResult(result?: IDialogResult<any>)

Parameters

result

IDialogResult<any>

Returns

CallSession

error(Error)

Signals that an error occured. The bot will signal the error via an on('error', err) event.

function error(err: Error)

Parameters

err

Error

Error that occured.

Returns

CallSession

gettext(string, any[])

Loads a localized string for the messages language. If arguments are passed the localized string will be treated as a template and formatted using sprintf-js (see their docs for details.)

function gettext(msgid: string, args: any[])

Parameters

msgid

string

String to use as a key in the localized string table. Typically this will just be the english version of the string.

args

any[]

(Optional) arguments used to format the final output string.

Returns

string

hangup()

Manually ends an established call. The call will be automatically ended when the bot stops prompting the user for input.

function hangup()

Returns

CallSession

isReset()

Returns true if the session has been reset.

function isReset()

Returns

boolean

messageSent()

Returns true if a message has been sent for this session.

function messageSent()

Returns

boolean

ngettext(string, string, number)

Loads the plural form of a localized string for the messages language. The output string will be formatted to include the count by replacing %d in the string with the count.

function ngettext(msgid: string, msgid_plural: string, count: number)

Parameters

msgid

string

Singular form of the string to use as a key in the localized string table. Use %d to specify where the count should go.

msgid_plural

string

Plural form of the string to use as a key in the localized string table. Use %d to specify where the count should go.

count

number

Count to use when determining whether the singular or plural form of the string should be used.

Returns

string

on(string, Function)

Registers an event listener.

function on(event: string, listener: Function)

Parameters

event

string

Name of the event. Event types:

• error: An error occured. IErrorEvent

listener

Function

Function to invoke.

reject()

Rejects an incoming call.

function reject()

Returns

CallSession

replaceDialog<T>(string, T)

Ends the current dialog and starts a new one its place. The parent dialog will not be resumed until the new dialog completes.

function replaceDialog<T>(id: string, args?: T)

Parameters

id

string

Unique ID of the dialog to start.

args

T

(Optional) arguments to pass to the dialogs begin() method.

Returns

CallSession

reset(string, any)

Clears the sessions callstack and restarts the conversation with the configured dialogId.

function reset(dialogId?: string, dialogArgs?: any)

Parameters

dialogId

string

(Optional) ID of the dialog to start.

dialogArgs

any

(Optional) arguments to pass to the dialogs begin() method.

Returns

CallSession

save()

Triggers saving of changes made to dialogData, userData, conversationdata, or [privateConversationData'(#privateconversationdata).

function save()

Returns

CallSession

send(string | string[] | IAction | IIsAction, any[])

Sends a PlayPrompt action to the user.

function send(action: string | string[] | IAction | IIsAction, args: any[])

Parameters

action

string | string[] | IAction | IIsAction

• action: {string} - Text of the message to send. The message will be localized using the sessions configured localizer. If arguments are passed in the message will be formatted using sprintf-js.
• action: {string[]} - The sent message will be chosen at random from the array.
• action: {IAction|IIsAction} - Action to send.

args

any[]

(Optional) arguments used to format the final output text when action is a {string|string[]}.

Returns

CallSession

sendBatch()

Immediately ends the current batch and delivers any queued up messages.

function sendBatch()