The Cleverbot API is RESTful. You call a URL on our server and we return JSON.
Sign up
First of all, you need to sign up to our API. You will have to provide card details, and will be charged according to the package you choose, but you can cancel any time. Then visit My Account where you will find your API key and usage statistics.
Making requests
Once you have your API key you can test the API straight away in your browser. Visit:
https://www.cleverbot.com/getreply?key=YOUR_API_KEY
This will return a JSON object which looks like:
{
"cs":"76nxdxIJO2...AAA",
"interaction_count":"1",
"input":"",
"output":"Good afternoon.",
"conversation_id":"AYAR1E3ITW",
...
}
Parameters
The URL for Cleverbot API should always start with http://www.cleverbot.com/getreply or https://www.cleverbot.com/getreply.
The key parameter is always required. It is your API key.
The input parameter is what you want to say to Cleverbot, such as “hello”.
The cs parameter stands for “cleverbot state”. It is the encoded state of the conversation so far and includes the whole conversation history up to that point. Every time you call the API, it will send back the cs parameter. You just have to send it right back again to continue the conversation.
The callback parameter allows for JSONP requests. The returned JSON object will be wrapped by the callback function.
For example, you can call:
http://www.cleverbot.com/getreply?key=YOUR_API_KEY&input=Hello&cs=76nxdxIJ02AAA&callback=ProcessReply
And it will reply something like this:
{
"cs":"112nxdyIJO2...AAA",
"interaction_count":"2",
"input":"Hello.",
"output":"How are you?",
"conversation_id":"AYAR1E3ITW",
"interaction_1": "Hello.",
"interaction_1_other": "How are you?",
"interaction_2": "",
"interaction_2_other": "Good afternoon.",
...
}
You do not need to pass in any other parameters. The conversation history is contained within the cs variable.
However, if you wish to override the conversation history, you can pass in variables like vtext2 to override the last thing the bot said, vtext3 for the previous thing the user said, and so on. This feature was added in mid May 2017.
New Feature for October 2017!
Along with the parameters above you can now also pass in cb_settings_tweak1, cb_settings_tweak2 or cb_settings_tweak3 to vary how Cleverbot will respond. These settings correspond to the tweaks menu item in the blue bar at the top of www.cleverbot.com (available only after you have signed up and logged in). The parameters are percentage values between 0 and 100. Tweak 1 varies Cleverbot’s reply from sensible to wacky, tweak 2 from shy to talkative and tweak 3 from self-centred to attentive.
JSON Reply
The JSON reply includes many variables. They are the same variables as used by our Cleverscript product, which allows for scripted conversations to be placed on top of a mini-Cleverbot. The full list of these variables is shown and explained on page 26 of the Cleverscript manual, but only a few are relevant to the Cleverbot API:
- cs: state of the conversation so far, which contains an encoded copy of the conversation id and history
- interaction_count: how many pairs of bot/user interactions have occurred so far
- input: the entire user input, with any spaces trimmed off both ends
- output: Cleverbot’s reply
- conversation_id: identifier for this conversation between user and bot
- errorline: any error information from Cleverbot, this is different from general the general errors described below
- time_taken: the number of milliseconds the bot took to respond
- time_elapsed: approximate number of seconds since conversation started
- interaction_1 to interaction_100: record of the previous interactions
- callback: used by some versions of the software to store a callback function
The interaction variables come in pairs. For example interaction_1 contains the last thing the user said, and interaction_1_other is the bot’s reply. interaction_2 was the user’s previous input and so on. So to read the whole conversation in order, you have to display the interaction variables in reverse order, eg interaction5, interaction_5_other, interaction_4, interaction_4_other, etc.
Note that if a variable is blank, it may not be returned.
Out of all of these variables only the cs variable need to be passed back to the API on the next request. It contains the entire conversation history.
Status codes
If the request was successful, it will return the JSON format described above with an HTTP status code of 200. If there was an error, it will return a much smaller bit of JSON containing just status and error. Possible errors are:
- 401: unauthorised due to missing or invalid API key or POST request, the Cleverbot API only accepts GET requests
- 404: API not found
- 413 or 414: request too large if you send a request over 64Kb
- 502 or 504: unable to get reply from API server, please contact us
- 503: too many requests from a single IP address or API key
Using the API
Our API returns results in JSON format. Using PHP, a call to our API would look like:
<?php
$url = "https://www.cleverbot.com/getreply";
$key = "YOUR_API_KEY";
$input = rawurlencode ("How are you?");
$apidata = json_decode (file_get_contents ("$url?input=$input&key=$key"));
?>
Or you can use Javascript and pass in a callback parameter. The following code snippet creates a <script> tag referencing our API. When the API returns the results, they will be passed to the ProcessReply function which will tell you the proportion of love:
<script>
url = "https://www.cleverbot.com/getreply";
key = "YOUR_API_KEY";
input = encodeURIComponent ("How are you?");
function ProcessReply (data) {
if (data.error) console.log ('Error: ' + data.error);
else alert ('Reply: ' + data.output);
}
script_element = document.createElement('script'); //create new script element
script_element.src = url + "?input=" + input + '&key=' + key + '&callback=ProcessReply';
document.getElementsByTagName ('head')[0].appendChild(script_element); //append to page, which executes it
</script>
The last three lines are much easier to read using jQuery:
<script>
$.ajax({
url: url,
data: {"input": input, "key": key}, //input automatically encoded
dataType: "jsonp",
success: ProcessReply
});
</script>
Please note that putting your API key inside a Javascript file like this is not recommended on public websites. Your API key could be easily used by someone else. So for public websites we recommend making calls on the server-side using a language like Python or PHP.
You can also use PHP to communicate with the API but Javascript to handle the result:
<?php
$url = "https://www.cleverbot.com/getreply";
$key = "YOUR_API_KEY";
$input = rawurlencode ("How are you?");
echo "<script>ProcessReply (" . file_get_contents ("$url?input=$input&key=$key") . ")</script>";
?>
Charging
Access to our API is provided on a monthly basis, starting on the day you place your order. If you have chosen the API Starter the first three months are free.
Each call to one of our API containing your key counts as one API call. If you approach your monthly limit, we will contact you to let you know and ask you to upgrade to a different plan.
Changing plan
You can change your plan by going to My Account, then Subscriptions, clicking on your order to view it and pressing “Upgrade or Downgrade”.