API Endpoints

GET /bot/{app_id}

List of bots

Implementation Notes

Retrieve a list of your application’s bots. Response returns JSON object with info for each bot.

Returns a 401 error code for invalid app_ID or user_key, or if applicable, invalid referrer.

curl -v  -X GET 'https://api.pandorabots.com/bot/APP_ID?user_key=USER_KEY'

Parameters

PUT /bot/{app_id}/{botname}

Create a bot

Implementation Notes

Create a new instance of a bot on the Pandorabots server.

If there is already a bot under the same app_id and botname, a 409 error is returned. Invalid botname will return a 400 error.

Creating more bots than your plan allows or using an invalid app_id or user_key (or if applicable referrer filter) returns a 401 error.

curl -v  -X PUT 'https://api.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'

Parameters

DELETE /bot/{app_id}/{botname}

Delete a bot

Implementation Notes

Delete a bot on the Pandorabots server.

Deleting a bot that does not exist returns a 412 error. Invalid botname will return a 400 error. Invalid app_id, user_key, or referrer filter will return a 401 error.

curl -v  -X DELETE 'https://api.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'

Parameters

GET /bot/{app_id}/{botname}

List of bot files

Implementation Notes

Retrieve a list of a bot’s files. Returns a JSON object with each bot file associated with bot specified.

Returns a 404 error code for bot not found. Returns a 401 error code for invalid app_ID, user_key, or referrer filter.

Thereturn=zipoption may not behave as expected using Active Docs 1.2

curl -v  -X GET 'https://api.pandorabots.com/bot/APP_ID/BOTNAME?user_key=USER_KEY'

Parameters

PUT /bot/{app_id}/{botname}/{file-kind}/{filename}

Upload a bot file (AIML, set, substitution, map)

Implementation Notes

Upload bot personality files to your bot. Files must be named with only lowercase letters and numbers with one of the following extensions:

AIML: Extension - .aiml, file-kind - file

Sets: Extension - .set, file-kind - set

Maps: Extension - .map, file-kind - map

Substitutions: Extension - .substitution, file-kind - substitution

The system will overwrite existing files with the file being uploaded.

If the request is malformed because the file name is invalid or malformed JSON for non-AIML files, a 400 error is returned. For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned.

If Active Doc spec is not working with this API, please use the following curl command examples:

curl -v -X PUT 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/file/foobot.aiml?user_key=USER_KEY'
  --data-binary @/home/foo/foobot.aiml

curl -v -X PUT 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/set/colors?user_key=USER_KEY'
  --data-binary @/home/foo/colors.set

Parameters

PUT /bot/{app_id}/{botname}/{file-kind}

Upload a bot file (pdefaults, properties)

Implementation Notes

Upload bot personality files to your bot. Files must be named with only lowercase letters and numbers with one of the following extensions:

Properties: Extension - .properties, file-kind - properties, No filename required in path

Predicate defaults: Extension - .pdefaults, file-kind - pdefaults, No filename required in path

The system will overwrite existing files with the file being uploaded.

For malformed JSON in non-AIML files, a 400 error is returned. For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned.

If Active Doc spec is not working with this API, please use the following curl command examples:

curl -v -X PUT 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/properties?user_key=USER_KEY'
  --data-binary @/home/foo/foobot.properties

Parameters

DELETE /bot/{app_id}/{botname}/{file-kind}/{filename}

Delete a bot file (AIML, set, map, substitution)

Implementation Notes

Delete an AIML, set, map or substitution bot file

For malformed file-kind, a 404 error is returned. For invalid file or botname, a 412 error is returned.

curl -v -X DELETE 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND/FILENAME?user_key=USER_KEY'

Parameters

DELETE /bot/{app_id}/{botname}/{file-kind}

Delete a bot file (pdefaults, properties)

Implementation Notes

Delete pdefaults or properties bot file.

For malformed file-kind, a 404 error is returned. For invalid botname, a 412 error is returned.

curl -v -X DELETE 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND?user_key=USER_KEY'

Parameters

GET /bot/{app_id}/{botname}/{file-kind}/{filename}

