hangouts.md

Botkit for Hangouts Class Reference

← Botkit Documentation ← Class Index

This is a class reference for all the methods exposed by the botbuilder-adapter-hangouts package.

Classes

• HangoutsAdapter
• HangoutsBotWorker

Interfaces

• HangoutsAdapterOptions

---

HangoutsAdapter

Connect Botkit or BotBuilder to Google Hangouts

To use this class in your application, first install the package:

npm install --save botbuilder-adapter-hangouts

Then import this and other classes into your code:

const { HangoutsAdapter } = require('botbuilder-adapter-hangouts');

This class includes the following methods:

• continueConversation()
• deleteActivity()
• processActivity()
• sendActivities()
• updateActivity()

Create a new HangoutsAdapter()

Parameters

Argument	Type	Description
options	HangoutsAdapterOptions	An object containing API credentials and a webhook verification token

Create an adapter to handle incoming messages from Google Hangouts and translate them into a standard format for processing by your bot.

Use with Botkit:

const adapter = new HangoutsAdapter({
     token: process.env.GOOGLE_TOKEN,
     google_auth_params: {
         credentials: process.env.GOOGLE_CREDS
     }
});
const controller = new Botkit({
     adapter: adapter,
     // ... other configuration options
});

Use with BotBuilder:

const adapter = new HangoutsAdapter({
     token: process.env.GOOGLE_TOKEN,
     google_auth_params: {
         credentials: process.env.GOOGLE_CREDS
     }
});
// set up restify...
const server = restify.createServer();
server.use(restify.plugins.bodyParser());
server.post('/api/messages', (req, res) => {
     adapter.processActivity(req, res, async(context) => {
         // do your bot logic here!
     });
});

HangoutsAdapter Class Methods

continueConversation()

Standard BotBuilder adapter method for continuing an existing conversation based on a conversation reference. BotBuilder reference docs

Parameters

Argument	Type	description
reference	Partial<ConversationReference>	A conversation reference to be applied to future messages.
logic		A bot logic function that will perform continuing action in the form async(context) => { ... }

deleteActivity()

Standard BotBuilder adapter method to delete a previous message. BotBuilder reference docs.

Parameters

Argument	Type	description
context	TurnContext	A TurnContext representing the current incoming message and environment. (Not used)
reference	Partial<ConversationReference>	An object in the form {activityId: <id of message to delete>}

processActivity()

Accept an incoming webhook request and convert it into a TurnContext which can be processed by the bot's logic.

Parameters

Argument	Type	description
req	any	A request object from Restify or Express
res	any	A response object from Restify or Express
logic		A bot logic function in the form async(context) => { ... }

sendActivities()

Standard BotBuilder adapter method to send a message from the bot to the messaging API. BotBuilder reference docs.

Parameters

Argument	Type	description
context	TurnContext	A TurnContext representing the current incoming message and environment. (Not used)
activities		An array of outgoing activities to be sent back to the messaging API.

updateActivity()

Standard BotBuilder adapter method to update a previous message with new content. BotBuilder reference docs.

Parameters

Argument	Type	description
context	TurnContext	A TurnContext representing the current incoming message and environment. (Not used)
activity	Partial<Activity>	The updated activity in the form {id: <id of activity to update>, text: <updated text>, cards?: [<array of updated hangouts cards>]}

HangoutsBotWorker

This is a specialized version of Botkit's core BotWorker class that includes additional methods for interacting with Google Hangouts. It includes all functionality from the base class, as well as the extension methods below.

When using the HangoutsAdapter with Botkit, all bot objects passed to handler functions will include these extensions.

To use this class in your application, first install the package:

npm install --save botbuilder-adapter-hangouts

Then import this and other classes into your code:

const { HangoutsBotWorker } = require('botbuilder-adapter-hangouts');

This class includes the following methods:

• deleteMessage()
• replyInThread()
• replyWithNew()
• replyWithUpdate()
• startConversationInThread()
• updateMessage()

Properties and Accessors

Name	Type	Description
api	any	Access to the official Google API client for Hangouts

HangoutsBotWorker Class Methods

deleteMessage()

Delete an existing message.

Parameters

Argument	Type	description
update	Partial<BotkitMessage>	An object in the form of {id: <id of message to delete>}

// send a reply, capture the results
let sent = await bot.reply(message,'this is my original reply...');

// delete the sent message using the sent.id field
await bot.deleteMessage(sent);

replyInThread()

Reply to an incoming message in a brand new thread. Works for a single message reply - if multiple replies or replying with a dialog is necessary, use startConversationInThread.

Parameters

Argument	Type	description
src	any	An incoming message or event object
resp	any	A reply message containing text and/or cards

controller.hears('thread','message', async(bot, message) =>{
     await bot.replyInThread(message,'This will appear in a new thread.');
});

replyWithNew()

Reply to a card_click event with a new message. See Google doc for interactive cards →.

Parameters

Argument	Type	description
src	any	An incoming event object representing a card_clicked event
resp	Partial<BotkitMessage>	A reply message containing text and/or cards

When a user clicks a button contained in a card attachment, a card_clicked event will be emitted. In order to reply to the incoming event with a new message (rather than replacing the original card), use this method!

controller.on('card_clicked', async(bot, message) => {
     // check message.action.actionMethodName to see what button was clicked...
     await bot.replyWithNew(message,'Reply to button click!');
})

replyWithUpdate()

Reply to a card_click event with an update to the original message. See Google doc for interactive cards →.

Parameters

Argument	Type	description
src	any	An incoming event object representing a card_clicked event
resp	Partial<BotkitMessage>	A reply message containing text and/or cards

When a user clicks a button contained in a card attachment, a card_clicked event will be emitted. In order to reply to the incoming event by replacing the original message, use this method!

controller.on('card_clicked', async(bot, message) => {
     // check message.action.actionMethodName to see what button was clicked...
     await bot.replyWithUpdate(message,'Reply to button click!');
})

startConversationInThread()

Switch the bot's active context to a new thread. Use this to change the location of a bot's responses or calls to beginDialog into a new conversation thread (rather than continuing in the same thread as the originating message)

Parameters

Argument	Type	description
spaceName	string	The name of the main space - usually message.channel
userId	string	The id of the user conducting the conversation - usually message.user
threadKey (optional)	string	An optional key definining the thread - if one is not provided, a random one is generated.

controller.hears('new thread', 'message', async(bot, message) => {

     // change to a new thread
     await bot.startConversationInThread(message.channel, message.user);

     // begin a dialog in the new thread
     await bot.beginDialog('foo');

});

updateMessage()

Update an existing message with new content.

Parameters

Argument	Type	description
update	Partial<BotkitMessage>	An object in the form {id: <id of message to update>, text: <new text>, card: <array of card objects>}

// send a reply, capture the results
let sent = await bot.reply(message,'this is my original reply...');

// update the sent message using the sent.id field
await bot.updateMessage({
     id: sent.id,
     text: 'this is an update!',
})

Interface HangoutsAdapterOptions

Fields

Name	Type	Description
enable_incomplete	boolean	Allow the adapter to startup without a complete configuration. This is risky as it may result in a non-functioning or insecure adapter. This should only be used when getting started.
google_auth_params		Parameters passed to the Google API client library which is in turn used to send messages. Define credentials per the GoogleAuthOptions defined here, OR, specify GOOGLE_APPLICATION_CREDENTIALS in environment as described in the Google docs.
token	string	Shared secret token used to validate the origin of incoming webhooks. Get this from the Google API console for your bot app - it is found on the Configuration tab under the heading "Verification Token". If defined, the origin of all incoming webhooks will be validated and any non-matching requests will be rejected.