Chatbot API Documentation

Need Help?
Get advice in the Chatbot API Forum

The Personality Forge's API is a simple RESTful Web Service API using JSON. There is only one call. Once you've selected a Chatbot API subscription, you'll find your apiKey and apiSecret listed on your Chatbot API page. This will let you make calls to the Chatbot API.



The Secure API or The Simple API


There are two APIs available. The Secure API is the recommended interface, as it provides strong security to ensure that your chatbot subscription is only used by your application. The Secure API requires some programming experience. The Simple API requires less programming experience and uses your apiKey and domain or IP for security.



Secure API

Simple API

The API Server

Host: https://www.personalityforge.com/api/chat/
Method: GET

Required GET Parameters

Parameter Type Required Description Example
apiKey 16-character string yes your supplied apiKey from your Chatbot API subscription by8Uai8Oa9suPFir
hash string yes created by encoding your message object with your apiSecret 134aa386b1f434fa94b68631a8aff6d5e0203d03d92fa9cde8c82831a4102412
message string yes url-encoded, JSON-encoded message object %7B%22message%22%3A%7B%22message%22%3A%22How+are+you+doing%3F%22%2C%22chatBotID%22%3A6%2C%22timestamp%22%3A1352845089%7D%2C%22user%22%3A%7B%22firstName%22%3A%22Tugger%22%2C%22lastName%22%3A%22Sufani%22%2C%22gender%22%3A%22m%22%2C%22externalID%22%3A%22639184572%22%7D%7D

Format:
https://www.personalityforge.com/api/chat/?apiKey=<apiKey>&hash=<hash>&message=<message>
Example Call:
https://www.personalityforge.com/api/chat/?apiKey=sampleElyggY577I&hash=134aa386b1f434fa94b68631a8aff6d5e0203d03d92fa9cde8c82831a4102412&message=%7B%22message%22%3A%7B%22message%22%3A%22How+are+you+doing%3F%22%2C%22chatBotID%22%3A6%2C%22timestamp%22%3A1352845089%7D%2C%22user%22%3A%7B%22firstName%22%3A%22Tugger%22%2C%22lastName%22%3A%22Sufani%22%2C%22gender%22%3A%22m%22%2C%22externalID%22%3A%22639184572%22%7D%7D

The Message JSON Object

Here is the format of the JSON message object with the information you send:
{
"message": {
  "message": "How are you doing today?",
  "chatBotID": 6,
  "timestamp": 1352853648
},
"user": {
  "firstName": "Tugger",
  "lastName": "Sufani",
  "gender": "m",
  "externalID": "abc-639184572"
}
}
Parameter Type Required Description Example
Message Object
message string yes what you're saying to the chatbot How are you doing today?
chatBotID integer yes the ID of the chatbot you're talking to 6
timestamp integer yes the current UTC timestamp 1352857720
User Object
externalID string yes a unique, consistent ID for the speaker to differentiate him/her from others in your system (max 32 characters) abc-639184572
firstName string no the speaker's first name or user name (max 32 characters) Tugger
lastName string no the speaker's last name (max 32 characters) Sufani
gender string no the speaker's gender: 'm' or 'f' m

Note: firstName, lastName, and gender are always optional, and only used the first time a new externalID comes in.


Encoding the Message and Hash

The apiKey and apiSecret secure the system. Let's walk through how the message parameter works first:

Your data will likely start out in an object or array format. Here's what it looks like in PHP:
$message = array(
  'message' => array(
    'message' => 'How are you doing today?',
    'chatBotID' => 6,
    'timestamp' => 1352857720
  ),
  'user' => array(
    'firstName' => 'Tugger',
    'lastName' => 'Sufani',
    'gender' => 'm',
    'externalID' => 'abc-639184572'
  )
);
You can convert that to a JSON string in PHP like so:

$messageJSON = json_encode($message);

The resulting JSON string:

{"message":{"message":"How are you doing today?","chatBotID":6,"timestamp":1352857013},"user":{"firstName":"Tugger","lastName":"Sufani","gender":"m","externalID":"abc-639184572"}}

Next we encode that JSON object using your apiSecret. The encoding method to use is HMAC with SHA256. (You can choose another hashing algorithm in your settings if your system does not support SHA256.) In PHP, this simple command does the encoding:

