ChatConnector class

Package:

botbuilder

Connects a UniversalBot to multiple channels via the Bot Framework.

Constructors

ChatConnector(IChatConnectorSettings)

Creates a new instnace of the ChatConnector.

Methods

delete(IAddress, (err: Error) => void)	Deletes an existing message.
deleteConversationMember(string, string, string, (err: Error) => void)	Deletes the data for an individual user within a conversation.
emulateOAuthCards(string, boolean, (err: Error) => void)	Tells the token service to emulate the sending of OAuthCards.
exportBotStateData(string, string, string | undefined, (err: Error, results: IBotStateDataResult) => void)	Exports bot state data persisted for a given channel.
getAccessToken((err: Error, accessToken: string) => void)	Gets the current access token for the bot.
getConversationPagedMembers(string, string, number | undefined, string | undefined, (err: Error, result?: IPagedMembersResult) => void)	Enumerate the members of a conversation one page at a time. This REST API takes a ConversationId. Optionally a pageSize and/or continuationToken can be provided. It returns a PagedMembersResult, which contains an array of ChannelAccounts representing the members of the conversation and a continuation token that can be used to get more values. One page of ChannelAccounts records are returned with each call. The number of records in a page may vary between channels and calls. The pageSize parameter can be used as a suggestion. If there are no additional results the response will not contain a continuation token. If there are no members in the conversation the Members will be empty or not present in the response. A response to a request that has a continuation token from a prior request may rarely return members from a previous request.
getConversations(string, string | undefined, (err: Error, result?: IConversationsResult) => void)	Retrieves a list of all the conversations the bot has on a given channel. Results will be sent back to the bot in pages along with a continuationToken that can be used to fetch the next page of conversations. This data can be used to delete all of the conversation data for a user via the deleteConversationMember() method.
getData(IBotStorageContext, (err: Error, data: IBotStorageData) => void)	Reads in data from the Bot Frameworks state service.
getSignInLink(IChatConnectorAddress, string, (err: Error, link: string) => void)	Gets a signin link from the token server that can be sent as part of a SigninCard.
getUserToken(IChatConnectorAddress, string, string | undefined, (err: Error, results: ITokenResponse) => void)	Attempts to retrieve the token for a user that's in a signin flow.
listen()	Registers an Express or Restify style hook to listen for new messages.
onEvent((events: IEvent[], callback?: (err: Error) => void) => void)	Called by the UniversalBot at registration time to register a handler for receiving incoming events from a channel.
onInvoke((event: IEvent, cb?: (err: Error, body: any, status?: number) => void) => void)	Used to register a handler for receiving incoming invoke events.
saveData(IBotStorageContext, IBotStorageData, (err: Error) => void)	Writes out data to the Bot Frameworks state service.
send(IMessage[], (err: Error, addresses?: IAddress[]) => void)	Called by the UniversalBot to deliver outgoing messages to a user.
sendConversationHistory(string, string, ITranscript, (err: Error, results: any) => void)	This method allows you to upload the historic activities to the conversation. Sender must ensure that the historic activities have unique ids and appropriate timestamps. The ids are used by the client to deal with duplicate activities and the timestamps are used by the client to render the activities in the right order.
signOutUser(IChatConnectorAddress, string, (err: Error, results: ITokenResponse) => void)	Signs the user out with the token server.
startConversation(IAddress, (err: Error, address?: IAddress) => void)	Called when a UniversalBot wants to start a new proactive conversation with a user. The connector should return a properly formated address object with a populated conversation field.
update(IMessage, (err: Error, address?: IAddress) => void)	Replaces an existing message with a new one.

Constructor Details

ChatConnector(IChatConnectorSettings)

Creates a new instnace of the ChatConnector.

new ChatConnector(settings?: IChatConnectorSettings)

Parameters

settings

IChatConnectorSettings

(Optional) config params that let you specify the bots App ID & Password you were assigned in the Bot Frameworks developer portal.

Method Details

delete(IAddress, (err: Error) => void)

Deletes an existing message.

function delete(address: IAddress, done: (err: Error) => void)

Parameters

address

IAddress

done

(err: Error) => void

deleteConversationMember(string, string, string, (err: Error) => void)

Deletes the data for an individual user within a conversation.