Retrieve a bot file (AIML, set, map, substitution)

Implementation Notes

Retrieve an AIML, set, map or substitution bot file.

For malformed file-kind, a 404 error is returned. For invalid filename or botname, a 400 error is returned. For unknown bot or file, a 412 error is returned.

curl -v -X GET 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND/FILENAME?user_key=USER_KEY'

Parameters

GET /bot/{app_id}/{botname}/{file-kind}

Retrieve a bot file (pdefaults, properties)

Implementation Notes

Retrieve pdefaults or properties bot file.

For malformed file-kind, a 404 error is returned. For invalid botname, a 400 error is returned. For unknown bot or file, a 412 error is returned.

curl -v -X GET 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/FILE-KIND?user_key=USER_KEY'

Parameters

GET /bot/{app_id}/{botname}/verify

Compile a bot

Implementation Notes

A bot personality is created by uploading AIML and other file types to Pandorabots. The files must compile correctly in order for the bot to run. By issuing a call to this API, Pandorabots will compile the bot, updating any changes that have been made to the files.

Compiling the bot makes its most recent version available for talk. A 400 error means that we were unable to compile your bot (you should check your files for syntax issues) or the botname was not found.

You can see any thrown errors in the results field of the returned JSON object:

curl -v  -X GET 'https://api.pandorabots.com/bot/APP_ID/BOTNAME/verify?user_key=USER_KEY'

Parameters

POST /talk

Talk to a bot (Public Botkey)

Implementation Notes

Start or continue a conversation with the bot using the Talk API with your public botkey. Pandorabots will return a new session ID if not included in the call. Use the session ID returned to group interactions together to view in your bot’s Logs on the Dashboard. We recommend using the first session ID returned in subsequent API calls during an active conversation by your end-user. (NOTE: our system considers 30 minutes of idleness as the end of an active conversation)

If you do not provide a client name, Pandorabots will assume client is your application and all predicates and variable information will be associated with your application. Predicates assigned to clientname only persist during an active conversation and are flushed after a certain idle period.

NOTE: If you send multiple sentences to your bot in a single input, the API response will include multiple bot responses.

See Anonymous Talk API for details on how you can maintain persistent predicates for your end-users.

Malformed requests such as exceeding size of input or invalid clientname returns 400 error code. Error code 412 is returned if the bot is not compiled or does not exist. Error code 429 is returned if your application has reached maximum plan API call limit. If you receive intermittent 404 error messages, please contact support@pandorabots.com, as this could be load balancing issue we need to resolve.

The response array will contain one element (response) for each sentence you input to the bot. You can configure which characters delimit a new sentence in the input by modifying the sentence-splitters property in your bot’s property file.

curl -v  -X POST 'https://api.pandorabots.com/talk?botkey=BOTKEY&input=INPUT'

Parameters

POST /atalk

Anonymous Talk (Public Botkey)

Implementation Notes

Start a conversation with the bot using the Anonymous Talk API. This method will allow you to request creation of an end-user client_name that can maintain persistent predicates per end-user talking to your bot.

If client_name is NOT sent in the request, then Pandorabots will create a end-user client_name and return it in the response. Similar to the Talk to Bot API, Pandorabots will also return a new session ID if not included in the call. Use the session ID returned to group interactions together to view in your bot’s Log on the Dashboard. We recommend using the first session ID returned in subsequent API calls during an active conversation by your end-user. (NOTE: our system considers 30 minutes of idleness as the end of an active conversation)

In addition to bot response and session ID, the HTTP response will include a new end-user client_name in the following format:
aiaas-XXX-user-nnnn, where XXX is your app_ID and nnnn is numeric starting with 0000 and incrementing after each request.

Malformed requests such as exceeding size of input or unknown end-user client_name returns 400 error code. Error code 412 is returned if the bot is not compiled or does not exist. Error code 429 is returned if your application has reached maximum plan API call limit.

curl -v  -X POST 'https://api.pandorabots.com/atalk/APP_ID/BOTNAME?user_key=USER_KEY&input=INPUT'

Parameters