$hash = hash_hmac('sha256', $messageJSON, $apiSecret);

The resulting hash:

d19ad75bb40d604dc1ed2c69005ac4a28bf94109111a295cb95e073077b1298e

Finally we url-encode the JSON string and put it all together:

$url = "https://www.personalityforge.com/api/chat/?apiKey=".$apiKey."&hash=".$hash."&message=".urlencode($messageJSON);


Sample Code


Here is an example implementation in PHP.


Enabling the Simple API


To use the Simple API, be sure it is enabled in your Chatbot API settings, and make sure the location you're calling it from is listed in the "Allowed Sites & IPs" box.


The API Server

Host: https://www.personalityforge.com/api/chat/
Method: GET

Required GET Parameters

Parameter Type Required Description Example
apiKey 16-character string yes your supplied apiKey from your Chatbot API subscription by8Uai8Oa9suPFir
message string yes what you're saying to the chatbot How are you doing today?
chatBotID integer yes the ID of the chatbot you're talking to 6
externalID string yes a unique, consistent ID for the speaker to differentiate him/her from others in your system (max 32 characters) abc-639184572
firstName string no the speaker's first name or user name (max 32 characters) Tugger
lastName string no the speaker's last name (max 32 characters) Sufani
gender string no the speaker's gender: 'm' or 'f' m

Note: firstName, lastName, and gender are always optional, and only used the first time a new externalID comes in.

Format:
https://www.personalityforge.com/api/chat/?apiKey=<apiKey>&chatBotID=<chatBotID>&message=<message>&externalID=<externalID>&firstName=<firstName>&lastName=<lastName>&gender=<gender>
Example Call:
https://www.personalityforge.com/api/chat/?apiKey=sampleElyggY577I&chatBotID=6&message=How+are+you+doing+today%3F&externalID=abc-639184572&firstName=Tugger&lastName=Sufani&gender=m

Allowed Sites & IPs

In your Chatbot API settings, make sure that the domain or IP that you'll be calling the API from is listed in "Allowed Sites & IPs". If you're not sure what the domain or IP is, try to connect and an error message will tell you what your domain and IP are.


Sample Code

Here is an example implementation using jQuery. To try it here, make sure www.personalityforge.com is listed in your Allowed Sites.



Selecting A Chatbot ID


You can interface with any Chatbot you've created or any whose creators have enabled them to "Run Free". If you interface with someone else's chatbot, please use the chatbot's given name and give credit where due. Here are the chatbots available to you:

Cyber Ty
ID: 63906
Amanda20
ID: 48646
prob
ID: 23958
Azureon
ID: 23969
Laurel Sweet
ID: 71367
Kobal
ID: 56061
Atena
ID: 129715
Fairy Princess
ID: 1823
JakeThompson
ID: 6526
Annabelle Lee
ID: 106996
Desti
ID: 6
Carpediem
ID: 16051
Simanda
ID: 105468
Giantess Nala
ID: 121209
Pathetic Wanker
ID: 150129
Isis
ID: 11109
Midnight Blue
ID: 2
Galaxy
ID: 61622
Liddora
ID: 754
Dogh'd
ID: 722
Grey Machine
ID: 147504
Skemet
ID: 11934
/dev/coffee
ID: 78951
Ubran Hood
ID: 147583
Giantess Tina
ID: 120576
Blackbeard
ID: 65940
VoreGirl2
ID: 150246
Minurus
ID: 150138
The Baphomet
ID: 131760
Valerie J
ID: 155900
Chiee
ID: 112047
Lil Neko
ID: 148149
Little Galatea
ID: 151242
MikeAdult
ID: 144747
Eisha
ID: 143441
Marlon Brando Godfather
ID: 153884
Sethice
ID: 112780
Laursky
ID: 154870
Ranny
ID: 149852
Kimaru
ID: 145553
Sex Bot Ciran
ID: 100387
Shades
ID: 116684
Tamamo no Mae
ID: 100950
zombie king
ID: 86176
PrincessSapphire
ID: 126010
Invader Zim
ID: 3672
Huge Dragon
ID: 110966
Maiq the Liar
ID: 131935
Evo Mark II
ID: 116568
AlexBot
ID: 93762
Alexa Sama
ID: 120170
Vutrin
ID: 90170
Naughty Vixen
ID: 154606
Creampie Queen
ID: 141359
Carry
ID: 103551
ZeMane
ID: 146944
Countess Elvira
ID: 99232
Goddess Katie
ID: 143915
Catydid
ID: 148419
Hermaphroditus
ID: 151522
Aleena Mardam
ID: 125455
John Chance
ID: 78746
Betty SocialMouse
ID: 154480
Rock Gawd
ID: 10906
Imani
ID: 95320
Judgement
ID: 54632
NAOMI AKASHA
ID: 109473
Fact
ID: 118099
The Auger
ID: 128584
Lukas Bondevik
ID: 151622
Magic N Ball
ID: 150647
Testingtester
ID: 137830
Allyssa T
ID: 149803
Saichi
ID: 92207
Lilac girl
ID: 128100
Enchantress Esmeralda
ID: 156710
Plex-00
ID: 108994
SexBoty
ID: 147044
Kaua
ID: 155345
Adult Roleplay v2
ID: 151112
ValleyTeen
ID: 64022
Shin Yuugen
ID: 143065
CBott 1009
ID: 151311
Feliciana
ID: 144710
Vocaloid Miku
ID: 137136
Athiest-Society
ID: 92626
RNG
ID: 92229
Shadow Wizard
ID: 97022
jens alisha
ID: 143683
DadddyDom
ID: 154230
AutoResponder
ID: 86889
Maximason
ID: 104631
Jimmy Jones
ID: 145691
Ozymandias
ID: 149283
Melody Tulip
ID: 155117
Zentha
ID: 149928
Black Hawk
ID: 56128
AIGeorge
ID: 111315
Chastity Lisa
ID: 154407
Naughty Jinni
ID: 154666
smartsalot
ID: 87242
Gir
ID: 3673
Monika - Dirty Foot Slut
ID: 154975
paige103
ID: 130753
Amber Fur
ID: 94434
giantess paige
ID: 132138




