exploration with the keybase chat API
Keybase bot-scripting for Node.js - now written all in TypeScript! Send encrypted data all over this world.
You can use this module to script basic Keybase commands such as sending and reading messages and attachments, and managing teams.
keybase-bot.
bash npm install keybase-bot # or yarn add keybase-bot
You're ready to make your first Keybase bot.
If your bot is going to do things in the background for an extended period, we recommend starting it up with a username and paper key:
// A simple nodeJS bot that doesn't care who else is logged in on this machine const Bot = require('keybase-bot') async function main() { const bot = new Bot() await bot.init('usernameX', 'some paper key...') /* now you can do things with the bot */ await bot.deinit() // when done } main()
This method means it's running as itself and won't care about Keybase generally running on your computer. It doesn't care if you're logged into Keybase in the GUI app on the same machine. It also doesn't care if you upgrade Keybase while it's running, since it won't restart its copy of Keybase during an update.
If, however, you'd like the bot just to act as you for a quick and easy operation, you can make your bot talk to the same service that the Keybase app is talking to. It will be logged in as whoever's logged into the Keybase app:
const Bot = require('keybase-bot') async function main() { const bot = new Bot() // Make sure you're logged into the Keybase app first! // No credentials neeeded: await bot.initFromRunningService() /* now you can do things with the bot */ await bot.deinit() // when done } main()
Let's make a bot that says hello to the Keybase user kbot.
const Bot = require('keybase-bot')async function main() { const bot = new Bot() try { const username = 'some_username' // put a real username here const paperkey = 'foo bar car zar...' // put a real paperkey here await bot.init(username, paperkey, {verbose: false}) console.log(
Your bot is initialized. It is logged in as ${bot.myInfo().username}
) const channel = {name: 'kbot'} const message = { body:Hello kbot! This is ${bot.myInfo().username} saying hello from my device ${bot.myInfo().devicename}
, } await bot.chat.send(channel, message) console.log('Message sent!') } catch (error) { console.error(error) } finally { await bot.deinit() } }main()
To run the above bot, you want to save that code into a file and run it with node:
node .js
You can read it from a secret config file, or pass it as an environment variable - whatever you think is best. For example, you could change the above initialization code to:
const username = process.env.KB_USERNAME const paperkey = process.env.KB_PAPERKEY await bot.init(username, paperkey)
And run your program like so:
KB_USERNAME=foo KB_PAPERKEY="foo bar car" node my-awesome-program.js
If you'd like to write a bot that listens to your messages (or your team's) and does something, check out
demos/es7/advertised-echo.js.
That demo bot announces itself as handling
!echo, which means it gives autocomplete suggestions in the GUI when you talk to it.
index.js:
#!/usr/bin/env node const Bot = require('keybase-bot')async function main() { const bot = new Bot() try { const username = process.env.KB_USERNAME const paperkey = process.env.KB_PAPERKEY const target = process.env.KB_TARGET await bot.init(username, paperkey, {verbose: false}) console.log(
Your bot is initialized. It is logged in as ${bot.myInfo().username}
) const channel = {name: target + ',' + bot.myInfo().username, public: false, topicType: 'chat'} const message = { body:Hello ${target}! This is ${bot.myInfo().username} saying hello from my device ${bot.myInfo().devicename}
, } await bot.chat.send(channel, message) console.log('Message sent!') } catch (error) { console.error(error) } finally { await bot.deinit() } } main()
package.json:
{ "name": "keybase-demo", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "author": "", "license": "ISC", "dependencies": { "keybase-bot": "^3.0.2" } }
Dockerfile:
FROM keybaseio/client:nightly-node RUN mkdir /app && chown keybase:keybase /app WORKDIR /app COPY package*.json ./ RUN npm install # or use yarn COPY . . CMD node /app/index.js
cd $PROJECT_DIR docker build -t "keybase-docker-test" .
docker run \ --rm \ -e KB_USERNAME="yourbotname" \ -e KB_PAPERKEY="your_paper_key" \ -e KB_TARGET="yourusername" \ keybase-docker-test
All the source of this library is now written in TypeScript. If you're working on the library, please use
yarnto install the necessary modules, and then run
yarn buildto build the JavaScript library files. Finally, make a test config file in
__tests__/(look at
__tests__/test.config.tsas an example) and run
yarn test. If everything passes, you haven't broken everything horribly.
A Keybase bot.
Initialize your bot by starting an instance of the Keybase service and logging in using oneshot mode.
usernamestring The username of your bot's Keybase account.
paperkeystring The paperkey of your bot's Keybase account.
optionsInitOptions? The initialization options for your bot.
bot.init('username', 'paperkey')
Returns Promise<void>
Initialize your bot by using an existing running service with a logged in user.
homeDirstring? The home directory of this currently running service. Leave blank to use the default homeDir for your system.
optionsInitOptions? The initialization options for your bot.
bot.initFromRunningService()
Returns Promise<void>
Get info about your bot!
const info = bot.myInfo()
Returns (BotInfo | null) – Useful information like the username, device, and home directory of your bot. If your bot isn't initialized, you'll get
null.
Deinitializes the bot by logging out, stopping the keybase service, and removing any leftover login files made by the bot. This should be run before your bot ends.
bot.deinit()
Returns Promise<void>
If bot is initialized with an optional directory
adminDebugDirectory, this will let you write info text into it.
textstring
bot.adminDebugLogInfo('My bot is ready to go.')
Returns Promise<void>
If bot is initialized with an optional directory
adminDebugDirectory, this will let you write error text into it.
textstring
bot.adminDebugLogInfo('My bot is ready to go.')
Returns Promise<void>
A collection of types used by the bot.
src/chat-client/index.ts:111-637
Extends ClientBase
The chat module of your Keybase bot. For more info about the API this module uses, you may want to check out
keybase chat api.
src/chat-client/index.ts:198-210
Joins a team conversation.
channelchat1.ChatChannel The team chat channel to join.
bot.chat.listConvsOnName('team_name').then(async teamConversations => { for (const conversation of teamConversations) { if (conversation.memberStatus !== 'active') { await bot.chat.join(conversation.channel) console.log('Joined team channel', conversation.channel) } } })
Returns Promise<void>
src/chat-client/index.ts:225-237
Leaves a team conversation.
channelchat1.ChatChannel The team chat channel to leave.
bot.chat.listConvsOnName('team_name').then(async teamConversations => { for (const conversation of teamConversations) { if (conversation.memberStatus === 'active') { await bot.chat.leave(conversation.channel) console.log('Left team channel', conversation.channel) } } })
Returns Promise<void>
src/chat-client/index.ts:386-393
Gets current unfurling settings
bot.chat.getUnfurlSettings().then(mode => console.log(mode))
Returns Promise<chat1.UnfurlSettings>
src/chat-client/index.ts:407-413
Sets the unfurling mode In Keybase, unfurling means generating previews for links that you're sending in chat messages. If the mode is set to always or the domain in the URL is present on the whitelist, the Keybase service will automatically send a preview to the message recipient in a background chat channel.
modechat1.UnfurlSettings the new unfurl mode
bot.chat .setUnfurlMode({ mode: 'always', }) .then(mode => console.log('mode updated!'))
Returns Promise<void>
src/chat-client/index.ts:424-441
Loads a flip's details
conversationIDstring conversation ID received in API listen.
flipConversationIDstring flipConvID from the message summary.
messageIDnumber ID of the message in the conversation.
gameIDstring gameID from the flip message contents.
// check demos/es7/poker-hands.js
Returns Promise<chat1.UICoinFlipStatus>
src/chat-client/index.ts:462-468
Publishes a commands advertisement which is shown in the "!" chat autocomplete.
advertisementAdvertisement details of the advertisement
await bot.chat.advertiseCommands({ advertisements: [ { type: 'public', commands: [ { name: '!echo', description: 'Sends out your message to the current channel.', usage: '[your text]', }, ], }, ], })
Returns Promise<void>
src/chat-client/index.ts:476-482
Clears all published commands advertisements.
advertisementadvertisement parameters
await bot.chat.clearCommands()
Returns Promise<void>
src/chat-client/index.ts:504-511
Lists all commands advertised in a channel.
lookupAdvertisementsLookup either conversation id or channel
const commandsList = await bot.chat.listCommands({ channel: channel, }) console.log(commandsList) // prints out something like: // { // commands: [ // { // name: '!helloworld', // description: 'sample description', // usage: '[command arguments]', // username: 'userwhopublished', // } // ] // }
Returns Promise<{commands: Array<chat1.UserBotCommandOutput>}>
src/chat-client/index.ts:121-128
Lists your chats, with info on which ones have unread messages.
optionsChatListOptions? An object of options that can be passed to the method.
const chatConversations = await bot.chat.list({unreadOnly: true}) console.log(chatConversations)
Returns Promise<Array<chat1.ConvSummary>> An array of chat conversations. If there are no conversations, the array is empty.
src/chat-client/index.ts:139-155
Lists conversation channels in a team
namestring Name of the team
optionsChatListChannelsOptions? An object of options that can be passed to the method.
bot.chat.listChannels('team_name').then(chatConversations => console.log(chatConversations))
Returns Promise<Array<chat1.ConvSummary>> An array of chat conversations. If there are no conversations, the array is empty.
src/chat-client/index.ts:166-183
Reads the messages in a conversation. You can read with or without marking as read.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
optionsChatReadOptions? An object of options that can be passed to the method.
alice.chat.read(channel).then(messages => console.log(messages))
Returns Promise<ReadResult> A summary of data about a message, including who send it, when, the content of the message, etc. If there are no messages in your channel, then an error is thrown.
src/chat-client/index.ts:250-268
Send a message to a certain conversation.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
messagechat1.ChatMessage The chat message to send.
optionsChatSendOptions? An object of options that can be passed to the method.
const channel = {name: 'kbot,' + bot.myInfo().username, public: false, topicType: 'chat'} const message = {body: 'Hello kbot!'} bot.chat.send(channel, message).then(() => console.log('message sent!'))
const onMessage = async message => { bot.chat.send(message.conversationId, { body: 'hello!', }) } await bot.chat.watchAllChannelsForNewMessages(onMessage, onError)
Returns Promise<chat1.SendRes>
src/chat-client/index.ts:277-290
Creates a new blank conversation.
channelchat1.ChatChannel The chat channel to create.
bot.chat.createChannel(channel).then(() => console.log('conversation created'))
Returns Promise<void>
src/chat-client/index.ts:301-309
Send a file to a conversation.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
filenamestring The absolute path of the file to send.
optionsChatAttachOptions? An object of options that can be passed to the method.
bot.chat.attach(channel, '/Users/nathan/my_picture.png').then(() => console.log('Sent a picture!'))
Returns Promise<chat1.SendRes>
src/chat-client/index.ts:321-328
Download a file send via Keybase chat.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
messageIdnumber The message id of the attached file.
outputstring The absolute path of where the file should be downloaded to.
optionsChatDownloadOptions? An object of options that can be passed to the method
bot.chat.download(channel, 325, '/Users/nathan/Downloads/file.png')
Returns Promise<void>
src/chat-client/index.ts:341-355
Reacts to a given message in a conversation. Messages have messageId's associated with them, which you can learn in
bot.chat.read.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
messageIdnumber The id of the message to react to.
reactionstring The reaction emoji, in colon form.
optionsChatReactOptions? An object of options that can be passed to the method.
bot.chat.react(channel, 314, ':+1:').then(() => console.log('Thumbs up!'))
Returns Promise<chat1.SendRes>
src/chat-client/index.ts:368-379
Deletes a message in a conversation. Messages have messageId's associated with them, which you can learn in
bot.chat.read. Known bug: the GUI has a cache, and deleting from the CLI may not become apparent immediately.
channelOrConversationIdchat1.ChatChannel or chat1.ConvIDStr The chat conversation to send the message in.
messageIdnumber The id of the message to delete.
optionsChatDeleteOptions? An object of options that can be passed to the method.
bot.chat.delete(channel, 314).then(() => console.log('message deleted!'))
Returns Promise<void>
src/chat-client/index.ts:530-538
Listens for new chat messages on a specified channel. The
onMessagefunction is called for every message your bot receives. This is pretty similar to
watchAllChannelsForNewMessages, except it specifically checks one channel. Note that it receives messages your own bot posts, but from other devices. You can filter out your own messages by looking at a message's sender object. Hides exploding messages by default.
channelchat1.ChatChannel The chat channel to watch.
onMessageOnMessage A callback that is triggered on every message your bot receives.
onErrorOnError? A callback that is triggered on any error that occurs while the method is executing.
optionsListenOptions? Options for the listen method.
// Reply to all messages between you and `kbot` with 'thanks!' const channel = {name: 'kbot,' + bot.myInfo().username, public: false, topicType: 'chat'} const onMessage = message => { const conversationId = message.conversationId bot.chat.send(conversationId, {body: 'thanks!!!'}) } bot.chat.watchChannelForNewMessages(channel, onMessage)
Returns Promise<void>
src/chat-client/index.ts:561-564
This function will put your bot into full-read mode, where it reads everything it can and every new message it finds it will pass to you, so you can do what you want with it. For example, if you want to write a Keybase bot that talks shit at anyone who dares approach it, this is the function to use. Note that it receives messages your own bot posts, but from other devices. You can filter out your own messages by looking at a message's sender object. Hides exploding messages by default.
Note that if your bot was added into a channel as a restricted bot, it won't have access to channel names. So you should be using
conversationIdwhen responding in the same conversation.
onMessageOnMessage A callback that is triggered on every message your bot receives.
onErrorOnError? A callback that is triggered on any error that occurs while the method is executing.
optionsListenOptions? Options for the listen method.
// Reply to incoming traffic on all channels with 'thanks!' const onMessage = message => { const conversationId = message.conversationId bot.chat.send(conversationId, {body: 'thanks!!!'}) } bot.chat.watchAllChannelsForNewMessages(onMessage)
Returns Promise<void>
A collection of types used by the Chat module.
src/chat-client/index.ts:54-58
Options for the
attachmethod of the chat module.
src/chat-client/index.ts:63-67
Options for the
downloadmethod of the chat module.
src/chat-client/index.ts:72-74
Options for the
reactmethod of the chat module.
src/chat-client/index.ts:79-81
Options for the
deletemethod of the chat module.
A function to call when a message is received.
Type: function (message: chat1.MsgSummary): (void | Promise<void>)
src/chat-client/index.ts:10-10
A function to call when an error occurs.
Type: function (error: Error): (void | Promise<void>)
src/chat-client/index.ts:90-93
Options for the methods in the chat module that listen for new messages. Local messages are ones sent by your device. Including them in the output is useful for applications such as logging conversations, monitoring own flips and building tools that seamlessly integrate with a running client used by the user.
src/team-client/index.ts:20-69
Extends ClientBase
The team module of your Keybase bot. For more info about the API this module uses, you may want to check out
keybase team api.
src/team-client/index.ts:29-37
Add a bunch of people with different privileges to a team
additionsAddMembersParam an array of the users to add, with privs
bot.team .addMembers({ team: 'phoenix', emails: [ {email: '[email protected]', role: 'writer'}, {email: '[email protected]', role: 'admin'}, ], usernames: [ {username: 'frank', role: 'reader'}, {username: '[email protected]', role: 'writer'}, ], }) .then(res => console.log(res))
Returns Promise<keybase1.TeamAddMemberResult> A result object of adding these members to the team.
src/team-client/index.ts:46-50
Remove someone from a team.
removalRemoveMemberParam object with the
teamname and
username
bot.team.removeMember({team: 'phoenix', username: 'frank'}).then(res => console.log(res))
Returns Promise<void>
src/team-client/index.ts:60-68
List a team's members.
teamListTeamMembershipsParam an object with the
teamname in it.
bot.team.listTeamMemberships({team: 'phoenix'}).then(res => console.log(res))
Returns Promise<keybase1.TeamDetails> Details about the team.
A collection of types used by the Team module.
src/wallet-client/index.ts:5-149
Extends ClientBase
The wallet module of your Keybase bot. For more info about the API this module uses, you may want to check out
keybase wallet api.
src/wallet-client/index.ts:13-20
Provides a list of all accounts owned by the current Keybase user.
bot.wallet.balances().then(accounts => console.log(accounts))
Returns Promise<Array<stellar1.OwnAccountCLILocal>> An array of accounts. If there are no accounts, the array is empty.
src/wallet-client/index.ts:30-42
Provides a list of all transactions in a single account.
accountIdstellar1.AccountID The id of an account owned by a Keybase user.
bot.wallet.history('GDUKZH6Q3U5WQD4PDGZXYLJE3P76BDRDWPSALN4OUFEESI2QL5UZHCK').then(transactions => console.log(transactions))
Returns Promise<Array<stellar1.PaymentCLILocal>> An array of transactions related to the account.
src/wallet-client/index.ts:52-60
Get details about a particular transaction
transactionIdstellar1.TransactionID The id of the transaction you would like details about.
bot.wallet.details('e5334601b9dc2a24e031ffeec2fce37bb6a8b4b51fc711d16dec04d3e64976c4').then(details => console.log(details))
Returns Promise<stellar1.PaymentCLILocal> An object of details about the transaction specified.
src/wallet-client/index.ts:74-87
Lookup the primary Stellar account ID of a Keybase user.
namestring The name of the user you want to lookup. This can be either a Keybase username or a username of another account that is supported by Keybase if it is followed by an '@'.
const lookup1 = bot.wallet.lookup('patrick') // 'patrick' on Keybase is 'patrickxb' on twitter const lookup2 = bot.wallet.lookup('[email protected]') // Using Lodash's `isEqual` since objects with same values aren't equal in JavaScript _.isEqual(lookup1, lookup2) // => true
Returns Promise<{accountId: stellar1.AccountID, username: string}> An object containing the account ID and Keybase username of the found user.
src/wallet-client/index.ts:103-111
Send lumens (XLM) via Keybase with your bot!
recipientstring Who you're sending your money to. This can be a Keybase user, stellar address, or a username of another account that is supported by Keybase if it is followed by an '@'.
amountstring The amount of XLM to send.
currencystring? Adds a currency value to the amount specified. For example, adding 'USD' would send
messagestring? The message for your payment
bot.wallet.send('nathunsmitty', '3.50') // Send 3.50 XLM to Keybase user `nathunsmitty` bot.wallet.send('[email protected]', '3.50') // Send 3.50 XLM to GitHub user `nathunsmitty` bot.wallet.send('nathunsmitty', '3.50', 'USD') // Send $3.50 worth of lumens to Keybase user `nathunsmitty` bot.wallet.send('nathunsmitty', '3.50', 'USD', 'Shut up and take my money!') // Send $3.50 worth of lumens to Keybase user `nathunsmitty` with a memo
Returns Promise<stellar1.PaymentCLILocal> The trasaction object of the transaction.
src/wallet-client/index.ts:124-132
Send lumens (XLM) via Keybase to more than one user at once. As opposed to the normal bot.wallet.send command, this can get multiple transactions into the same 5-second Stellar ledger.
batchIdstring example, if sending a bunch of batches for an airdrop, you could pass them all
airdrop2025.
paymentsArray<stellar1.BatchPaymentArg> an array of objects containing recipients and XLM of the form {"recipient": "someusername", "amount": "1.234", "message", "hi there"}
bot.wallet.batch('airdrop2040', [ {recipient: 'a1', amount: '1.414', message: 'hi a1, yes 1'}, {recipient: 'a2', amount: '3.14159', message: 'hi a2, yes 2'}, ])
Returns Promise<stellar1.BatchResultLocal> an object
src/wallet-client/index.ts:141-148
If you send XLM to a Keybase user who has not established a wallet, you can cancel the payment before the recipient claims it and the XLM will be returned to your account.
transactionIdstellar1.TransactionID The id of the transaction to cancel.
bot.wallet .cancel('e5334601b9dc2a24e031ffeec2fce37bb6a8b4b51fc711d16dec04d3e64976c4') .then(() => console.log('Transaction successfully canceled!'))
Returns Promise<void>
A collection of types used by the Wallet module.
src/chat-client/index.ts:15-20
Options for the
listmethod of the chat module.
src/chat-client/index.ts:25-28
Options for the
listChannelsmethod of the chat module.
src/chat-client/index.ts:33-39
Options for the
readmethod of the chat module.
src/chat-client/index.ts:44-49
Options for the
sendmethod of the chat module.
Make sure that you have Node, Yarn, and the Keybase application installed. We also use developer tools such as EditorConfig, ESLint, Flow, and Prettier so you'll probably want to make sure that your development is configured to use those tools somewhere in your code writing process.
yarn.
src/.
yarn dev.
yarn buildto update
lib/.
yarn docs.
That's it. We accept changes via Pull Requests; please make sure that any changes you make build successfully and pass Flow, Prettier, and ESLint checks. We'd also really appreciate it if your PR could follow the Conventional Commit specification. If you're adding a new feature, please add/update tests, demos, documentation, and whatever else makes sense to go with it. If you have any questions about contributing, please feel free to ask a maintainer!
We run tests using Jest. All tests are run against actual Keybase processes that are created and destroyed during testing and ping the actual Keybase server to do things like send messages and XLM. To facilitate this, the tests read a file in
__tests__/test.config.tsthat contains usernames, paperkeys, and team names that are used during testing. You'll need three test Keybase accounts, two teams, and some Stellar Lumens to run all tests.
__tests__/test.config.example.tsas
__tests__/test.config.ts. Note that
__tests__/test.config.tsshould NOT be version controlled, as it will contain paper keys!
__tests__/test.config.tsas it specifies, replacing the placeholder values with actual usernames, paperkeys, and team names.
yarn test. Everything should pass!
Most of the types the bot uses are generated from definitions defined in the
protocol/directory inside the Keybase client repo. This ensures that the types that the bot uses are consistent across bots and always up to date with the output of the API.
To build the types for the TypeScript bot, you'll need to clone the
clientrepo. This requires Go and your GOPATH to be set up.
go get github.com/keybase/client/go/keybase
and install the necessary dependencies for compiling the protocol files. This requires node.js and Yarn.
cd client/protocol yarn install
Then you can generate the types by using the provided Makefile in this repo.
cd path/to/keybase-bot make
Should you need to remove all the types for some reason, you can run
make clean.
We automatically generate a CHANGELOG and version (using Semantic Versioning)
keybase-botwith
standard-version. To cut a new release:
masterbranch.
masterand ensure it's up to date with
origin/master.
standard-versionwith the command
yarn release.
origin. (
git push --follow-tags origin master)
yarn publish.
BSD-3-Clause