function deleteConversationMember(serviceUrl: string, conversationId: string, memberId: string, done: (err: Error) => void)

Parameters

serviceUrl

string

The service url for the channel being updated. This can be found in the address.serviceUrl for a message sent to the bot.

conversationId

string

ID of the conversation with the member to delete.

memberId

string

ID of the member to delete.

done

(err: Error) => void

Callback invoked upon completion of the delete operation.

emulateOAuthCards(string, boolean, (err: Error) => void)

Tells the token service to emulate the sending of OAuthCards.

function emulateOAuthCards(serviceUrl: string, emulate: boolean, done: (err: Error) => void)

Parameters

serviceUrl

string

The service url for the channel being queried. This can be found in the address.serviceUrl for a message sent to the bot.

emulate

boolean

If true the token service will emulate the sending of OAuthCards.

done

(err: Error) => void

Callback invoked upon completion of the operation.

exportBotStateData(string, string, string | undefined, (err: Error, results: IBotStateDataResult) => void)

Exports bot state data persisted for a given channel.

function exportBotStateData(serviceUrl: string, channelId: string, continuationToken: string | undefined, done: (err: Error, results: IBotStateDataResult) => void)

Parameters

serviceUrl

string

The service url for the channel being queried. This can be found in the address.serviceUrl for a message sent to the bot.

channelId

string

ID of the channel being exported. This can be found in the address.channelId for a message sent to the bot.

continuationToken

string | undefined

The continuation token for the next page of results to fetch. This should be undefined for the first page requested.

done

(err: Error, results: IBotStateDataResult) => void

Callback to recieve the next page of results.

getAccessToken((err: Error, accessToken: string) => void)

Gets the current access token for the bot.

function getAccessToken(callback: (err: Error, accessToken: string) => void)

Parameters

callback

(err: Error, accessToken: string) => void

getConversationPagedMembers(string, string, number | undefined, string | undefined, (err: Error, result?: IPagedMembersResult) => void)

Enumerate the members of a conversation one page at a time. This REST API takes a ConversationId. Optionally a pageSize and/or continuationToken can be provided. It returns a PagedMembersResult, which contains an array of ChannelAccounts representing the members of the conversation and a continuation token that can be used to get more values.

One page of ChannelAccounts records are returned with each call. The number of records in a page may vary between channels and calls. The pageSize parameter can be used as a suggestion. If there are no additional results the response will not contain a continuation token. If there are no members in the conversation the Members will be empty or not present in the response.

A response to a request that has a continuation token from a prior request may rarely return members from a previous request.

function getConversationPagedMembers(serviceUrl: string, conversationId: string, pageSize: number | undefined, continuationToken: string | undefined, done: (err: Error, result?: IPagedMembersResult) => void)

Parameters

serviceUrl

string

The service url for the channel being queried. This can be found in the address.serviceUrl for a message sent to the bot.

conversationId

string

The conversationId

pageSize

number | undefined

The number of results to get (default is 20)

continuationToken

string | undefined

The continuation token for the next page of results to fetch. This should be undefined for the first page requested.

done

(err: Error, result?: IPagedMembersResult) => void

Callback to recieve the next page of results.

getConversations(string, string | undefined, (err: Error, result?: IConversationsResult) => void)

Retrieves a list of all the conversations the bot has on a given channel. Results will be sent back to the bot in pages along with a continuationToken that can be used to fetch the next page of conversations. This data can be used to delete all of the conversation data for a user via the deleteConversationMember() method.

function getConversations(serviceUrl: string, continuationToken: string | undefined, done: (err: Error, result?: IConversationsResult) => void)

Parameters

serviceUrl

string

The service url for the channel being queried. This can be found in the address.serviceUrl for a message sent to the bot.

continuationToken

string | undefined

The continuation token for the next page of results to fetch. This should be undefined for the first page requested.

done

(err: Error, result?: IConversationsResult) => void

Callback to recieve the next page of results.

getData(IBotStorageContext, (err: Error, data: IBotStorageData) => void)

Reads in data from the Bot Frameworks state service.

function getData(context: IBotStorageContext, callback: (err: Error, data: IBotStorageData) => void)

Parameters

context

IBotStorageContext

callback

(err: Error, data: IBotStorageData) => void