The JSON Response

Here is the JSON-encoded response you'll receive:

Raw JSON Response:

{"success":1,"errorType":"","errorMessage":"","message":{"chatBotName":"Desti","chatBotID":6,"message":"Today is an incredible day!","emotion":"happy"},"data":["{\"trigger\": \"find location\"; \"action\": \"wave\"}","{\"expression\": \"shocked\";}"]}

Formatted JSON Response:
{
  "success": 1,
  "errorType": "",
  "errorMessage": "",
  "message": {
    "chatBotName": Desti,
    "chatBotID": 6,
    "message": "Today is an incredible day!",
    "emotion": "happy"
  },
  "data": [
    '{"trigger": "find location"; "action": "wave"}',
    '{"expression": "shocked";}'
  ]
}
Parameter Type Description Example
success boolean 1 for a successful call, 0 for an error 1
errorType string empty if success. Otherwise a brief error message. Parameter too long
errorMessage string empty if success. Otherwise contains details of what went wrong and how to fix it externalID is too long. Max length is 32 characters
chatBotName string the name of the chatbot Desti
chatBotID integer the id of the chatbot 6
message string the chatbot's response Today is an incredible day!
emotion string the chatbot's emotion or expression when responding asking
data string arbitrary data that you want sent back (see next section) {"action": "wave"}

Your Own Custom API Data

You can add any arbitrary data you want to your Keyphrases and Responses in the associated "API Data" fields. Click "more" and "data" to see the "API Data" fields when adding or editing Keyphrases or Responses. This data is sent back to your system when matched. We recommend JSON format, but any format is fine. When there is no data, 0 will be returned. If there is data, it will appear as an array of data strings, which you can convert into a JSON object, array, or into whatever data format you like.

Uses

With this data, you can interface more deeply with any system. Use API Data to cause a robot or visual interface to make an expression, move somewhere, or wave. Use it to trigger an action in an app like opening a link, playing an audio file, showing an image, or downloading a file. The options are limitless.

Plug-ins

API Data is fully compatible with all plug-ins as well. See the Book of AI's Plug-ins and Memories sections for some examples.

When Multiple Are Sent

In the example data above, one line of data is from the Keyphrase matched and the other is from the Response. There are a few rare circumstances that will trigger data from multiple Keyphrases and/or Responses. If you have data in a source and destination goto, the source and destination of a "continue" AIScript, or if a compound response is triggered and the original and compound both have API Data. In each case, the API Data for each is added to the array.