User Guide

Ready to get started? This page gives an overview of how to install and use kik

Installation

You can install the library though pip, either from the command line:

$ pip install kik

or add the following line to your project’s requirements.txt file:

kik==1.5.0

Example Bot

Here is a minimal echo bot using Flask

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
from flask import Flask, request, Response

from kik import KikApi, Configuration
from kik.messages import messages_from_json, TextMessage

app = Flask(__name__)
kik = KikApi(BOT_USERNAME, BOT_API_KEY)

kik.set_configuration(Configuration(webhook=YOUR_WEBHOOK))

@app.route('/incoming', methods=['POST'])
def incoming():
    if not kik.verify_signature(request.headers.get('X-Kik-Signature'), request.get_data()):
        return Response(status=403)

    messages = messages_from_json(request.json['messages'])

    for message in messages:
        if isinstance(message, TextMessage):
            kik.send_messages([
                TextMessage(
                    to=message.from_user,
                    chat_id=message.chat_id,
                    body=message.body
                )
            ])

    return Response(status=200)


if __name__ == "__main__":
    app.run(port=8080, debug=True)

The API Client

The core of the library is the KikApi class, which is used to send requests to the Kik API. The client needs to be instantiated with your bot’s username and API key:

>>> from kik import KikApi
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)

Configuration

The Configuration API can be accessed through two functions.

KikApi.get_configuration retrieves your bots current configuration as a Configuration object.

>>> from kik import KikApi
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> config = kik.get_configuration()
>>> config.webhook
'https://example.com/incoming'

KikApi.set_configuration sets your bot’s configuration, taking a Configuration object.

>>> from kik import KikApi, Configuration
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> config = Configuration(webhook='https://example.com/incoming')
>>> kik.set_configuration(config)
<kik.Configuration>

Receiving Messages

The library contains two functions that are useful when receiving messages to your webhook

The first is KikApi.verify_signature which is takes care of authenticating incoming requests to your webhook.

Just call the method with the provided signature header and the body of the incoming HTTP request:

>>> from kik import KikApi
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> kik.verify_signature(SIGNATURE_HEADER, REQUEST_BODY)
True

If this method returns False, you should ignore the incoming request, as it may be malicious.

Note

verify_signature must be called with the raw request body, not the parsed JSON

The second important function for receiving messages is messages.messages_from_json, which converts incoming messages into Python objects. After you parse the incoming request as JSON, simply pass the array of messages in the messages field to the function to get an array of message objects.

>>> from kik.messages import messages_from_json
>>> messages_from_json(messages)
[<kik.messages.TextMessage>, <kik.messages.LinkMessage>]

For a complete list of message types you might receive, see the Kik API Documentation.

Sending Messages

Messages are sent using KikApi.send_messages for the messaging API.

>>> from kik import KikApi
>>> from kik.messages import TextMessage
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> kik.send_messages([
...     TextMessage(
...         to='aleem',
...         chat_id='8c595a879e4140dbecb60f6c6933348bfd940cd9cbd6014e8fa51f24b5c8f74a',
...         body='Test'
...     )
... ])
{}

Similarly, messages can be sent through the broadcasting API, using KikApi.send_broadcast.

>>> from kik import KikApi
>>> from kik.messages import TextMessage
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> kik.send_broadcast([
...     TextMessage(
...         to='aleem',
...         chat_id='8c595a879e4140dbecb60f6c6933348bfd940cd9cbd6014e8fa51f24b5c8f74a',
...         body='Test'
...     )
... ])
{}

Messages are constructed using the Message subclasses. in kik.messages. These classes directly mirror the API message formats, with the exceptions of snake_case naming, from being renamed to from_user (as from is a reserved keyword in Python), and the handling of attribution and keyboards (explained below).

Attribution

All message types that support attribution are subclasses of AttributableMessage. To give custom attribution to these messages, simply assign their attribution property to a CustomAttribution instance.

>>> from kik.messages import CustomAttribution, LinkMessage
>>> message = LinkMessage()
>>> message.attribution = CustomAttribution(
...     name='A Name',
...     icon_url='http://foo.bar/anicon'
... )

Additionally, there are special attribution values to make a PictureMessage or VideoMessage appear to be from the camera or gallery. To achieve these effects, assign the attribution property of the message PresetAttributions.CAMERA or PresetAttributions.GALLERY

>>> from kik.messages import PresetAttributions
>>> message = PictureMessage()
>>> message.attribution = PresetAttributions.CAMERA

Keyboards

All message types that support keyboards are subclasses of KeyboardMessage. These messages contain a keyboards array holding any number of Keyboard instances.

Currently, the only supported keyboard types is SuggestedResponseKeyboard, which must be assigned a responses array containing instances of classes subclassing SuggestedResponse (e.g. TextResponse, PictureResponse and FriendPickerResponse).

>>> from kik.messages import TextMessage, SuggestedResponseKeyboard, \
...     TextResponse
>>> message = TextMessage()
>>> message.keyboards.append(
...     SuggestedResponseKeyboard(
...         to='aleem',
...         hidden=True,
...         responses=[TextResponse('OK')]
...     )
... )

Users

The User Profile API is accessed through KikApi.get_user<kik.KikApi.get_user(), which retrieves a user’s profile from their username.

The function returns a User, containing the user’s profile

>>> from kik import KikApi
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> user = kik.get_user('aleem')
>>> user.first_name
'Johnny'

Kik Codes

The Kik Code creation API is accessed through KikApi.create_code. This function takes an optional data parameter which will be embedded in the Kik Code, and returned in the ScanDataMessage you receive when the user scans the code.

create_code returns a Code, which allows you to get a URL for the code.

>>> from kik import KikApi
>>> kik = KikApi(BOT_USERNAME, BOT_API_KEY)
>>> code = kik.create_code({'some': 'data'})
>>> code.url()
'https://api.kik.com/v1/code/161d764eeebf050fba373ae8cef9f5052524019a'