getSignInLink(IChatConnectorAddress, string, (err: Error, link: string) => void)

Gets a signin link from the token server that can be sent as part of a SigninCard.

function getSignInLink(address: IChatConnectorAddress, connectionName: string, done: (err: Error, link: string) => void)

Parameters

address

IChatConnectorAddress

Address of the user and channel to get signin link for.

connectionName

string

Name of the auth connection to use.

done

(err: Error, link: string) => void

Callback to retrieve the link.

getUserToken(IChatConnectorAddress, string, string | undefined, (err: Error, results: ITokenResponse) => void)

Attempts to retrieve the token for a user that's in a signin flow.

function getUserToken(address: IChatConnectorAddress, connectionName: string, magicCode: string | undefined, done: (err: Error, results: ITokenResponse) => void)

Parameters

address

IChatConnectorAddress

Address of the user and channel to login.

connectionName

string

Name of the auth connection to use.

magicCode

string | undefined

(Optional) Optional user entered code to validate.

done

(err: Error, results: ITokenResponse) => void

Callback to retrieve the users token.

listen()

Registers an Express or Restify style hook to listen for new messages.

function listen()

Returns

(req: any, res: any) => void

onEvent((events: IEvent[], callback?: (err: Error) => void) => void)

Called by the UniversalBot at registration time to register a handler for receiving incoming events from a channel.

function onEvent(handler: (events: IEvent[], callback?: (err: Error) => void) => void)

Parameters

handler

(events: IEvent[], callback?: (err: Error) => void) => void

onInvoke((event: IEvent, cb?: (err: Error, body: any, status?: number) => void) => void)

Used to register a handler for receiving incoming invoke events.

function onInvoke(handler: (event: IEvent, cb?: (err: Error, body: any, status?: number) => void) => void)

Parameters

handler

(event: IEvent, cb?: (err: Error, body: any, status?: number) => void) => void

saveData(IBotStorageContext, IBotStorageData, (err: Error) => void)

Writes out data to the Bot Frameworks state service.

function saveData(context: IBotStorageContext, data: IBotStorageData, callback?: (err: Error) => void)

Parameters

context

IBotStorageContext

data

IBotStorageData

callback

(err: Error) => void

send(IMessage[], (err: Error, addresses?: IAddress[]) => void)

Called by the UniversalBot to deliver outgoing messages to a user.

function send(messages: IMessage[], done: (err: Error, addresses?: IAddress[]) => void)

Parameters

messages

IMessage[]

done

(err: Error, addresses?: IAddress[]) => void

sendConversationHistory(string, string, ITranscript, (err: Error, results: any) => void)

This method allows you to upload the historic activities to the conversation. Sender must ensure that the historic activities have unique ids and appropriate timestamps. The ids are used by the client to deal with duplicate activities and the timestamps are used by the client to render the activities in the right order.

function sendConversationHistory(serviceUrl: string, conversationId: string, transcript: ITranscript, done: (err: Error, results: any) => void)

Parameters

serviceUrl

string

The service url for the channel being queried. This can be found in the address.serviceUrl for a message sent to the bot.

conversationId

string

ID of the conversation with the history to send.

transcript

ITranscript

done

(err: Error, results: any) => void

signOutUser(IChatConnectorAddress, string, (err: Error, results: ITokenResponse) => void)

Signs the user out with the token server.

function signOutUser(address: IChatConnectorAddress, connectionName: string, done: (err: Error, results: ITokenResponse) => void)

Parameters

address

IChatConnectorAddress

Address of the user and channel to signout.

connectionName

string

Name of the auth connection to use.

done

(err: Error, results: ITokenResponse) => void

Callback to retrieve the users token.

startConversation(IAddress, (err: Error, address?: IAddress) => void)

Called when a UniversalBot wants to start a new proactive conversation with a user. The connector should return a properly formated address object with a populated conversation field.

function startConversation(address: IAddress, done: (err: Error, address?: IAddress) => void)

Parameters

address

IAddress

done

(err: Error, address?: IAddress) => void

update(IMessage, (err: Error, address?: IAddress) => void)

Replaces an existing message with a new one.

function update(message: IMessage, done: (err: Error, address?: IAddress) => void)

Parameters

message

IMessage

done

(err: Error, address?: IAddress) => void