Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

A Cleverbot API wrapper for Python with asynchronous functionality.

Project description is a Cleverbot API wrapper for Python made to be both fully-featured and easy to use.


import cleverbot

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

text = input("Say to Cleverbot: ")
    reply = cb.say(text)
except cleverbot.CleverbotError as error:


Install it normally from PyPI with pip:

pip install

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

pip install[async]



  • requests 1.0.0+
  • Asynchronous:
    • aiohttp 1.0.0+


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

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

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 or dictionary:

cb.conversation_id ==['conversation_id']
convo.conversation_id ==['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:


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


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.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:


Loading conversations will delete the old ones.

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


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 2.5.0
Filename, size File type Python version Upload date Hashes
Filename, size (15.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size (14.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page