In order for users to talk to your bot, the messages have to be sent to and received from the bot application. In traditional chat environments, the sending and receiving is done by an external chat service - like Slack, Facebook Messenger, or in the good ol' days, an IRC server.
Botkit now includes a built-in chat server, so that messages can be sent and received directly to the bot application without relying on a third-party. The server can be used in two ways: with real-time websocket connections, or with traditional http webhooks.
The best way to connect to your bot is using websockets, which enables real-time two-way delivery of messages. Websocket connections remain open, which allows the bot to send multiple messages in sequence, or take longer than usual to process a request before sending a response.
The bundled web chat client is configured to use websockets by default, and handles all of the complexity of managing the connection, including gracefully handling disconnects and reconnects that may occur. See connection events below.
The websocket server accepts connections at the root URL of your Botkit application. If your application is served over SSL, the url will be wss://<my_bot_url>. Otherwise, use the unencrypted url at ws://<my_bot_url>
If using websockets does not work for your application, Botkit can also receive messages via webhooks.
When using the webhooks to communicate with Botkit, several limitations apply:
- The bot MUST respond to every incoming request with some sort of reply
- The bot can only send a SINGLE reply to any incoming message
- Your bot cannot spontaneously message the user without first receiving a message (or other event trigger)
Messages can be sent to Botkit by sending a POST to /botkit/receive with a message object as the body of the request.
POST /botkit/receive
{
"text": "Message Text",
"user": "unique user id",
"channel": "webhook"
}
The response to this request will be a message object representing the reply from the bot. The reply will be in the same format as the incoming message, with a text, user, and channel field, along with any additional attachments or custom fields sent by the bot.
When first establishing a connection, the client will send a connect event - either a hello event, or a welcome_back event. These events tell the bot that a user has connected and is ready to chat.
hello events occur when a brand new user opens their first chat session.
welcome_back events occur when a known user returns to the chat.
In addition, the bot may fire a reconnect event. These occur when an ongoing chat is disrupted by a disconnect/reconnect, and may indicate that some messages may not have been delivered.
These events can be handled with skill modules to do things like send greetings or trigger analytics events.
Botkit Anywhere comes bundled with a message history feature which will capture and track all messages sent during a user's communication with the bot. This log of messages is available via an API call which is used by the built-in client to display previously sent messages when a user reconnects.
This is particularly useful when the bot is embedded in a site, as each time a user navigates to a new page, the chat widget will have to establish a brand new connection and repopulate the interface.
By default, the message history feature is disabled. Before you enable this plugin, you must first implement an identity verification mechanism for your users. As implemented, calls to this API are not authenticated, which would allow potentially sensitive information contained in message history to be exposed. This module should be considered a proof of concept reference design only, and is not production ready!
To enable this module, you'll need to uncomment the code, implement additional security measures, and specify a MongoDB connect string in your applications environment as MONGO_URI. Once set, your Botkit will automatically capture and store messages, as well as serve them up to the web chat client.