The Cleverbot API\u00a0is RESTful. You call a URL on our server and we return JSON.<\/p>\n
Sign up<\/strong> Making requests This will return a JSON object which looks like:<\/p>\n Parameters<\/strong> The\u00a0key<\/em> parameter is always required. It is your API key.<\/p>\n The\u00a0input<\/em> parameter is what you want to say to Cleverbot, such as “hello”.<\/p>\n The\u00a0cs<\/em> 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<\/em> parameter. You just have to send it right back again to continue the conversation.<\/p>\n The\u00a0callback<\/em> parameter allows for JSONP requests. The returned JSON object will be wrapped by the\u00a0callback<\/em> function.<\/p>\n For example, you can call: And it will reply something like this:<\/p>\n You do not need to pass in any other parameters.<\/em> The conversation history is contained within the cs<\/em> variable.<\/p>\n However, if you wish to override the conversation history, you can pass in variables like vtext2<\/em> to override the last thing the bot said, vtext3<\/em> for the previous thing the user said, and so on. This feature was added in mid May 2017.<\/p>\n New Feature for October 2017!<\/strong><\/p>\n Along with the parameters above you can now also pass in cb_settings_tweak1<\/em>, cb_settings_tweak2<\/em> or cb_settings_tweak3<\/em> 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<\/a> (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.<\/p>\n JSON Reply<\/strong> The\u00a0interaction<\/em> variables come in pairs. For example\u00a0interaction_1<\/em> contains the last thing the user said, and interaction_1_other<\/em> is the bot’s reply.\u00a0interaction_2<\/em> 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\u00a0interaction5<\/em>, interaction_5_other<\/em>, interaction_4<\/em>, interaction_4_other<\/em>, etc.<\/p>\n Note that if a variable is blank, it may not be returned.<\/p>\n Out of all of these variables only the cs<\/em> variable need to be passed back to the API on the next request. It\u00a0contains the entire conversation history.<\/p>\n Status codes Using the API<\/strong> Or you can use Javascript and pass in a callback parameter. The following code snippet creates a\u00a0<script><\/em>\u00a0tag referencing our API. When the API returns the results, they will be passed to the\u00a0ProcessReply<\/em>\u00a0function which will tell you the proportion\u00a0of love:<\/p>\n The last three lines are much easier to read using\u00a0jQuery:<\/p>\n 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\u00a0used by someone else. So for public websites we\u00a0recommend making calls on the server-side using a language like Python or PHP.<\/p>\n You can also use PHP to communicate with the API but Javascript to handle the result:<\/p>\n Charging<\/strong> Each call to one of our API \u00a0containing 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.<\/p>\n Changing plan<\/strong> The Cleverbot API\u00a0is 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\u00a0where … <\/p>\n
\nFirst 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<\/a>\u00a0where you will find your API key and usage statistics.<\/p>\n
\n<\/strong>Once you have your API key you can test the API straight away in your browser. Visit:
\nhttps:\/\/www.cleverbot.com\/getreply?key=YOUR_API_KEY<\/em><\/p>\n{\r\n \"cs\":\"76nxdxIJO2...AAA\",\r\n \"interaction_count\":\"1\",\r\n \"input\":\"\",\r\n \"output\":\"Good afternoon.\",\r\n \"conversation_id\":\"AYAR1E3ITW\",\r\n ...\r\n}<\/pre>\n
\nThe URL for Cleverbot API should\u00a0always start with http:\/\/www.cleverbot.com\/getreply<\/em> or\u00a0https:\/\/www.cleverbot.com\/getreply<\/em>.<\/p>\n
\nhttp:\/\/www.cleverbot.com\/getreply?key=YOUR_API_KEY&input=Hello&cs=76nxdxIJ02AAA&callback=ProcessReply<\/em><\/p>\n{\r\n \"cs\":\"112nxdyIJO2...AAA\",\r\n \"interaction_count\":\"2\",\r\n \"input\":\"Hello.\",\r\n \"output\":\"How are you?\",\r\n \"conversation_id\":\"AYAR1E3ITW\",\r\n \"interaction_1\": \"Hello.\",\r\n \"interaction_1_other\": \"How are you?\",\r\n \"interaction_2\": \"\",\r\n \"interaction_2_other\": \"Good afternoon.\",\r\n ...\r\n}<\/pre>\n
\nThe JSON reply includes many variables. They are the same variables\u00a0as used by our\u00a0Cleverscript<\/a>\u00a0product, 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<\/a>, but only a few are relevant to the Cleverbot API:<\/p>\n\n
\n<\/strong>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<\/em>\u00a0and\u00a0error<\/em>. Possible errors are:<\/p>\n\n
\nOur API returns results in JSON format. Using PHP, a call to our API would look like:<\/p>\n<?php\r\n$url = \"https:\/\/www.cleverbot.com\/getreply\";\r\n$key = \"YOUR_API_KEY\";\r\n$input = rawurlencode (\"How are you?\");\r\n$apidata = json_decode (file_get_contents (\"$url?input=$input&key=$key\"));\r\n?><\/pre>\n
<script>\r\nurl = \"https:\/\/www.cleverbot.com\/getreply\";\r\nkey = \"YOUR_API_KEY\";\r\ninput = encodeURIComponent (\"How are you?\");\r\nfunction ProcessReply (data) {\r\n if (data.error) console.log ('Error: ' + data.error);\r\n else alert ('Reply: ' + data.output);\r\n}\r\nscript_element = document.createElement('script'); \/\/create new script element\r\nscript_element.src = url + \"?input=\" + input + '&key=' + key + '&callback=ProcessReply';\r\ndocument.getElementsByTagName ('head')[0].appendChild(script_element); \/\/append to page, which executes it\r\n<\/script><\/pre>\n<script>\r\n$.ajax({\r\n url: url,\r\n data: {\"input\": input, \"key\": key}, \/\/input automatically encoded\r\n dataType: \"jsonp\",\r\n success: ProcessReply\r\n});\r\n<\/script><\/pre>\n<?php\r\n$url = \"https:\/\/www.cleverbot.com\/getreply\";\r\n$key = \"YOUR_API_KEY\";\r\n$input = rawurlencode (\"How are you?\");\r\necho \"<script>ProcessReply (\" . file_get_contents (\"$url?input=$input&key=$key\") . \")<\/script>\";\r\n?><\/pre>\n
\nAccess to our API is provided on a monthly basis, starting on the day you place\u00a0your order. If you have chosen the API Starter the first three months are free.<\/p>\n
\nYou can change your plan by going to My Account<\/a>, then Subscriptions<\/a>, clicking\u00a0on your order to view it and pressing “Upgrade or Downgrade”.<\/p>\n","protected":false},"excerpt":{"rendered":"