Skip to content
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
764 lines (419 sloc) 39.6 KB

Change Log

View the official Botkit roadmap for upcoming changes and features.

Want to contribute? Read our guide!




Update dependency on request to latest to fix security warnings in dependency tree.


Update dependency on botbuilder to 3.16 to fix security warnings in dependency tree.


This release is the first major step towards deprecating Botkit Studio, and introducing a more general system for scripted dialogs and content from Botkit CMS.

We urge all Botkit users to update to the most recent version of Botkit. This may require an update to your project's package.json file.

  • Remove all functionality pertaining to Botkit Studio statistics and analytics APIs. All stats related services provided by Botkit Studio will cease operation on Dec 15.
  • Remove stats_optout flag from configuration.
  • Remove Botkit Studio options from command line interface.
  • Calls to Botkit Studio and/or Botkit CMS will no longer include the user's id

New features and changes:


  • Add support for Slack's chat.getPermalink


  • Fix bug introduced in 0.6.19 that caused events to improperly fire twice.
  • Emit a warning if Slack webhook validation is not enabled.
  • To prepare for upcoming changes to Botkit Studio and Botkit stats collection:
    • Prevent bots without Botkit Studio credentials from sending stat events
    • Emit a message about stats data collection at startup


No new features, but updates throughout the dependency tree for security and stability purposes.

  • Updated dependency versions to latest available

  • Rewrote Botkit command line tool to remove dependency on abandoned library. Upgrade to the latest: npm install -g botkit

  • Switched from using jscs to eslint for linting purposes.


  • Fix syntax error in Web connector. Oops! Thanks for reporting this issue @iworkforthem!

  • Add support for Google Hangouts "card_clicked" event. Thanks to @ouadie-lahdioui


