Frequently Asked Questions

  • How does the free trial work?
  • I've just activated my account, now what?
  • How do I get my application approved?
  • What is an Application ID and where can I find mine?
  • What is an API alert?
  • How can I upgrade/downgrade my application plan?
  • How do I add another application plan?
  • How do I cancel my application plan?
  • How do I cancel my account?
  • What happens when I sign up for an application plan in the middle of the month?
  • When will Pandorabots charge my credit card?
  • Why doesn't Select a Plan on the Developer Portal home page work?
  • Why am I unable to upload a file using a file selector with Active Docs?
  • What hostname do I use if using pb-CLI or other tutorials?
  • Why am I getting errors trying to talk to my bot that I created on the Playground?
  • What happened to my botid?
  • What open source libraries do you offer?
  • What are “Interactions”?
  • What can I do if I've reached my plan limit?
  • What about other APIs?
  • What are the formats and extensions for my files to be uploaded?
  • Why am I unable to make API calls?
  • What can I do if I get a compile error?
  • What is a Bad/missing Referrer error?
  • Why doesn't my bot respond based on new AIML files I've uploaded?
  • Can I license the personality bot Mitsuku?
  • How does the free trial work?

    To allow you maximum flexibility in testing the API, we offer a free, ten day trial on the Developer Plan. This includes up to 10,000 talk interactions per month, with no limits on other types of API calls. We will not charge your credit card on file until the end of the ten day period. If you opt not to subscribe during that time period please cancel your application to avoid any charges. Note that the free trial only applies to the first application plan. Any subsquent plans you add to your account will be charged according to our policies.

    I’ve just activated my account, now what?

    You must enter in your credit card information before we can approve your application plan.

    Once your application has been approved, you will receive an Application Approval email with an application activation link. Once you activate your application, you should be able to access both your user_key and Pandorabots account details to start using the API.

    How do I get my application approved?

    You must enter your credit card details before we can approve your application. Please go to the Account page and click the Credit Card Details tab to enter in your credit card. You may also notice that clicking on Apps on the nav bar redirects you to the Credit Card Details page.

    Once a verified credit card has been entered, we will approve your application within one business day. You will receive an email notification of application approval. Click the activation link in the email to activate your application.

    What is an Application ID and where can I find mine?

    To access the API you need both a user key and application ID for authentication. You can find your application ID (it is typically a string of numbers) on the application detail page. This identifier is unique for each application plan and is generated when you activate your application.

    What is an API alert?

    When your application gets close to or exceeds a plan limitation you will be alerted via email and it will be included as an alert on the Developer Portal. To see any relevant alerts, click on the API Alert (Show) link on your application's detail page.

    How can I upgrade/downgrade my application plan?

    On your Application detail page, click on the Review/Change link to review your current plan and select your new plan. Note that the new plan price will be prorated for the month as a line item on your monthly invoice, based on the time you selected the new plan. A plan change will occur immediately.

    Please refer to our Terms of Service, section 2.d for details. If you don't want to be charged for a paid plan for the following month, make sure to downgrade or cancel your plan prior to the end of the current month.

    How do I add another application plan?

    You can add another application plan to your account by request. Please message us using the Developer Portal message feature and provide the name you want to use for your application, and the application plan you'd like to sign up for.

    How do I cancel my application plan?

    Please message us using the Developer Portal message feature and provide the application name and current plan name to cancel. We must receive a cancellation notice in writing. We will suspend your application and finalize any pending invoices within two business days.

    How do I cancel my account?

    Please message us using the Developer Portal message feature and provide your account username. We must receive a cancellation notice in writing. We will suspend all applications and finalize any pending invoices within two business days. Please make sure to download any invoices and/or bot files prior to requesting account cancellation. Once we have canceled your account, you will not have access to them anymore, and we cannot provide them.

    What happens when I sign up for an application plan in the middle of the month?

    At sign up, you receive your full monthly allowance for the remainder of the month at a prorated price. However, if you end up using your bot interactions allowance in just a of couple days, you may want to consider upgrading your plan.

    When will Pandorabots charge my credit card?

    You will be notified via email (you can also see these messages on the developer portal message box) when your invoice has been finalized for the month for charging. We will charge your credit card on the due date listed on your invoice. For plan changes or initial sign up, this is typically 1-3 business days. For general monthly subscription fees, invoices will be charged on the 7th of the month. For free trial, see this FAQ answer.

    What open source libraries do you offer?

    Base AIML Content & Reusable Libraries - we provide initial bot files to get you started with your bot development.
    SDKs - we provide software development kits to get you started on your application development.

    What are “Interactions”?

    One interaction is equal to one input to the bot and one output from the bot (otherwise known as the /talk or /atalk APIs). Other types of API calls are not limited at this time.

    What can I do if I've reached my plan limit?

    A small overage fee will be charged per call (to view overage charge costs, go to your Application details page, click on the Review link next to your plan name).

    If you find that you are reaching your limits often, we recommend you upgrade your plan.

    To allow you maximum flexibility in developing your bot, only bot interactions (talk) API calls are limited at this time.

    Why doesn't Select a Plan on the Developer Portal home page work?

    Plan selection from the home page is disabled if you are logged in. If you want to create a new account, sign out of your current account and try again. If you want to add a new application plan to your current account, see answer above.

    Why am I unable to upload a file using a file selector with Active Docs?

    Active Docs is an implementation of Swagger.js, a tool for creating API documentation and HTTP clients. The current implementation of Swagger.js has a bug which causes uploading files selected on your local machine to be corrupted. There is a temporary workaround to allow you to upload AIML content into a file created (or overwritten) on our AIaaS platform.

    If you would like to upload files, please use the curl examples provided in Active Docs, try out the workaround solution using the Active Docs 1.2 interface, or a REST client such as Postman. If you like command line interfaces, please also checkout our own CLI

    What hostname do I use if using pb-CLI or other tutorials?

    Our open source command line tool or other tutorials sometime reference a "hostname". For this platform, it is aiaas.pandorabots.com

    Why am I getting errors trying to talk to my bot that I created on the Playground?

    The Playground is distinct and separate platform from the AIaaS Pandorabots API. It was designed as a IDE for learning AIML and chatbot development, and not as a means of deploying your bot to a website or application. This means the bot you have created is not actually being accessed by the REST client.

    If you want to deploy the bot that you've created on the Playground, you can download the bot files from the Files tab, and then go through the basic steps of rebuilding the bot on the API server:

    1) Create a bot
    2) Upload the files downloaded from the Playground
    3) Compile the bot

    The following tutorials may also be useful:

    What happened to my botid? What is an Application ID or app_id and how is it different than my username?

    The previous Pandorabots platform used a string called botid as a unique identifier for your bot. Our new developer service has replaced this concept, instead identifying your bot by including your Application ID and the botname in the path for each API request. The app_id is unique to your application, and is used to help reference all of the bots tied to that application.

    You can also use the app_id/botname pattern to call another bot using sraix.

    The Playground has a similar way of identifying a bot, however, the username of the person creating the bot is used instead of an app_id. This is distinct from your username on the Developer Portal, which is never used to identify a bot or to make API calls.

    What about other APIs?

    This is an initial offering. We will be providing additional APIs in future releases.

    What are the formats and extensions for my files to be uploaded?

    AIML

    • Format: valid AIML 2.0
    • Extension: .aiml

    Sets

    • Format: JSON array of strings
    • Extension: .set

    Maps

    • Format: JSON array of arrays, where each key-value pair is an inner array.
    • Extension: .map

    Substitutions

    • Format: JSON array of arrays, where each key-value pair is an inner array.
    • Extension: .substitution

    Predicate Defaults

    • Format: JSON array of arrays, where each key-value pair is an inner array.
    • Extension: .pdefaults

    Properties

    • Format: JSON array of arrays, where each key-value pair is an inner array.
    • Extension: .properties

    Note: for properties and predicate defaults, the file name must be the name of your bot.

    Why am I unable to make API calls?

    We have reserved 15:00 - 16:00 UTC as our maintenence window. You may experience a disruption of service during this time. We also perform backups daily during this time period. You can check on server alerts on the Applications page or the Stats page.

    Any invalid app_ID, user_key or referrer filter will result in a 401 Unauthorized error response.

    What can I do if I get a compile error?

    If you create, upload or edit an AIML file with bad AIML, the compile a bot request will return a compile error. The position number returned corresponds to the character position in the file where the compiler encountered the error. You must fix the error, upload the file(s) again and re-compile. Use text editors like Vim, Emacs, Notepad++, etc. which allow you to jump to a character position in your file causing the compile error.

    What is a Bad/missing Referrer error?

    If you add a domain or IP referrer filter to protect your Bot credentials, you may get this error if attempting to access your bot from the wrong domain or IP address. This can be configured on the Application details page on the Developer Portal, and only allows API requests from the referrers specified. If you've set this up but are using our API through other means, such as Active Docs, or a REST client on your local machine, and not from your webpage, you will likely see this error. If you want to use Active Docs, make sure to add developer.pandorabots.com in your list of referrer filters. A max of 5 are allowed.

    Other typical reasons for receiving this error -- referrer filter value entered is incorrect, or your application is not actually sending a Referer in the HTTP header of the API call.

    Why doesn't my bot respond based on new AIML files I've uploaded?

    If you've uploaded files to your newly created bot and immediately tried to talk to your bot, you might have noticed receiving an error response that your bot is uncompiled. If you upload additional files to your bot after having compiled it at least once, then the bot in memory (if active) will be the most recently compiled version. It will not respond with any new AIML until you compile your bot again.

    If your uncompiled bot is idle for some time, the most recent compiled version will be flushed from server memory and the next time you talk to your bot you will receive an error indicating your bot is uncompiled.

    You can use the List of Bots API to receive compiled status of your bots. You can also use the recent parameter in the Talk to Bot API to request loading of the most recently compiled bot (in the case your bot is uncompiled). Another reason your bot might become uncompiled is if you have learnf elements in your AIML. We do not recommend using this AIML tag as it creates/updates a system file called pand_learn.aiml which includes learned categories. This automatically marks your bot as uncompiled similar to if you had uploaded a bot file. Unless your application is monitoring your bot status and can initiate a compile command, this is not AIML code we recommend. Even so, we also don't recommend automatic compilation without reviewing learned categories first since these categories would be available to all end-users of your bot.

    Another reason why your bot is not responding in the manner you are expecting may be due to duplicate categories. When your bot is compiled, the order of your file upload determines which category will be processed if you have duplicate categories. The last uploaded file has precedence. For example, you have a UDC (ultimate default category) where the matched pattern is just a wildcard (*) in a pand_initial.aiml file. If you add duplicate UDC category in another AIML file and upload and compile your bot, the template in the 2nd file uploaded will be returned as bot response. This is also likely the reason why two bots that you think have identical files are behaving differently. To find out the load order of your AIML files, use the List of Bot Files API for your bot.

    Even if the category you were expected to match is in a file last uploaded, it is possible that higher priority wildcards may also be matching a pattern that you aren't expected, or if topics are being used, the pattern isn't matching within the topic (or that) elements.

    Finally, unexpected bot responses may be due to normalization. The Pandorabots platform performs pre-processing using the normal.substitution file to substitute end-user input. Normalization also applies to THAT tags. Make sure your pattern or that tags are normalized for pattern-matching if you are using normal.substitution file in your bot.

    We recommend you use the Debug a Bot Conversation parameters to figure out why your bot is behaving in unexpected ways, such as extra, or trace.

    Can I license the personality bot Mitsuku?

    Licensing of Mitsuku chatbot content as an unmodified module is available, and can be integrated with your own bot(s) via sraix. Note that setup for custom bots used by your application with Mitsuku, or modifications to Mitsuku, requires engineering support. Interested parties should call 415.343.5894 or email info@pandorabots.com to discuss any specific requirements and monthly licensing fees.