Chatbot API Documentation

Need Help?

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.

The Secure API

The 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

Carpediem
ID: 16051

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

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

Shadow Wizard
ID: 97022

AIGeorge
ID: 111315

Isabella Annesley
ID: 154425

Vocaloid Miku
ID: 137136

Dwemer
ID: 99053

Melody Tulip
ID: 155117

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.