Kik Node API

About

This library is a Node wrapper for the Kik Bot API to help you develop a bot for Kik Messenger in Node.js. To learn more about the Kik Bot platform check out dev.kik.com or follow the steps below to get started.

Contributing

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to bots@kik.com.

If you're looking to contribute to the kik package, check out the Contributing Guide.

Getting Started

Creating a basic Kik bot is simple:

Create Your Bot on dev.kik.com

Go over to dev.kik.com.

...and in Kik, hit the plus button in the top right corner and then hit 'scan a Kik code'.

(the above scan code is only an example, you must go to the link above for a valid scan code)

Pointing your camera at the code will allow Kik to scan the code and introduce you to Botsworth, the bot maker bot. Follow the prompts to configure your bot.

Botsworth will ask you to give your bot a name which, is the first step. Choose wisely! Your bot should be cleverly and descriptively named - it should provide relatively clear indication as to the function of your bot. Hint: Avoid numbers and special characters in your bot's name.

Once you've chosen your bot's name, Botsworth will ask you to confirm, and will then log you into the Kik Bot Dashboard. You will be prompted to agree to the Kik API Terms of Use.

Next step: Setting up your development environment!

Setting up the NPM

Make sure you're running at least npm 2.2.1 and Node 8.0.0. We'll be using npm version 5.5.1 and Node version 8.9.0 today on Linux / MacOS X.

Go ahead and open terminal and install the Kik Node Package:

Install with npm install @kikinteractive/kik

Getting the Sample Code

We're going to be using this sample javascript to create a basic echo bot. Go ahead and create a new .js file and name it 'MyFirstEchoBot.js'. Paste in the sample code below:

'use strict';

// We are gonna need to import the http library and the kikBot SDK 
// so that we can use them to make our bot work
let util = require('util'); 
let http = require('http');
let Bot  = require('@kikinteractive/kik');

// We are first gonna create a new bot object with all of 
// the information we just filled in on dev.kik.com
let bot = new Bot({
    username: 'BOT_USERNAME_HERE', // The username you gave BotsWorth on Kik 
    apiKey: 'BOT_API_KEY_HERE', // The API Key you can find on your profile on dev.kik.com
    baseUrl: 'WEBHOOK_HERE' // THIS IS YOUR WEBHOOK! make sure this maches the web tunnel or host you have running 
});

// Send the configuration to kik to update the bot with the information above
bot.updateBotConfiguration();

// The onTextMessage(message) handler. This is run everytime your bot gets a message. 
// The method takes a message object as a parameter.
bot.onTextMessage((message) => {

    // We take the message and call the reply method with the body of the message we recieved 
    // this is the "echo" functionality of our bot 
    message.reply(message.body);

    // print out the message so we can see on the server what's being sent 
    console.log(message.body);
});

// We want to set up our start chatting message. This will be the first message the user gets when they start 
// chatting with your bot. This message is only sent once. 
bot.onStartChattingMessage((message) => {
    bot.getUserProfile(message.from)
        .then((user) => {
            message.reply(`Hey ${user.firstName}! I'm your new echo bot. Send me a message and I'll send it right back!`);
        });
});

// Set up your server and start listening
let server = http
    .createServer(bot.incoming())
    .listen(8000, (err) => {
  if (err) {
    return console.log('something bad happened', err)
  }

  console.log(`server is listening on 8000`)
});

Next step: Filling in your information

How Bots Work

Kik bots talk to the Kik infrastructure via HTTP requests: When sending a message, you send a request to us, and for messages to be received by your bot, Kik will make requests to your endpoint. In other words, Kik must be able to call your URL on your web server.

Configuring Your Server

For our bot to work, we need to have an address that's accessible from the internet. Many production Kik bots run in cloud based services such as Heroku, Google App Engine or Amazon Web Services - or in their own data center infrastructure.

However, for development purposes you can use ngrok to provide access to your bot running in your local network. Ngrok is easy to setup and use, and has excellent documentation.

Ngrok is a handy tool and service that allows you tunnel requests from the wide open Internet to your local machine when it's behind a NAT or firewall. It's commonly used to develop web services and webhooks.

If you're using ngrok, launch it now in a new terminal window:

$ ngrok http 8080

When it launches, you will see a screen similar to the following:

ngrok by @inconshreveable                                                                                                                                                                 (Ctrl+C to quit)
                                                                                                                                                                                                          
