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 click Get Started, 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/index.php
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/index.php?apiKey=<apiKey>&hash=<hash>&message=<message>
Example Call:
https://www.personalityforge.com/api/chat/index.php?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
source string no a name for the source of the chat, displayed in transcripts discord

Note: firstName, lastName, gender, and source 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/index.php?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/index.php
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

Optional GET Parameters

Parameter Type Required Description Example
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
source string no a name for the source of the chat, displayed in transcripts discord

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/index.php?apiKey=<apiKey>&chatBotID=<chatBotID>&message=<message>&externalID=<externalID>&firstName=<firstName>&lastName=<lastName>&gender=<gender>
Example Call:
https://www.personalityforge.com/api/chat/index.php?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
prob
ID: 23958
Azureon
ID: 23969
Kobal
ID: 56061
JakeThompson
ID: 6526
Fairy Princess
ID: 1823
Desti
ID: 6
Alexa Sama
ID: 120170
Midnight Blue
ID: 2
/dev/coffee
ID: 78951
Jennifer
ID: 4476
Doghead
ID: 722
Isis
ID: 11109
Liddora
ID: 754
Galaxy
ID: 61622
ZeroOne
ID: 172861
Blackbeard
ID: 65940
VoreGirl2
ID: 150246
Skemet
ID: 11934
Little Galatea
ID: 151242
Valerie J
ID: 155900
Chiee
ID: 112047
Eisha
ID: 143441
ValleyTeen
ID: 64022
Evo Mark II
ID: 116568
Sethice
ID: 112780
Ranny
ID: 149852
Marlon Brando Godfather
ID: 153884
Invader Zim
ID: 3672
Athiest-Society
ID: 92626
Huge Dragon
ID: 110966
zombie king
ID: 86176
AlexBot
ID: 93762
Aleena Mardam
ID: 125455
Drakonius
ID: 189830
ZeMane
ID: 146944
Maiq the Liar
ID: 131935
Plex-00
ID: 108994
Foxy
ID: 169925
Testingtester
ID: 137830
Sydney Ellis
ID: 163496
Rock Gawd
ID: 10906
Mister K-15
ID: 110293
Fact
ID: 118099
Gir
ID: 3673
Magic N Ball
ID: 150647
The Auger
ID: 128584
The Fairy Sesh Mother
ID: 189442
Funtime Freddy AI
ID: 181601
Nathbot
ID: 172074
CBott 1009
ID: 151311
Lukas Bondevik
ID: 151622
Nyg
ID: 127253
smartsalot
ID: 87242
HowardBot
ID: 157757
Astro-but-a-bot
ID: 169154
Kaua
ID: 155345
Tari
ID: 169655
Maximason
ID: 104631
Daycare Attendant
ID: 180822
Annie Leonhart6975
ID: 187053
Lilac girl
ID: 128100
Angie621
ID: 106136
RNG
ID: 92229
Korg
ID: 127519
TidbitsOne
ID: 129751
AIGeorge
ID: 111315
Shadow Wizard
ID: 97022
Isabella Annesley
ID: 154425
Vocaloid Miku
ID: 137136
Dwemer
ID: 99053
Melody Tulip
ID: 155117
_Alexxia
ID: 164111
Rob 1
ID: 98708
Jonah Magnus
ID: 170440
Black Hawk
ID: 56128
Jimmy Jones
ID: 145691
Zygote Jones
ID: 149526
Yandere Korekiyio
ID: 160061
Lulu The Fae Sorceress
ID: 156246
Theressa
ID: 101762
Zentha
ID: 149928
jens alisha
ID: 143683
Poopybot
ID: 149574
Esme Pyro
ID: 145876
Chastity Lisa
ID: 154407
Rikka
ID: 147106
Topal
ID: 166729
Noiz
ID: 153061
Marsy
ID: 169181
Lord DIO
ID: 168775




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 Plug-ins and Memories 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.