Lightweight framework for building bots and apps for Google Chat.
npm install @google/chat-sdkNote: This is not an official Google product.
This is an experimental framework for building Google Chat bots using Node.js.
1. Create a new project:
``shell`
npm init
2. Install the framework:
`shell`
npm install --save @google/chat-sdk
3. Create an index.js file for the bot:
`javascript
const { Bot } = require("@google/chat-sdk");
// Create the bot using http transport
// Note: set the project number to enable authentication of incoming
// messages.
const bot = Bot.http({
projectNumber: process.env.GOOGLE_PROJECT_NUMBER,
});
// Echo back any at-mentions
bot.message(async ({reply, messageText}) => {
await reply({
text: You said: ${messageText}
});
});
// Start the bot
bot.start();
`
See the Google Chat bot documentation
for instructions on how to register your bot.
You can also experiment on glitch.com by remixing this project
The framework supports both HTTPS and Cloud PubSub transports.
To create a bot using https, use the Bot.http(opts) factory method. Options include:
* port (default: 3000) - Port to listen onpath
* (default: '/') - URL path for incoming messages.trustProxy
* (default: true) - Enables recognition of X-forward-for headers in requestsprojectNumber
* (default: undefined) - Project # of the bot in the developer console.
Enables verification of the authorization headers in incoming events.
For PubSub, use the Bot.pubsub(opts) factory method. Options include:
* subscriptionName (default: undefined) - Name of the subscription to listen on
Note: PubSub bots do not currently support all features and may have issues with interactive
cards and dialogs.
You can also implement your own transport (e.g. a fake for testing) by implementing the
Transport interface and
setting the transport via the bot.transport property.
If either Bot.http() or Bot.pubsub() are called without options, the bot will attempt to autoconfigure
itself based on the environment.
* PROJECT_NUMBER - Project number for validating incoming JWTs. When running on GCP, the bot will alsoPORT
attempt to read this from the GCP Metadata API.
* - Port number to listen onGOOGLE_CHAT_SUBSCRIPTION_NAME
* - The name of the subscription the bot will receive messages on (pubsub only)GOOGLE_APPLICATION_CREDENTIALS
* - Te bot uses the application default credentialsGOOGLE_APPLICATION_CREDENTIALS
mechanism to authenticate itself. When running on GCP, the framework should automatically discover
its credentials. When running locally or on another cloud, set the
environment variable to the service account credentials for the bot.
Add event handlers to the bot to respond to user interactions. The bot framework automatically
detects the type of event based on the event type and message content and dispatches
the event to the appropriate handler.
Handlers are called with a context object
that provides quick access to common fields in the event along with methods for replying to, creating, and updating
messages and dialogs.
Note that the context object can be safely destructured if desired.
Register a message handler using bot.message() method. THe handler will be invoked
for any message that @ mentions the bot or user text in a DM. For example:
`typescript`
// Echo back any useer text
bot.message(async (ctx) => {
await ctx.reply({
text: ctx.messageText
})
})
Message handlers typically reply with the ctx.reply() method to post a new message in the conversation.
Bots can also register handlers with regular expressions to filter and match. When filters
are used, multiple message handlers can be registered. Note that only 1 handler is invoked,
and patterns are evaluated in the order they're registered.
`typescript
// Respond to "@bot help"
bot.message(/help/, async (ctx) => {
await ctx.reply({
text: 'Here are some things you can try...'
});
});
// Catch all other messages.
bot.message(async (ctx) => {
// ....
})
`
Register a slash command handler using bot.command() method. Slash commands can be identified
by either the numeric command ID or the command name itself:
`typescript
// Handle the slash command with id 1
bot.command(1, async (ctx) => {
// ...
})
// Handle the '/poll' command
bot.command('/poll', async (ctx) => {
// ...
})
`
For slash commands that display dialogs, use ctx.showDialog() to reply with the dialog:
`typescript`
bot.command('/poll', async (ctx) => {
const pollConfigCard = {
sections: [
{
widgets: [
// ...
]
}
]
};
await ctx.showDialog(pollConfigCard)
})
Register action handlers for interactive cards and dialogs using bot.action() with the action name:
`typescript`
// Handle the slash command with id 1
bot.action('submit', async (ctx) => {
// ...
})
For bots that have configured URLs to unfurl in the developer console, use the
bot.unfurl() method to handle unfurl requests. A bot can use either a single generic handlerctx.urlPatternResult
for all unfurl requests or multiple hanlders with URLPattern
to match specific URLs. When patterns are used, the resulting match and any capture groups
are exposed via .
Use ctx.updateMessage() to display additional information where the URL was referenced.
Example with pattern matching:
`typescript`
bot.unfurl({
hostname: ':customer.issuetracker.example.com',
pathname: '/issues/:issueId'
}, async (ctx) => {
const customer = ctx.urlPatternResult.hostname.groups.customer;
const issueId = ctx.urlPatternResult.pathname.groups.issueId;
const issue = lookupIssue(customer, issueId);
const card = buildIssueCard(issue);
await ctx.updateMessage({
cards: [card]
})
})
To be notified when a bot is added or removed to a space, use bot.addedToSpace() and bot.removedFromSpace() methods.
`typescript`
bot.addedToSpace(async ctx => {
ctx.newMessageInSpace({
text: 'Here are a few things you can try...'
});
});
Note that when a bot is first added to a space via an @mention, Chat only sends a single event. If an ADDED_TO_SPACE
event contains a message, this framework internally dispatches the event twice; once for any addedToSpace listeners,messages
then a second synthetic event for any listeners that match the user content.
The Context instance supplied to handlers includes several methods for replying to events:
* reply - Replies directly to the user's message with a new messageupdateMessage
* - For actions on interactive cards and link unfurls, updates the previous message wherenewMessageInThread
the action occurred.
* - Similar to reply, but for sending additional messages on the thread.newMessageInSpace
* - Starts a new thread in the spaceshowDialog
* - Shows a dialog, either in respond to a slash command or dialog actioncloseDialog
* - Closes the current dialog when called from an action handler.
These helpers automatically merges the space and thread names into the message. You only need to supply
the message content itself.
The bot.sendMessage()` event can be used to send an unsolicited message to a space, such as when
notifying the user about an external event. This method is a wrapper around the chat
API and is bound to the bot's configured identity.