Session Status                online                                                                                                                                                                      
Account                       A Bot Developer (Plan: Free)                                                                                                                                                 
Version                       2.1.18                                                                                                                                                                      
Region                        United States (us)                                                                                                                                                          
Web Interface                 http://127.0.0.1:4040                                                                                                                                                       
Forwarding                    http://ABCDEFG123.ngrok.io -> localhost:8080                                                                                                                                  
Forwarding                    https://ABCDEFG123.ngrok.io -> localhost:8080                                                                                                                                 
                                                                                                                                                                                                          
Connections                   ttl     opn     rt1     rt5     p50     p90                                                                                                                                 
                              0       0       0.00    0.00    0.00    0.00

Note the "Forwarding" address (https://ABCDEFG123.ngrok.io), as this will become part of your 'webhook' address.

Configuring Your Bot

To get the bot running, you're going to need your bot's username, and the API key. This is all available from dev.kik.com. It will be similar to the following screenshot:

Here you can set the display name and "profile picture" for your bot. You'll need to copy/paste your API key into the bot's source code.

We'll also need to set the webhook to the URL of your bot's "incoming messages" route on your web server. This is where Kik will send all the messages that users send to your bot. In the example code, the route for incoming messages is /incoming

In your 'MyFirstEchoBot.js' file, change:

let bot = new Bot({
    username: 'BOT_USERNAME_HERE', 
    apiKey: 'BOT_API_KEY_HERE', 
    baseUrl: 'WEBHOOK_HERE'  
});

so that your bot's username and your API key are passed to Kik API's Bot constructor. For example, if we named our bot ademobot, and according the bot configuration panel our API key is 5a888dcb-4c6e-1973-b15t-308e1854f0ba, then we would change the above line to:

let bot = new Bot({
    username: 'ademobot', 
    apiKey: '5a888dcb-4c6e-1973-b15t-308e1854f0ba', 
    baseUrl: 'WEBHOOK_HERE'  
});

Now for your webhook, Kik will send messages to this path upon receipt. So, if your web address is https://www.example.com then you'll set your webhook to https://www.example.com/incoming, as shown below.

let bot = new Bot({
    username: 'ademobot', 
    apiKey: '5a888dcb-4c6e-1973-b15t-308e1854f0ba', 
    baseUrl: 'https://www.example.com/incoming'  
});

If you're using ngrok as shown above, you would set the webhook as follows:

let bot = new Bot({
    username: 'ademobot', 
    apiKey: '5a888dcb-4c6e-1973-b15t-308e1854f0ba', 
    baseUrl: 'https://ABCDEFG123.ngrok.io/incoming'  
});

Launch Your Bot

once you've got your 'MyFirstEchoBot.js' file ready, were going to open up terminal and run our Node server. cd to the directory that you saved your '.js' file in.

$ cd MyFirstEchoBot

Start the bot by running the file as shown below:

$ node 'MyFirstEchoBot'.js
 * server is listening on 8000

Talking to the bot

With your bot up and running, you'll be able to chat with it in Kik. New users can click on the magnifying glass in their messages list to search for your bot. Once found, they can click on "Start Chatting" to subscribe to your bot and start interacting!

Getting Help

Here are other resources for using Kik node:

stackoverflow.com is a great place to get answers about building a Kik chat bot.
Go to dev.kik.com to get started building a bot, scan the code at dev.kik.com and talk to Botsworth.

License

The Kik bot library is released under the terms of the MIT license. See License for more information or see https://opensource.org/licenses/MIT.

Additional Documentation

Sending a message to a specific user

You can send a targeted message to a user once they have subscribed to your bot. If you want to send someone a message, just call bot.send(...) with their username. You don't need to specify a chat ID here since you are sending it directly to the user, not within a specific chat.

// To one user (a.username)
bot.send(Bot.Message.text('Hey, nice to meet you!'), 'a.username');

// You can use a shorthand for text messages to keep things a bit cleaner
bot.send('Getting started is super easy!', 'a.username');

Sending a picture message

If you want to send a photo to a user you can send a picture message. The API will download the image you supply and pass it along. You have to set the attribution name and icon for the message so the knows where the content came from even if it's forwarded later.

bot.send(Bot.Message.picture('http://i.imgur.com/oalyVlU.jpg')
    .setAttributionName('Imgur')
    .setAttributionIcon('http://s.imgur.com/images/favicon-96x96.png'),
    'a.username');

Greeting a user by name

Whenever a user subscribes to your bot, your bot will receive a start-chatting message. This message gives you the chance to say hello to the user and let them know what your bot is about.

You might want to greet your new user by name. You can use the bot.getUserProfile(...) method to request information about users who have subscribed to your bot.

bot.onStartChattingMessage((message) => {
    bot.getUserProfile(message.from)
        .then((user) => {
            message.reply(`Hey ${user.firstName}!`);
        });
});

Adding multiple handlers

Separating different states into multiple message handlers can keep your bot logic under control. If you call next from within your handler, you allow the next handler in the chain to run, otherwise, handling of the incoming message will end with the current handler.

bot.onTextMessage((message, next) => {
    const userState = getUserState(message.from);

    if (!userState.inIntroState) {
        // Send the user the intro state
        // ...

        return;
    }

    // Allow the next handler take over
    next();
});

bot.onTextMessage((message) => {
    searchFor(message.body)
        .then((result) => {
            message.reply(result);
        });
});

Setting a static keyboard

You can specify a static keyboard for your bot when a user starts mentioning it in a conversation:

let bot = new Bot({
    username: 'echo.bot',
    apiKey: '7b939d69-e840-4d22-aab8-4188c2198f8a',
    baseUrl: 'https://kik-echobot.ngrok.io/',
    staticKeyboard: new Bot.ResponseKeyboard(['Option 1', 'Option 2'])
});

API Documentation

Bot

Parses user messages sent from Kik's server. Use the .incoming() method to return the middleware in a form of function (req, res, next) {}. The middleware will automatically decode the request, and call the appropriate on functions based on the content type. Additional middleware can be used by calling the .use(handler) method.

Kind: global class
See: https://bots.kik.com

new Bot()

Param	Type	Description
options.username	`string`
options.apiKey	`string`
[options.baseUrl]	`string`
[options.incomingPath]	`string`	Set true to enable polling or set options
[options.manuallySendReadReceipts]	`boolean`
[options.receiveReadReceipts]	`boolean`
[options.receiveDeliveryReceipts]	`boolean`
[options.receiveIsTyping]	`boolean`
[options.skipSignatureCheck]	`boolean`	Verify the authenticity of inbound requests. For testing only, do not disable for a bot in production.
[options.staticKeyboard]	`ResponseKeyboard`	Static keyboard for your bot

bot.use(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.updateBotConfiguration()

Kind: instance method of Bot

bot.onTextMessage([text], handler)

Kind: instance method of Bot

Param	Type
[text]	`string` \| `regexp`
handler	`MessageHandlerCallback`

Example

bot.onTextMessage((incoming, next) => {
     // reply handles the message and stops other handlers
     // from being called for this message
     incoming.reply(`Hi I'm ${bot.username}`);
 });

Example

bot.onTextMessage((incoming, next) => {
     if (incoming.body !== 'Hi') {
         // we only handle welcoming, let someone else deal with this
         // message
         return next();
     }

     // say hello...
 });

Example

bot.onTextMessage(/^hi|hello|bonjour$/i, (incoming, next) => {
     // say hello...
 });

bot.onLinkMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onPictureMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onVideoMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onStartChattingMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onScanDataMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onFriendPickerMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onStickerMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onIsTypingMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onDeliveryReceiptMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.onReadReceiptMessage(handler)

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

bot.getKikCodeUrl() ⇒ `promise.<string>`

Creates a Kik Code with the intended options and returns the URL of the Kik Code image. If the options specify a data Kik Code this will hit the Kik Code service and store that data for you.

Kind: instance method of Bot

Param	Type	Description
[options.data]	`string` \| `object`	The data to be sent back to this bot after the user scans
[options.width]	`number`	Width of the Kik code in the PNG image
[options.height]	`number`	Height of the Kik code in the PNG image
[options.size]	`number`	Helper for the width and height in the PNG image
[options.color]	`number`	The color which the user will see after scanning. See {KikCode.Colors}

bot.getUserProfile() ⇒ `promise.<UserProfile>`

Kind: instance method of Bot

bot.broadcast(messages, recipients)

Kind: instance method of Bot

Param	Type
messages	`array`
recipients	`array`

bot.send(messages, recipient, [chatId])

Kind: instance method of Bot

Param	Type
messages	`array`
recipient	`string`
[chatId]	`string`

bot.incoming()

Handles the incoming requests for messages configuration.

Kind: instance method of Bot

bot.outgoing(handler)

Adds a post processing handler for all outgoing messages. Messages passed to this handler will be JSON objects.

Kind: instance method of Bot

Param	Type
handler	`MessageHandlerCallback`

Example

bot.outgoing((outgoing, next) => {
     console.log('Outgoing message:', outgoing);
     next();
});

IncomingMessage

Object that allows you to send a response to user messages or ignore them.

Kind: global class

IncomingMessage
- .reply(messages) ⇒ promise.<object>
- .markRead() ⇒ promise.<object>
- .startTyping() ⇒ promise.<object>
- .stopTyping() ⇒ promise.<object>
- .ignore()

incomingMessage.reply(messages) ⇒ `promise.<object>`

Kind: instance method of IncomingMessage

Param	Type
messages	`Message` \| `array.<Message>`

incomingMessage.markRead() ⇒ `promise.<object>`

Kind: instance method of IncomingMessage

incomingMessage.startTyping() ⇒ `promise.<object>`

Kind: instance method of IncomingMessage

incomingMessage.stopTyping() ⇒ `promise.<object>`

Kind: instance method of IncomingMessage

incomingMessage.ignore()

Kind: instance method of IncomingMessage

UserProfile

See https://dev.kik.com/#/docs/messaging#user-profiles

Kind: global class

UserProfile
- .displayName ⇒ string
- .username ⇒ string
- .firstName ⇒ string
- .lastName ⇒ string
- .profilePicUrl ⇒ string
- .profilePicLastModified ⇒ number
- .timezone ⇒ string

userProfile.displayName ⇒ `string`

Kind: instance property of UserProfile

userProfile.username ⇒ `string`

Kind: instance property of UserProfile

userProfile.firstName ⇒ `string`

Kind: instance property of UserProfile

userProfile.lastName ⇒ `string`

Kind: instance property of UserProfile

userProfile.profilePicUrl ⇒ `string`

Kind: instance property of UserProfile

userProfile.profilePicLastModified ⇒ `number`

Kind: instance property of UserProfile

userProfile.timezone ⇒ `string`

Kind: instance property of UserProfile

Message

Object that stores a specific message that can be sent to/received from a user. The static methods of Message are factories that generate a specific kind of message.

Kind: global class

Message
- static
  - .text() ⇒ Message
  - .link() ⇒ Message
  - .picture() ⇒ Message
  - .video() ⇒ Message
  - .isTyping() ⇒ Message
  - .readReceipt() ⇒ Message
  - .fromJSON(json) ⇒ Message
- instance
  - .from ⇒ string
  - .id ⇒ string
  - .chatId ⇒ string
  - .messageIds ⇒ array
  - .readReceiptRequested ⇒ boolean
  - .stickerPackId ⇒ string
  - .scanData ⇒ string
  - .stickerUrl ⇒ string
  - .timestamp ⇒ number
  - .type ⇒ string
  - .kikJsData ⇒ object
  - .picUrl ⇒ string
  - .noForward ⇒ boolean
  - .isTyping ⇒ boolean
  - .body ⇒ string
  - .text ⇒ string
  - .title ⇒ string
  - .url ⇒ string
  - .videoUrl ⇒ string
  - .delay ⇒ number
  - .typeTime ⇒ number
  - .attributionName ⇒ string
  - .attributionIcon ⇒ string
  - .loop ⇒ boolean
  - .muted ⇒ boolean
  - .autoplay ⇒ boolean
  - .noSave ⇒ boolean
  - .participants ⇒ array
  - .chatType ⇒ string
  - .mention ⇒ string
  - .picked ⇒ array
  - .metadata ⇒ object
  - .isInPublicChat() ⇒ boolean
  - .isInPrivateChat() ⇒ boolean
  - .isInDirectChat() ⇒ boolean
  - .isTextMessage() ⇒ boolean
  - .isLinkMessage() ⇒ boolean
  - .isPictureMessage() ⇒ boolean
  - .isVideoMessage() ⇒ boolean
  - .isStartChattingMessage() ⇒ boolean
  - .isScanDataMessage() ⇒ boolean
  - .isFriendPickerMessage() ⇒ boolean
  - .isStickerMessage() ⇒ boolean
  - .isIsTypingMessage() ⇒ boolean
  - .isDeliveryReceiptMessage() ⇒ boolean
  - .isReadReceiptMessage() ⇒ boolean
  - .isMention() ⇒ boolean
  - .toJSON() ⇒ object
  - .addTextResponse(text) ⇒ Message
  - .addResponseKeyboard(suggestions, [isHidden], [user]) ⇒ Message
  - .setKikJsData(kikJsData) ⇒ Message
  - .setPicUrl(picUrl) ⇒ Message
  - .setNoForward(noForward) ⇒ Message
  - .setIsTyping(isTyping) ⇒ Message
  - .setMessageIds(messageIds) ⇒ Message
  - .setBody(body) ⇒ Message
  - .setText(text) ⇒ Message
  - .setTitle(title) ⇒ Message
  - .setUrl(url) ⇒ Message
  - .setVideoUrl(videoUrl) ⇒ Message
  - .setDelay(delay) ⇒ Message
  - .setTypeTime(typeTime) ⇒ Message
  - .setAttributionName(attributionName) ⇒ Message
  - .setAttributionIcon(attributionIcon) ⇒ Message
  - .setLoop(loop) ⇒ Message
  - .setMuted(muted) ⇒ Message
  - .setAutoplay(autoplay) ⇒ Message
  - .setNoSave(noSave) ⇒ Message
  - .setMention(noSave) ⇒ Message

message.from ⇒ `string`

See https://dev.kik.com/#/docs/messaging#receiving-messages

Kind: instance property of Message

message.id ⇒ `string`

See https://dev.kik.com/#/docs/messaging#receiving-messages

Kind: instance property of Message

message.chatId ⇒ `string`

See https://dev.kik.com/#/docs/messaging#receiving-messages

Kind: instance property of Message

message.messageIds ⇒ `array`

See https://dev.kik.com/#/docs/messaging#receipts

Kind: instance property of Message

message.readReceiptRequested ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#receipts

Kind: instance property of Message

message.stickerPackId ⇒ `string`

See https://dev.kik.com/#/docs/messaging#sticker

Kind: instance property of Message

message.scanData ⇒ `string`

See https://dev.kik.com/#/docs/messaging#kik-codes-api

Kind: instance property of Message

message.stickerUrl ⇒ `string`

See https://dev.kik.com/#/docs/messaging#sticker

Kind: instance property of Message

message.timestamp ⇒ `number`

See https://dev.kik.com/#/docs/messaging#common-fields

Kind: instance property of Message

message.type ⇒ `string`

See https://dev.kik.com/#/docs/messaging#message-formats

Kind: instance property of Message

message.kikJsData ⇒ `object`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.picUrl ⇒ `string`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.noForward ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.isTyping ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#is-typing

Kind: instance property of Message

message.body ⇒ `string`

See https://dev.kik.com/#/docs/messaging#text

Kind: instance property of Message

message.text ⇒ `string`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.title ⇒ `string`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.url ⇒ `string`

See https://dev.kik.com/#/docs/messaging#link

Kind: instance property of Message

message.videoUrl ⇒ `string`

See https://dev.kik.com/#/docs/messaging#video

Kind: instance property of Message

message.delay ⇒ `number`

See https://dev.kik.com/#/docs/messaging#common-fields

Kind: instance property of Message

message.typeTime ⇒ `number`

See https://dev.kik.com/#/docs/messaging#text

Kind: instance property of Message

message.attributionName ⇒ `string`

See https://dev.kik.com/#/docs/messaging#attribution

Kind: instance property of Message

message.attributionIcon ⇒ `string`

See https://dev.kik.com/#/docs/messaging#attribution

Kind: instance property of Message

message.loop ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#video

Kind: instance property of Message

message.muted ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#video

Kind: instance property of Message

message.autoplay ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#video

Kind: instance property of Message

message.noSave ⇒ `boolean`

See https://dev.kik.com/#/docs/messaging#video

Kind: instance property of Message

message.participants ⇒ `array`

See https://dev.kik.com/#/docs/messaging#participants

Kind: instance property of Message

message.chatType ⇒ `array`

See https://dev.kik.com/#/docs/messaging#all-received-chat-messages-excluding-receipts (will be undefined for receipt messages)

Kind: instance property of Message

message.mention ⇒ `string`

See https://dev.kik.com/#/docs/messaging#mention

Kind: instance property of Message

message.picked ⇒ `string`

See https://dev.kik.com/#/docs/messaging#friend-picker

Kind: instance property of Message