Token Upselling
Overview
The Token Upselling feature is a notification banner that you can integrate within your OpenAI AddOn. This notification banner informs your application end users of when their available tokens are running low and when they are completely out. Both notification banners display an option for the end user to purchase additional tokens. These notification banners support a healthy token management workflow, and help avoid any potential interruptions in the end user’s workflow through transparently informing them about their available tokens.
The following notification banner will appear to an end user when their tokens are running low. “Running low” is defined as when an end user has a remaining token balance equal to or less than 20 percent of their initial token count.
Note: You can edit the notification banner trigger to a remaining percentage other than the default 20 percent. Reference the Customize Notification Trigger to learn more about how to change this percentage.
The following notification will appear to an end user when they no longer have any remaining tokens. This is triggered when tokenCounter
is greater than or equal to tokensAvailable
. For reference, tokenCounter
refers to the amount of tokens an end user has used since their initial token balance.
The text inside the banner notifications is customizable. Reference the Customize Notification Banner Text section to learn more about customizing the notification banner text within your application.
Read this article to learn more about configuring token upselling within your host application.
Prerequisites
Prior to getting started with the configuration, ensure you have the following:
Superpower or Enterprise plan
An OpenAI AddOn within your application
Configuration Steps
This section discusses the configuration steps you need to follow to integrate the Token Upselling feature into your web application.
To integrate the Token Upselling feature into your application, take the following steps:
Enable Token Upselling
To enable Token Upselling, you need to pass your configuration code to the AI Integration AddOn within the Developer Console.
When you pass your code, ensure you define the following variables:
tokenCounter
: Counts how many tokens an end user has used in totaltokensAvailable
: Displays how many remaining tokens an end user hadisUpsellEnabled
: A boolean that confirms whether or not the Token Upsell feature is enabled
Note: If you do not provide tokenCounter
and tokensAvailable
, the end user will have unlimited access to the AI functionality within your application.
The purpose of the following code is to initialize and track the number of tokens available and the number of tokens used. It also checks if the upsell feature is enabled.
Limit Usage
When you define tokensAvailable
and tokenCounter,
you limit the end user’s token usage.
isPromptDisabled
automatically disables the ai-integration
when the number of tokens used by an end user (tokenCounter
) is greater than or equal to the number of tokens available (tokensAvailable
).
The following code displays an example of the AddOn AI Integration configuration code.
onInfo Callback
The purpose of the onInfo
callback in the following code snippet is to handle information messages related to the usage of the ai-integration
AddOn. It checks if the code of the infoMessage
is 1000 and if the handle is ai-integration
. If both conditions are met, it updates the AddOn settings and reloads the configuration.
The code works by:
Retrieving the handle from the
infoMessage
.Checking if the handle is
ai-integration
.If the handle is
ai-integration
, retrieve thetotalTokens
from theinfoMessage
.Updating the
tokenCounter
by adding thetotalTokens
.Creating a
newConfig
object with the updatedtokenCounter
and other settings.Reloading the configuration by calling
bee.loadConfig(newConfig)
.
Trigger the Handler Function
The purpose of the "upsell" action is to trigger the handler function, which, based on the following code sample, increases the number of tokens available by 1000 and returns an object with updated settings for the ai-integration
add-on.
The handler function is a function that is executed when the upsell
action is triggered. It has two parameters: resolve
and reject
. The resolve
parameter is a function that is called when the handler function successfully completes its task, and the reject
parameter is a function that is called when the handler function encounters an error or fails to complete its task.
Content Dialog Config
Configure the content dialog and upgrade path to enable the token upselling notification banner. This configuration is important because it defines the steps the end user takes to purchase more tokens.
The following code displays an example of how to configure the content dialog.
Configure Resolve
Ensure you define how your host application will resolve the upsell feature. You can do this by returning the configuration on how to handle the content dialog within the addOn configuration. The code provided in the previous step displays an example of this.
Settings, Data Types, and Defaults
The following table shows a list of what your web application can pass to the Beefree SDK in the addOn configuration of ai-integration.
Settings | Data Types | Defaults |
---|---|---|
| string | Default is “tokens”. |
| boolean | Default is false. If changed to true, it can override tokens balance and disable the prompt. |
| boolean | Default is false. If changed to true, it enables the upsell. |
| number | Tokens used, if not provided in the configuration, the user has unlimited tokens. |
| number | Tokens available to the end user. If not provided in the configuration, the user has unlimited tokens. |
| number | Default is 80 (%) of tokens available. |
| boolean | Default is false. |
| boolean | Default is false. |
Disable the Regenerate Button
The regenerate button appears after an end user submits their first prompt to OpenAI through the OpenAI AddOn. This button enables the end user to resubmit the same prompt to OpenAI in order to receive a newly generated response. This is helpful when an end user may want a variety of prompt responses to select from. However, each regenerated response incurs additional token usage and costs. This section will discuss how to disable the regenerate button in the event you would like to remove it from your application’s user interface.
Image 1.0 shows the regenerate button as an example at the bottom of an AI generated prompt response.
To achieve this, configure the isRegenerateEnabled setting to false.
The following example displays the sample code for the regenerate button.
Customize Notification Banner Trigger
The default trigger for the upsell notification banner is when an end user has used 80% of their initial tokens, and only has 20% of their initial tokens available. These percentages are customizable based on your use case. You can edit the notification banner to trigger at any percentage of the initial token count that best works for your host application.
Take the following steps to customize your notification banner trigger:
Pass
upsellTrigger
to the initial AddOn configuration
Customize Notification Banner Text
This section discusses how you can customize the notification banner text. For reference, the notification banner has the following default message:
“You’re out tokens. Purchase more”
To edit the notification banner text, take the following steps:
Identify the Template: Locate the notification template you want to customize. In this example, the template is specified with a custom language ID:
`bee-common-component-ai.no-token-message`
.
Understand the Template: Read and understand the original template text, which is "You're out of {tokenLabel}. {ctaLabel} to continue." This template includes two placeholders:
{tokenLabel}
and{ctaLabel}
.
Understand the Default Behavior: Understand that by default, the template includes a Call-to-Action (CTA) button represented by the
`{ctaLabel}`
placeholder.Determine Your Customization Needs: Decide what changes you want to make to the template.
Options include:
Removing the CTA button entirely.
Changing the CTA button label.
Reordering the text within the template.
Create a Custom Language Entry: If you want to customize the template, create a custom language entry. This entry should have the same custom language ID:
`bee-common-component-ai.no-token-message`
.
Modify the Template: Customize the template in your custom language entry according to your needs. For example:
To remove the CTA: "You're out of
{tokenLabel}
."To change the CTA label: "You're out of
{tokenLabel}
. Click here to refill."
Implement the Custom Language Entry: In your web application code, replace the default template with the custom language entry you've created. Ensure that you use the correct custom language ID when accessing the text.
Configure Image Tokens
You can also configure the Token Upselling feature to guide your application's end user to purchase images. Purchasing additional image tokens allows your end users to continue using features such as Alt Text Generation with AI and Bulk Alt Text Generation.
The following code shows an example of a Token Upselling configuration for both text and image tokens. Purchasing text tokens supports end users as they use features connected to the OpenAI AddOn, and purchasing image tokens supports ends users as they use features connected to the Azure AI Vision AddOn.
Code Explanation
AddOns Configuration: This section defines the available add-ons, each with a unique identifier and specific settings related to tokens and images.
onInfo Callback: This function handles info messages (with code 1000) and updates the settings for the relevant add-on based on usage.
Content Dialog (Upsell): This section manages upsell interactions, increasing the available tokens or images and updating the settings accordingly.
Feature Limitations
This section discusses the Token Upselling feature limitations:
Customization features only extend to the text within the notification banner, and are not available for the design of the notification banner.
Billing
The only billing related to this feature is on OpenAI’s end with token purchasing through use of your OpenAI API key.
Error Handling
This section discusses the error handling for token upselling. If an error occurs, end user’s will receive the following message:
“Something went wrong. Retry your request after a brief wait.”
The following image shows an example of how this message will appear within the user interface.
Additional Considerations
For more information on how the Token Upselling feature will visually look to an end user within the user interface, visit the OpenAI Feature Enhancements article.
Last updated