In addition to minor fixes, dependency version updates, and documentation updates, this version includes:

  • Google Hangouts support is here! Thanks to @ouadie-lahdioui's hard work, your bot can now operate in Hangouts Chat.

    Get started with the Botkit Starter Kit for Google Hangouts.

    Botkit docs for Google Hangouts connector

  • CiscoSpark bots are now officially WebexBots. Everything is backwards compatible thanks to the hard work of @ObjectIsAdvantag, but you should move to using Botkit.webexbot() instead of Botkit.sparkbot() ASAP.

    Botkit docs for Cisco Webex Teams

    Read more about these changes.

  • Tests have been reorganized and updated thanks to @fastbean-au.

  • Errors that occur in the middleware pipeline will now cause pipeline_error event to be emitted. In addition, errors at specific stages of the pipeline will also emit their own events: ingest_error, normalize_error, categorize_error and receive_error. This should make it easier to debug problems in middleware. Thanks to @Nop0x. Docs

    Handle a pipeline error:

    controller.on('pipeline_error', function(err, bot, message, stage_name) {
        // ... handle it!

    Handle a specific stage error:

    controller.on('ingest_error', function(err, bot, message) {
        // ... handle it!


  • Fixed issue in Cisco adapter introduced in 0.6.15


Some minor tweaks:

  • Update to the way Webex Teams bots identify themselves PR #1397 Thank you to @jpjpjp

  • Externalize the utterances object #1085 thanks to @hannanabdul55

  • For Botkit web adapter, add typingDelayFactor config option, as well as controller.setTypingDelayFactor() to change how fast the bot types. Values between 0-1 will speed up the bot's typing, values above 1 will slow it down. - Docs - PR #1387 Thanks to @schmitzl

Several updates to the TypeScript definitions:

  • Add collectResponse to CoreBot's public types #1358 thanks to @pducks32
  • Add missing methods to d.ts #1359 thanks to @ypresto
  • Updating typings for interactive messages #1318 thanks to @jaalger

Thanks to frequent contributor @ouadie-lahdioui for the updates to Facebook Messenger:

Support for Slack's new security feature:

  • Request Signing with Slack Signing Secret - Docs - #1406 thanks to @shishirsharma


  • Fix for require_delivery option in Facebook bots. PR #1312

  • Errors encountered during Slack RTM connection process will now be reprorted to the callback function PR #1335

  • Updated methodology used to validate email addresses when restricting access to Cisco Spark bots

  • Updated dependencies to latest stable versions


  • Fix bugs and refactor handling of message actions, particularly as they relate to Botkit Studio scripts

  • Adjust mechanism used to construct facebook quick reply payload in order to support future formats. PR #1301

  • Promisify Facebook Messenger profile API. PR #1300

  • Lower the log priority from 'log' to 'debug' for several messages in Botkit Core and Botkit Slack.


  • Botkit has a brand new docs site! We have begun transitioning the documentation out of this repo into a dedicated documentation repo.

  • Remove dependency on Python introduced in 0.6.10. Thanks to @qiongfangzhang for the attention on that!

  • Fix for Facebook Messenger send broadcast function. PR #1280 Thanks @OmranAbazid

  • Extend Facebook's user profile object with locale. PR #1265 Thanks @julianusti

  • Added 'picture' to Facebook User Profile endpoint. PR #1264 Thanks @se

  • Add FB request thread control PR #1257 Thanks as always to @ouadie-lahdioui

  • Remove requirement that Cisco Spark endpoint be SSL. PR #1284 thanks @akalsey and your beard.

  • Add support for Slack's users.lookupByEmail API. PR #1285 Thanks to @piglovesyou

  • Fix to the way variables are copied between conversations while using Botkit Studio scripts


  • For Botkit Studio users, added for loading scripts by their unique ID rather than by name or trigger. Docs here


  • Add support for Cisco Jabber. Thanks to @qiongfangzhang and @panx981389 and their team at Cisco for the contribution!

Documentation for the Cisco Jabber adapter can be found here

  • Updated ciscospark dependency to latest version and fixed some bugs in the example bot

  • Update Twilio dependency to latest, along with small updates to adapter. Thanks @nishant-chaturvedi! PR #1140


  • Add 2 new middleware endpoints that occur during conversations - conversationStart(bot, convo, next) and conversationEnd(bot, convo, next). Some new documentation
  • Conversations powered by Botkit Studio will now include convo.context.script_name and convo.context.script_id which point back to the script loaded from the Botkit Studio API
  • When using Botkit Studio's execute script action, the resulting conversation object will have 2 additional context fields: convo.context.transition_from and convo.context.transition_from_id which will point to the script from which the user transitioned
  • When using Botkit Studio's execute script action, the original conversation from which the user is transitioning will have 2 additional context fields: convo.context.transition_to and convo.context.transition_to_id which will point to the script to which the user transitioned
  • Fix for Botkit Studio scripts which used "end and mark successful" action from a condition. Previously this would end, but not mark successful.

Merged Pull Requests:

  • Make sure Facebook API errors are passed to callback if specified PR #1225
  • Refresh Microsoft Teams token when it has expired. PR #1230
  • Update TypeScript definition for Web bots PR #1231
  • Update TypeScript definition for bot.replyAndUpdate PR #1232
  • Fix for Microsoft teams button builder function PR #1233



Botkit now works on the web! The new web connector supports websocket and webhook connections for sending and receiving messages. The brand new Botkit Anywhere starter kit includes a customizable web chat client, and a built-in chat server. Of course, this works with the existing stack of Botkit tools and plugins!

New for Botkit Studio:

Developers using Botkit Studio to create and manage script content can now utilize a new message action in their conditional statements, or at the end of any thread. It is now possible to direct your bot to seamlessly transition to a different Botkit Studio script. This allows for new patterns like interconnected menus, loops and branching conversations.

New core features:

Developers can now exclude specific types of events from being included in conversations using controller.excludeFromConversations(event_name). This has been applied to the Facebook connector, which will now exclude certain events automatically. Docs

The tick interval used for driving conversations can now be adjusted using controller.setTickDelay(ms). Docs

Merged pull requests:

Our community of Botkit Core developers is more than 150 people strong! Thank you to all of the contributors who spent their precious time improving Botkit for everyone. There are more than a dozen pull requests included in this release!!



This release contains a ton of updates to the Facebook connector, many of which were contributed by @ouadie-lahdioui!

Botkit will now exclude message_delivered, message_echo and message_read events from inclusion in conversations using the new excludeFromConversations() function. Docs


These fixes for the Slack connector add more ways to protect your bot from potentially malicious incoming webhook events. Use them!!


Add to load all a list of available scripts from Botkit Studio Docs

Add handling (and error messages) for 401 response codes from Botkit Studio APIs that indicate a bad access token


Important fixes to Facebook and Cisco Spark connectors: A breaking change was introduced in 0.6.5 which has now been fixed.

Remove crypto dependency, now use built-in crypto library.

Update botkit-studio-sdk dependency to latest version.


Introducing the Botkit command line tool!

Run: npm install -g botkit

Then, you'll be able to set up a new Botkit project (based on one of our excellent starter kits!) by typing:

botkit new --name "my bot"

New helper functions:

Botkit bots for Slack, Cisco Spark, Microsoft Teams and Facebook now have support for additional helper functions:

bot.getMessageUser(message) returns a Promise that will receive a normalized user profile object for the user who sent the message.

bot.getInstanceInfo() returns a Promise that will receive a normalized instance object, with identity and team fields.


Fix for Cisco Spark: improved methodology for detecting and handling @mentions

Fix for Slack: allow multiple validation errors to be passed in to bot.dialogError(). Thanks @cfs! PR #1080

Fix for Slack: fix for bot.whisper() Thanks to @jonchurch and @fletchrichman!

New: Botkit Studio scripts may now contain custom fields in message objects. This is in support of an upcoming feature in Botkit Studio which will allow developers to add define these custom fields in the Studio IDE.


New: Support for Slack Dialogs, including:

  • bot.createDialog() function Docs
  • bot.replyWithDialog() function Docs
  • function
  • dialog_submission event Docs
  • bot.dialogOk() function Docs
  • bot.dialogError() function Docs

Fix: Cisco Spark bots will once again receive direct_message and direct_mention events. (Fix for #1059)


Fix bug in Facebook connector: call startTicking() as part of object instantiation. This was missing in 0.6 and 0.6.1

Move call to startTicking() in TwilioIPM connector to make it consistent with other connectors.

Fix: Catch 202 response code that does not have a JSON response body. This status sometimes comes back from the MS Teams API when a message has been queued for delivery.


Fix bugs in Botframework and ConsoleBot connectors that caused messages not to send. Resolves #1033.

Fix typo in Twilio connector that caused attached media to fail. Thanks @jpowers! PR #1023

Fix missing bodyParser module in Facebook connector. Resolves #1041.

New: Add support for the new conversations APIs for Slack. Read about this new API here.

New: Add usergroups APIs for Slack. Thanks to @digitalspecialists for this! PR #1001

Change: Facebook message_echo webhooks will now emit message_echo events instead of message_received events to distinguish them from messages sent by users.


This version features some BIG CHANGES!

New platform support:

Microsoft Teams is now officially supported with its own connector, including new features in Botkit Studio like authoring of Teams-specific attachments, an app package builder and configuration manager, and a new starter kit.

Read the full docs for Botkit for Microsoft Teams

Major changes to message handling code:

Introducing the Botkit Message Pipeline, a formalized process for Botkit's handling of incoming and outgoing messages. All of the platform connectors have been refactored to use this new series of middleware functions, and are now implemented in a uniform way.

Developers who make use of Botkit's middleware system should take time to read this update. Most current middleware functions will continue to work as expected, but mild changes may be desirable to update these functions to use Botkit's latest features.

In addition, developers who use third party middleware plugins should carefully retest their applications after upgrading to version 0.6, as these plugins may need to be updated for full compatibility.

Upgrade Guide:

This version of Botkit deprecates the receive_via_postback and interactive_replies options that caused button clicks to be treated as typed messages. These and other small changes to the way Botkit emits events may require minor updates to some Botkit apps.

Upgrading from Botkit 0.5 or lower? Read this guide!


Slack: Support for sending ephemeral messages with bot.whisper() and bot.sendEphemeral(). In addition, any message with message.ephemeral set to true will be sent with bot.sendEphemeral() automatically. Read documentation here. Thanks to @jonchurch

Slack: Add support for bot.api.files.sharedPublicURL() method. Thanks to @GitTristan

Facebook: Support for using message tags. Read documentation here. Thanks to @ouadie-lahdioui

Facebook: Support for using Facebook's new built-in NLP tools. Read documentation here. Thanks to @ouadie-lahdioui for this one too!!

Twilio SMS: Add support for sending MMS messages (file attachments) via Twilio. Read documentation here. Thanks to @krismuniz!

Cisco Spark: Emit a console warning when a bot receives messages from outside the allowed domain list. Thanks to @MathRobin!

New: Typescript declarations! Thanks to @uny and @naktibalda for their work on this.


Lock in ciscospark dependency at version 1.8.0 until further notice due to breaking changes in more recent versions.


Fix for Botkit Studio-powered bots: Facebook attachments can now be added without buttons

Fix for Cisco Spark: Bot mentions will now reliably be pruned from message, regardless of what client originated the message

Fix for Cisco Spark: startPrivateConversationWithPersonID has been fixed.


Introducing Botkit for SMS! Botkit bots can now send and receive messages using Twilio's Programmable SMS API! Huge thanks to @krismuniz who spearheaded this effort! Read all about Twilio SMS here

New unit tests have been added, thanks to the ongoing efforts of @colestrode, @amplicity and others. This release includes coverage of the Botkit core library and the Slack API library. This is an ongoing effort, and we encourage interested developers to get involved!

Add missing error callback to catch Slack condition where incoming messages do not match a team in the database. PR #887 thanks to @alecl!

Add support for Facebook attachment upload api PR #899 thanks @ouadie-lahdioui! Read docs about this feature here

Fixed issue with Slack message menus. PR #769

Fixed confusing parameter in JSON storage system. delete() methods now expect object id as first parameter. PR #854 thanks to @mehamasum!

All example bot scripts have been moved into the examples/ folder. Thanks @colestrode!

Fixes an instance where Botkit was not automatically responding to incoming webhooks from Cisco with a 200 status. PR #843

Updated dependencies to latest: twilio, ciscospark, https-proxy-agent, promise


Fix for #806 - new version of websocket didn't play nice with Slack's message servers

Support for Slack's new rtm.connect method.

Use rtm.connect instead of rtm.start when connecting an RTM bot to Slack. This should performance during connections.


Add a new readme file and moved other documentation into docs/ folder.

Update all dependencies to their most recent versions

Change behavior of conversation timeouts. New behavior is documented here.

Support for Facebook Messenger's new "Home URL" setting PR #793 New features documented here.

Support for including parameters in Facebook codes. PR #790 Docs here.

Support for Facebook's new "target audience" APIs PR #798

Support for additional Slack user APIs, including 'user.profile.set' and 'user.profile.get'. PR #780

Add support for createPrivateConversation() in Slack bots PR #586

beforeThread Hooks:

These new hooks allow developers to execute custom functionality as a conversation transitions from one thread to another. This enables asynchronous operations like database and API calls to be made mid-conversation, and can be used to add additional template variables (using convo.setVar()), or change the direction of the conversation (using convo.gotoThread()).

Add convo.beforeThread(), a plugin hook that fires before a conversation thread begins. Docs

Add, a plugin hook that fires before a Botkit Studio-powered conversation thread begins. Docs


Changes for Slack:

Add support for Slack's new chat.unfurl method for use with App Unfurls

Add additional Slack's team API methods PR #677

Botkit will now store the value of the state parameter used in the oauth flow in the team's record PR #657

Fixes slash commands when using internal webserver PR #699

Add error logging for say and PR #691

Changes for Facebook Messenger:

Updates to Facebook's Messenger Profile APIs (previously thread settings APIs) PR #690

Add ability to retrieve Messenger Code image PR #689

Add support for Facebook's domain whitelisting API PR #573

Add tests for handleWebhookPayload in Facebook bot flow PR #678

Add Facebook account linking support PR #578

Add ability to customize api url for Facebook PR #576

Changes to Botkit Core:

Add "done" and "exit" as a utterances for "quit" PR #498


Thanks to @jhsu @davidwneary @mbensch @alecl @ouadie-lahdioui @agamrafaeli @katsgeorgeek @jfairley


Fixes for Cisco Spark:

Allow port number to be included in public_address

Fix to issue when using retrieveFile()

Fixes for Slack:

Add support for channel.replies API

Fixes for Facebook:

Add support for Facebook account linking


Add support for bots on Cisco Spark! For information about getting started, and to learn about new Botkit features that are specific to this platform, check out our new Cisco Spark readme.

Botkit will now send a user agent header on all requests to the Slack API

When building for Slack, developers may now override the root URL of the API by specifying api_root in the configuration in order to use mocked testing endpoints or use the Slack API through a proxy.


Add support for Slack Enterprise Grid, for more information read

Add Support for Slack's new thread system, including:

bot.replyInThread() to create a threaded reply

bot.startConversationInThread() to create and immediately start a conversation in a thread

bot.createConversationInThread() to create a conversation in a thread

Add new heard middleware endpoint, which fires after a pattern has been matched, but before the handler function is called. This allows developers to enrich messages with NLP tools or other plugins, but do so only when the original message matches specific criteria.

Add new capture middleware endpoint, which fires after a user responds to a convo.ask question but before the related handler function is called. This allows developers to change the value that is captured, or capture additional values such as entities returned by an NLP plugin.


controller.version() will now report the currently installed version of Botkit.

Change to how quick replies are rendered via Botkit Studio's API


Add support for Facebook Messenger "location" quick replies PR #568

Add support for Slack's new users.setPresence API PR #562

Add support for Slack's new reminders API PR #580


Change to Will now resolve promise regardless of whether a trigger was matched


Bug fix: Fix detection of Slackbot interactive callbacks



Add referral field to facebook_postback events, if set PR #552

Refactor handling of incoming webhooks from Slack and Facebook in order to make it easier for developers to create custom endpoints and/or integrate Botkit into existing Express applications.

Add controller.handleWebhookPayload() to process a raw webhook payload and ingest it into Botkit

Make stale connection detection configurable PR #505

DDOS Vulnerability Fix - Secure Facebook Webhook PR #555

Bug fixes:

Fix an issue where a custom redirect_uri would be rejected by Slack's oauth verification

Fix bot_channel_join and bot_group_join with Slack Events API PR #514

Fix path to static content directory PR #546

retry and send_via_rtm options are now properly associated with the controller object.

Fix some issues pertaining to typing indicators and the slack RTM PR #533


Adds convo.transitionTo(), a new feature for creating smoother transitions between conversation threads

Adds support for new Facebook Messenger thread settings APIs which enable developers to set and manage the 'getting started' screen and persistent menus.

Adds support for Facebook Messenger attachment in Botkit Studio

Adds a check to ensure messages are properly received by Facebook and Slack before proceeding to next message in a conversation.

Adds optional require_delivery option for Facebook and Slack bots which tells Botkit to wait to receive a delivery confirmation from the platform before sending further messages. Slack info Facebook info

Change: Receiving facebook_postback events as normal "spoken" messages now requires the {receive_via_postback:true} option be set on the controller. Read more


Support for Slack's Events API is here, thanks to the Botkit contributor community. Read documentation here

Bug fix:

Fixes an issue with setting the default IP address for the Express server introduced in 0.4.1


This release contains many small fixes and updates to keep up with the ever changing platforms!


Slack bots will now send messages via the Web API instead of the RTM. This behavior can be changed by passing send_via_rtm: true to controller.spawn()

Adds ConsoleBot for creating bots that work on the command line

Adds a new Middleware Readme for documenting the existing middleware modules

Adds an example for using quick replies in the Facebook Example Bot

Adds additional fields to Facebook messages to specify if they are facebook_postbacks or normal messages.

Adds optional hostname field to constructor functions to bind Express to a specific IP.

Fixes for Slack's files.upload API

Merge in numerous pull requests from the community: PR #461 PR #465 PR #466 PR #469 PR #472 PR #474 PR #434 PR #435 PR #440 PR #441 PR #443 PR #446 PR #448


Add support for Botkit Studio APIs. More Info

Substantially expanded the documentation regarding Botkit's conversation thread system.

Add support for Microsoft Bot Framework. The Microsoft Bot Framework makes it easy to create a single bot that can run across a variety of messaging channels including Skype,, Facebook Messenger, Slack, Telegram, Kik, SMS, and email. More Info

Updates to Facebook Messenger connector to support features like message echoes, read receipts, and quick replies.

Merged numerous pull requests from the community: PR #358 PR #361 PR #353 PR #363 PR #320 PR #319 PR #317 PR #299 PR #298 PR #293 PR #256 PR #403 PR #392

In order to learn about and better serve our user community, Botkit now sends anonymous usage stats to To learn about opting out of stats collection, read here.


Add support for Slack Interactive Messages.

Add example of Slack button application that provides a bot that uses interactive messages.

New functionality in Slack bot: Botkit will track spawned Slack bots and route incoming webhooks to pre-existing RTM bots. This enables RTM bots to reply to interactive messages and slash commands.


Improves Slack RTM reconnects thanks to @selfcontained PR #274


Adds support for Twilio IP Messenging bots

Add example bot: twilio_ipm_bot.js


Slack changes:

Adds authentication of incoming Slack webhooks if token specified. More info [Thanks to @sgud]

Improves support for direct_mentions of bots in Slack (Merged PR #189)

Make the oauth identity available to the user of the OAuth endpoint via req.identity (Merged PR #174)

Fix issue where single team apps had a hard time receiving slash command events without funky workaround. (closes Issue #108)

Add team_slashcommand.js and team_outgoingwebhook.js to the examples folder.

Facebook changes:

The attachment field may now be used by Facebook bots within a conversation for both convo.say and convo.ask. In addition, postback messages can now be received as the answer to a convo.ask in addition to triggering their own facebook_postback event. [Thanks to @crummy and @tkornblit]

Include attachments field in incoming Facebook messages (Merged PR #231)

Adds built-in support for opening a tunnel to expose Facebook webhook endpoint while developing locally. (Merged PR #234)


Fix issue with over-zealous try/catch in Slack_web_api.js


Adds support for Facebook Messenger bots.

Rename example bot: bot.js became slack_bot.js

Add example bot: facebook_bot.js


Changes conversation.ask to use the same pattern matching function as is used in hears()

Adds controller.changeEars() Developers can now globally change the way Botkit matches patterns.


Add new middleware hooks. Developers can now change affect a message as it is received or sent, and can also change the way Botkit matches patterns in the hears() handler.


Next time I promise to start a change log at v0.0.0

You can’t perform that action at this time.