Example

import cleverbot


cb = cleverbot.Cleverbot('YOUR_API_KEY', timeout=60)

text = input("Say to Cleverbot: ")
try:
    reply = cb.say(text)
except cleverbot.CleverbotError as error:
    print(error)
else:
    print(reply)
finally:
    cb.close()

Installing

Install it normally from PyPI with pip:

pip install cleverbot.py

Or install it with the asynchronous dependencies (Python 3.4.2+ only):

pip install cleverbot.py[async]

Requirements:

• Python 3.2+ or 2.7

• A Cleverbot API key

Dependencies:

• requests 1.0.0+

• Asynchronous:

  • aiohttp 1.0.0+

Usage

First import the package:

import cleverbot

If you have the asynchronous dependencies and want to use Cleverbot asynchronously import it as below instead:

from cleverbot import async_ as cleverbot

Then initialize Cleverbot with your API key and optionally a cleverbot state, timeout and or tweak if you want to adjust Cleverbot’s mood:

cb = cleverbot.Cleverbot('YOUR_API_KEY', cs='76nxdxIJ02AAA', timeout=60, tweak1=0, tweak2=100, tweak3=100)

The cleverbot state is the encoded state of the conversation that you get from talking to Cleverbot and includes the whole conversation history.

If you’re using Cleverbot asynchronously you can also give an event loop to Cleverbot with a loop keyword argument

You can now start talking to Cleverbot.

Talk straight to Cleverbot:

reply = cb.say("Hello")

You can pass in keyword arguments to Cleverbot.say such as cs to change the conversation, vtext to change the current conversation’s history, or even tweak as an alias for cb_settings_tweak to change Cleverbot’s mood. Read the “Parameters” section of the official Cleverbot API docs for more information.

Alternatively, start a new conversation and talk from it:

convo = cb.conversation()
reply = convo.say("Hello")

Conversations are like mini Cleverbots so you can pass in anything that Cleverbot takes as keyword arguments including key. The values you don’t pass in excluding the cleverbot state will be taken from the originating Cleverbot.

If you want to manage your conversations more easily you can pass in a name as the first argument to every conversation you create which will turn Cleverbot.conversations into a dictionary with the name as the key and the conversation as the value. Trying to mix both named and nameless conversations will result in an error.

Cleverbot.say and Conversation.say are coroutines if you’re running asynchronously.

If something goes wrong with the request such as an invalid API key an APIError will be raised containing the error message or if you’ve defined a timeout and don’t get a reply within the defined amount of seconds you’ll get a Timeout.

As an example:

cleverbot.errors.APIError: Missing or invalid API key or POST request, please visit www.cleverbot.com/api

You can get the error message and the HTTP status from the error like so:

try:
    cb.say("Hello")
except cleverbot.APIError as error:
    print(error.error, error.status)

This is similar for Timeout where you can get the defined timeout value with Timeout.timeout.

Additionally, all Cleverbot errors subclass CleverbotError so you can use it to catch every Cleverbot related error.

To access the data gained from talking straight to Cleverbot or from talking in a conversation you can either get it from an attribute or directly get it from the Cleverbot.data or Conversation.data dictionary:

cb.conversation_id == cb.data['conversation_id']
convo.conversation_id == convo.data['conversation_id']

Note that every attribute except for Cleverbot.cs and Conversation.cs (i.e. the cleverbot state) is read-only and will get shadowed if you set it to something.

For a list of all of the data and their descriptions go to the “JSON Reply” section in the official Cleverbot API docs.

To reset Cleverbot’s and all of its conversations’ data you can simply do the following:

cb.reset()

To only reset a single conversation’s data use Conversation.reset instead:

convo.reset()

Resetting won’t delete any conversations so you’ll be able to reuse them.

If you want to save the current state of Cleverbot and all of its conversations you can use Cleverbot.save:

cb.save('cleverbot.pickle')

This saves the key, timeout and tweaks you’ve given to Cleverbot and its conversations and also the data of each including the cleverbot state.

In order to load and recreate the previously saved state as a new Cleverbot instance use load:

cb = cleverbot.load('cleverbot.pickle')

To only load the data and conversations use Cleverbot.load:

cb.load('cleverbot.pickle')

Loading conversations will delete the old ones.

When you’re done with the current instance of Cleverbot, close Cleverbot’s connection to the API:

cb.close()

Cleverbot.close is a coroutine if you’re using Cleverbot asynchronously.