1 of 25

AddOns

Learn more about AddOn options within Beefree SDK and how you can use them to offer your end users extended features and functionality.

Beefree SDK includes Partner AddOns and Custom AddOns that you can incorporate into your application. At a high-level, these AddOns enable you to add extended functionality and capabilities to your application. These extended functionalities empower you to customize your end users' experience based on their interests and the desired tasks they are trying to perform with your app. The AddOns work as additional features you can opt in for on top of the base features that come with your Beefree SDK plan type.

There are two types of AddOns: Partner AddOns and Custom AddOns. Partner AddOns can easily be integrated with your application in a matter of minutes by installing them inside of the Developer Console. They are available for the following Beefree SDK plan types:

Essentials
Core
Superpowers
Enterprise

Custom AddOns are useful when there is a feature you'd like to offer within your application that is not available in our AddOn Marketplace within the Developer Console. In these instances, you can develop your own Custom AddOns for your application's end users. They are available for the following Beefree SDK plan types:

Superpowers
Enterprise

AddOns Overview

Learn more about AddOns at a high-level.

Why AddOns?

From the moment Beefree’s first email builder was released to the public, people started asking for new “things” to be available in the Content tab, so that they would be able to do more with the drag-and-drop editor.

Like inserting a countdown timer in a promotional email, or a QR code in an event ticket reminder, or live weather on a landing page.

They wanted to be able to go from this…

… to this:

… so that additional features are available in Beefree’s editors to build richer emails, landing pages, popups, and other digital content.

Everybody wins

Beefree SDK is used by over 600 software companies in all kinds of industries. Through their applications, hundreds of thousands of marketers create countless emails and landing pages, which reach millions of people.

With AddOns, richer emails and landing pages can be created, and everybody wins:

The people that receive those emails or view those pages, have a better experience.
The marketers that create them, have more ways to engage their audience.
The applications that embed Beefree’s builders can give those marketers better tools.
The AddOn providers reach more marketers through those apps.
And all of the above creates an overall more successful community around Beefree.

Types of AddOns

You can either use AddOns that have been built by other companies or build new ones.

If you wish to build an AddOn, you can either build an AddOn that’s just for you, and one that is available to any application that uses Beefree SDK. We call the former Custom AddOns, and the latter Partner AddOns, as companies partner with us to extend the core functionality of Beefree’s content builders.

Custom AddOns

This feature is available on Beefree SDK's Superpowers plan and above. If you're on the Core or Essentials plan, upgrade a development application for free to try this and other Superpowers-level features.

To add your own content tiles to the Content tab in a Beefree editor, you will need to develop a Custom AddOn.

For example, say your application is an event marketing system and you want your users to be able to drag-n-drop a QR code into an email. The QR code is generated by your event marketing system when the email is sent. The feature only works for your application. That’s a Custom AddOn.

For details on developing Custom AddOns, see AddOn Development.

This is an advanced feature that requires the Superpowers plan. Of course, you can test it in a development environment at no extra charge, if you wish to do so.

Partner AddOns

This feature is available on Beefree SDK's paid plans only.

There is a growing library of Partner AddOns for Beefree SDK customers, and there are more in the works. All these AddOns are available in a public directory inside the Beefree SDK Console. Application developers that have embedded a Beefree builder are able to quickly select and install any of those AddOns.

Interested in partnering with us? Learn how to submit a Partner AddOn.

Using vs. building AddOns

Using AddOns

Here is how you can locate and install ready-to-go AddOns:

Access the directory from within the Beefree SDK Console, from the Details page of any application that you have created.
Browse the list. These AddOns can help your end-users with things like countdown timers, dynamic maps, personalized cards, etc.
Install any AddOn with just a few clicks. Please note that some AddOns will require that you become a customer of the AddOn provider and obtain an API key.

For more, see Using AddOns.

Custom AddOns

Learn more about Custom AddOns, and how to develop and implement your own custom built AddOn.

This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.

Introduction

Example of a Custom AddOn

Let’s say you embedded our email editor in your event engagement platform, which has a feature that allows event marketers to insert an event ticket’s QR code in marketing campaigns sent to create more engagement around an event.

You want those marketers, users of your platform, to be able to easily include a QR code in the emails they send to remind people about the event. That way ticket holders can use the QR code to quickly get into the event venue.
So you decide to create a “QR Code” addon: “QR Code” becomes a new tile in the Content tab in the editor.
Marketers drag and drop the tile, click on Select event to indicate which event the QR is for, and use the editor to style that section of the message (e.g. size, padding, etc.).
The QR code is created dynamically by your platform, at the time the email is sent to a ticket buyer.
The feature is specific to your application.

Availability

Superpowers
Enterprise

Of course, there are exceptions to this requirement.

Testing: if you are not yet on a Superpowers or Enterprise plan, and you want to test building a Custom AddOn:
- Request an upgrade to the Superpowers plan.
- Test as much as you want. If and when you decide that you wish to deploy your Custom AddOn in production, we will ask you to upgrade your production application to the Superpowers or Enterprise plan.
Development of a Partner AddOn:
- You provide features that could be a good fit as an extension of our editors
- You are not a Beefree SDK customer

Getting started

You will be taken to a page that lists the addons that have been installed for this application. Since you are just getting started, the list is likely empty. Click on Create a custom addon to start the process of creating a Custom AddOn.

AddOn Development

Introduction

Welcome to the Beefree SDK AddOn development documentation!

This document is for anyone that wants to start creating AddOns for Beefree SDK users.

Before you get started, you may want to review these .

Happy coding!

Creating a development app

First, so that you are not testing your new AddOn with a production application.

Development applications inherit the plan of the production application to which they are connected. You can only build AddOns when you are on the . If you are not on one of those plans:

Create a development application
Request an upgrade

Once you have a development application on the Superpowers plan or above, proceed to the next step.

Getting started

The process all starts in the :

Log into the Console at
If you have not done so yet, create a development app as indicated above
Click the Details link next to any application on the Superpowers plan or above
Click the AddOns link, under Application configuration
Click the Create a custom AddOn button

When you create a new Custom AddOn, you will be prompted to enter some information through the AddOn setup form. Depending on the method that you choose, the number of fields in the form will change.

Name: The name of the AddOn is saved in the dashboard. This is not the name used for the tile in the Beefree editor’s Content tab but rather the internal name visible to other developers. In other words, it will not be shown to end-users of the editor.
Enable toggle: A toggle element to enable and disable the AddOn. When toggled OFF, the AddOn is not visible to end-users of the editor in your application (the host application).
Type: The type of content that the AddOn will create. Currently, the following content types are available:
- Image
- HTML
- Mixed
- Row
- Paragraph
- Button
- Title
- List
- Menu
- Icon
Handle: A unique identifier for this AddOn. This value will be the future reference between the AddOn and its content dialog. Additionally, it will be used to override settings per user or build a content dialog for the AddOn.
Method: This is an important selection and is covered in detail in the section below.
- External iframe: Choose this option if the AddOn is hosted outside the host application. If this is an AddOn that will be made available to other Beefree SDK applications via the Partner AddOn directory, then it is by definition hosted outside of the host application, and therefore you must select this method.
- Content Dialog: Choose this option for AddOn that lives inside the host application (e.g., internal AddOn). You cannot choose this method if you plan to make your AddOn available to others by listing it in the Partner AddOn directory.
Icon: Upload an image from your local computer that will become the icon associated with the tile shown in the editor’s Content tab. We recommend a 64 x 64 pixel SVG file.
Labels:
- Content Title: This is the name that will be used for the tile in the BEE editor’s Content tab (e.g., “Countdown timer,” “Product Recommendation,” etc.).
- Content button: The label for the call-to-action button (e.g., “Select a Countdown Timer”), which opens the content dialog or iframe.
- Placeholder message: This is the message shown in the editor’s stage when the tile is first dropped.

If you are using the iFrame method, some additional fields are shown on the form.

Iframe URL – Required The URL that will be loaded inside the Iframe.
API Key – Optional The API Key optionally authorizes the application to load the URL provided above. If authorization is not needed, this field can be left empty.
Authentication URL – Optional The endpoint that handles the optional authorization request. If authorization is not needed, this field can be left empty.

Once you have entered all the details, click Save, and you should immediately find your AddOn visible within the Beefree SDK platform. However, your AddOn is not completed until the configuration steps described below are done.

Concepts

Content dialog vs. iframe methods

One of the important choices you will make is in regard to how your content creation AddOn loads.

The general rule of thumb is that if your AddOn lives within the host application, you can use a content dialog.

If your AddOn lives on another website outside of the host application or will be listed in the Partner AddOn directory, then you must select the external iframe method.

Overview of iframe method

The AddOn can be built using any technology stack. There are no specific rules about how your AddOn functions internally.

However, you will need to implement the following:

JavaScript API
- Protocol to communicate between iframe and the Beefree application.
Server API
- Conditional health check endpoint
- Optional authentication endpoint

Don’t worry about the fine details just yet! We’ll revisit each of these methods in more detail in the following sections.

Overview of content dialog method

Superpowers and Enterprise applications have the option to create their own, custom AddOn with content dialogs.

This option is convenient when the AddOn and host applications are hosted under the same domain.

You don’t need to implement a JavaScript API or Server API when using the content dialog.

Content types

An AddOn can only return one type of content. The type you choose will determine which sidebar properties are shown when your AddOn is selected.

Currently, you may choose between the following content types:

Image: Will insert an image module on the stage, and show the properties of an image content block in the sidebar. Adjusting the properties allows for customization of the content type.
HTML: Will insert an HTML module on the stage, and show the properties of a custom HTML content block in the sidebar, except the HTML text input will be hidden. That’s because the HTML cannot be edited outside of the content dialog or iframe made available by your AddOn.
Mixed: Will insert a module on the stage that allows for loading of different content blocks with a single action.
Row: Will insert a row module on the stage, and show the row properties in the sidebar. The row is pre-built with a specific use case in mind. For example, a row that serves of the purpose of allowing end users to add products to their builders.
Paragraph: Will insert a paragraph module on the stage, and show the properties of a paragraph content block in the sidebar.
Button: Will insert a button module on the stage, and show the properties of a button content block in the sidebar. This simplifies offering pre-built buttons to your end users.
Title: Will insert a title module on the stage, and show the properties of a title content block in the sidebar.
List: Will insert a list module on the stage, and show the properties of a list content block in the sidebar.
Menu: Will insert a menu module on the stage, and show the properties of a menu content block in the sidebar. This simplifies offering pre-built menus to your end users.
Icon: Will insert an icon module on the stage, and show the properties of an icon content block in the sidebar.

Mixed Content AddOns

Mixed Content AddOns are a new type of content tile that allows the host application to load multiple content modules at once. This grants you greater flexibility with how you want your custom AddOn to interact with your customers and data; for example, you could create a mixed content AddOn to drop a product image in your template, along with a title, description, and more.

To utilize this feature:

The host application should return a valid response as the parameter of the “resolve” callback.

Response Content

A valid response that the hosting application should send to the Beefree app when the contents of a Mixed Content AddOn are selected must have the following structure:

For example:

If the response is not valid, an error is raised, and onError is called.

Modules definition

For each module type, here is the list of allowed properties.

Unless otherwise specified, the properties are optional.

Title

The following code calls a function named resolve with an object argument. This object defines a heading element with characteristics such as type, text content, alignment, font size, boldness, text color, and link color. The resolve function handles or returns the constructed heading element.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Title Simplified Schema

Image

The following sample code defines an image element with various attributes.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Image Simplified Schema

Button

The following sample code defines a button element with various attributes.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Button Simplified Schema

Paragraph

The following sample code defines a paragraph element with various attributes. The mergeTags property contains a list of merge tags, which can be used for dynamic content insertion.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Paragraph Simplified Schema

HTML

The following sample code defines an HTML element with various attributes.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

HTML Simplified Schema

The code defines a menu structure with a list of items. Each item has text content (e.g., “Menu item”) and a link associated with it. The link includes a title, URL (href), and a target attribute, demonstrating that it generates a menu with clickable items that open the specified links in the same browser window or tab when clicked.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

List

The following code snippet calls the resolve function to generate a list element defined by the type property set to 'list'. The value object specifies the list's characteristics, including the list tag ('ol'), HTML content, alignment, text formatting options like underline, italic, bold, and colors for text and links. This configuration allows you to customize list elements when creating custom addons for your host application using Beefree SDK.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

List Simplified Schema

Icons

The following code snippet defines an icons component for your application using Beefree SDK. It specifies an array of icon objects, including properties such as image URL, text, dimensions, and positioning. You can customize each icon with optional attributes like alt, title, and hyperlink details.

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Icons Simplified Schema

Custom AddOn - Row

This feature expands the capabilities of Custom AddOns by including:

additional integrations (e.g. a Product Block integrated with client’s e-commerce)
domain-specific contents (e.g Event Block for an application that offers event engagement)
.. and much more

To take advantage of this new feature, you have to:

The host application should return a valid response as the parameter of the “resolve” callback.

Response Content

A valid response that the hosting application should send to the Beefree app when the contents of a Row AddOn are selected must have the following structure:

For example:

The Content dialog method

The purpose of the contentDialog object in the code snippet is to handle different types of content that can be added to a dialog. It has a handler function that resolves with an image or HTML content based on the provided contentDialogId.

Configure content dialog in beeConfig

Image

HTML

Custom Fields

This is optional. Should you feel the need to add custom fields when resolving, we created a “customFields” key allowing to you place any additional custom fields inside of that object.

Row Simplified Schema

This simplified row schema is designed to help you structure and validate rows. It allows you to define rows that contain columns, which can hold various design elements like buttons, images, text, and more, all while enforcing clear rules for responsiveness, styling, and structure. Its simplicity lies in its modular approach: each column and module follows a predictable pattern with reusable definitions like padding and predefined options for properties like alignment and color.

You can reference the simplified schema in the following code snippet:

The Iframe method

JavaScript API

General

The JavaScript API allows an application inside of an external iframe to communicate with the host application that’s embedded a Beefree app. If you use the content dialog option, there is no need to implement the JavaScript API.

This section describes the communication protocol between a Beefree app and an external AddOn (i.e. an AddOn that is loaded into an iframe inside a Beefree app).

The communication takes place using postMessage, which is a standard way of communicating between Window objects.

The data object sent in the messages exchanged between the Beefree app and the AddOn has a standardized form:

Actions

The application inside the iframe may trigger the following actions:

onCancel
onSave

Events

The application inside of the iframe may listen for the following events:

loaded
init
load

Protocol

The Beefree app creates an iframe for the AddOn and then expects it to start the conversation by sending the loaded action:

The AddOn may also pass optional arguments to define the shape and style of the modal dialog that will contain the AddOn. If no arguments are provided the modal will fill the screen with no border.

The following parameters are available for the loaded method:

isRounded: Boolean true or false value. If true, the modal will have rounded corners.
hasTitleBar: Boolean true or false value. If true, the modal will display a title bar.
showTitle: Boolean true or false value. If true, the name of the AddOn will display in the title bar.
width: The width of the modal in pixels. If not provided, the modal will be 100% width.
height: The height of the modal in pixels. If not provided, the modal will be 100% height.

The following is a full example of a fixed-size modal with rounded corners, no title, and no close button. In this case, a custom close button is provided by the AddOn using the onCancel method.

The Beefree app then responds with an init message that contains the current locale of the editor and any pass-through data defined by the host application:

This message may be followed by an optional load message from the Beefree app in case the user has already defined the content of this AddOn in a previous session:

Any further action is then on the AddOn. In case the user cancels the edit, it is expected to send an onCancel message:

And if the user finishes editing and clicks on the save (or OK) button, the AddOn is expected to send an onSave message:

Server API

The Server API is only for use with external iframe applications. The application inside of the iframe must implement at least one API endpoint for a health check, but may also implement an optional endpoint for authentication. If you use the content dialog option, there is no need to implement the Server API.

Healthcheck

The health check endpoint is mandatory for apps that will be posted to the partner directory but otherwise optional. If your AddOn is for internal use (i.e. a custom AddOn), then you can perform your own health checks inside of the host application. If the application is offline, then you can use the configuration settings to disable it. If you choose to implement the health endpoint, simply ensure it returns a 200 for all GET requests.

Authentication

An application is not required to use any authentication. For example, the Giphy AddOn by Beefree is FREE for all users and therefore has no need for authentication.

However, authentication can be enabled for applications of any kind, if you want to identify or authorize the user to access your resources.

To enable authentication, simply add the optional parameters to your AddOn in the Beefree SDK Console:

API Key: This is any globally unique identifier that can be used to identify the customers, but usually, this would be a bearer token or JWT.
Authentication URL: This is the URL of your authentication endpoint. More on this below.

Protocol

With authentication enabled, a specific protocol follows:

Before the Beefree app creates an iframe for the AddOn, it performs a proxied GET request to the authentication URL.
The following HTTP Headers are passed to the AddOn’s endpoint.
1. x-real-ip: The IP Address of the host application
2. authorization: It contains the API Key (e.g. bearer token), which you provided to the host application.
3. x-bee-clientid: It contains the client id of the host application.
4. x-bee-uid: It contains the uid defined in the BEE configuration.
The iframe application uses the Authorization Header to validate the user permissions.
1. In the event of success, the application returns a URL to load within the iframe. The URL is provided as plain text with a 200 status code, no JSON formatting is needed.
2. In the event of unauthorized, the application returns a 403 status code.
The Beefree app creates an iframe for the AddOn using the URL returned from the authorization endpoint.
The AddOn application loads the application or performs additional authentication.

Configuration parameters

The AddOn section of the configuration allows you to override the parameters you configured at the application level, on a per-user basis.

Contribute to the Partner AddOn Marketplace

Learn more about how to contribute your Custom AddOn as a Partner AddOn in Beefree SDK's Partner AddOns Marketplace.

Introduction

Partner AddOns can easily be integrated with your application in a matter of minutes by installing them inside of the . You can reference available Partner AddOns inside of the . If the AddOn with the functionality you are looking for is not offered within the Partner Directory, you also have the option to create your own . If you'd like to add your Custom AddOn to Partner AddOn Marketplace within the Beefree SDK Developer Console, you have the option to do that.

Throughout this page, we will discuss at a high-level how you can list the Custom AddOn you created as a Partner AddOns within the Partner AddOn Marketplace.

Getting started

To get started, you will need to follow the documentation and create a Custom AddOn for a web application that has embedded Beefree SDK.

Please note that because Partner AddOns by definition live outside of the Beefree SDK application that will use them, you must select the external iframe method for development.

Listing in the partner directory

You can submit your AddOn to be listed in the Beefree SDK Partner AddOn Directory, so that other applications that have embedded Beefree SDK can take advantage of it.

You will be completely in charge of the business relationship with those companies, who will become your customers. We are not part of that relationship, other than being an enabler of it.

The following is a list of requirements for getting an AddOn listed in the Partner AddOn Directory:

You have signed the Beefree SDK AddOn License and Distribution Agreement. Contact your Account Manager or log in to the and submit a ticket for details.
You have built an AddOn that:
1. Uses the External iFrame Method (see )
2. Uses the optional health check endpoint
You have thoroughly tested the AddOn before submitting it to our test for a final review.
You have a demo of the AddOn that we can access.

Partner AddOns directory

These AddOns need to be installed from your Beefree SDK Console. Some of them are offered by third-party providers, and they might require an active subscription with those providers in order to be used.

Custom AI Writing Assistant

The Custom AI Writing Assistant AddOn enables host applications to integrate their own LLM models with Beefree SDK. This allows host applications to provide their end users with advanced AI writing capabilities that are specific to their domains. Using the Content Dialog, this AddOn employs the same entry points as the AI writing assistant, allowing full control over the AI experience within your application. Once your Custom AI Writing Assistant AddOn is fully configured, the Content Dialog displays the modal you created within the user interface when end users click the Write with AI button in the sidebar.

How do I enable the Custom AI Writing Assistant AddOn? | Terms of Services

Stability AI

The Stability AI AddOn converts text to images. This feature allows your end users to submit descriptions of what they would like to see in their AI-generated images, and to also submit negative prompts of what they do not want to see in their image. Once they submit the prompt and negative prompt, they'll receive an AI-generated image that they can use directly within their designs.

How do I enable the Stability AI AddOn? | AI Providers and Data Security | Terms of Services

DeepL

Through this AddOn and Multi-language templates, you can empower your end users to create up to six different language versions of a single design. Once your end users create their new language versions, they can click the Translate button to automatically translate all the translatable content within their designs.

How do I enable the DeepL AddOn? | AI Providers and Data Security | Terms of Services

AI Writing Assistant

Empower users to generate text quickly with AI. With this AddOn, your end users will see a new “Write with AI” button for Title, Paragraph, List, and Button content blocks. Beefree SDK processes your end users' prompts, sends them to your AI provider, and returns the response to the end user. They can then decide to apply or regenerate the response. By integrating the AI Writing Assistant, you provide your end users with a powerful tool to complete their designs quickly, which helps them maintain a competitive edge. Choose between Azure OpenAI or OpenAI as providers for this feature, our AddOn is quick and simple to integrate.

How do I enable the AI Writing Assistant AddOn? | Developer’s FAQ for OpenAI | Webinar

Azure AI Vision - Image Analysis

Generate alt-text descriptions with the power of Computer Vision. Azure AI Vision is a unified service that offers innovative computer vision capabilities. Image analysis pulls from more than 10,000 concepts and objects to detect, and caption images.

IO Monetizer

For setup, please reach out to support@interactiveoffers.com, and we will provide you with an API key that identifies your application on our network.

Over 600 digital publishers use Interactive Offers to help captivate new audiences and discover new monetization solutions. These programmatic email ad solutions provide a non-intrusive way to engage users with your content while earning revenue from every email you send.

Countdown Timers by NiftyImages

Create urgency with custom-designed countdown timers.

Give your users the ability to design fully customized countdown timers without ever leaving the editor. Create urgency for sales, events, holidays, webinars, and more, with this powerful yet easy-to-use AddOn.

Addon website | About the AddOn | Setup instructions | Privacy Policy | Support

Engage and inform with dynamic content, timers, and millions of visuals.

Email from your platform will come alive with this powerful set of dynamic-content tools and a massive collection of ready-to-use visuals. On-open content transforms the email experience into a live marketing channel, backed by millions of royalty-free visuals to grab inbox attention with eye-catching emails.

Addon website | Privacy Policy | Support

Countdown Timers by Sendtric

Boost clickthrough rates with dynamic countdown timers.

Sendtric countdown timers are perfect for your customers to create urgency in their campaigns. With our robust architecture and limitless customization options, our timers can be used for a variety of use cases such as sales, events, deadlines, new account sign-ups, abandoned cart reminders, and much more.

Addon website | About the AddOn | Privacy Policy | Support

Viewed

Capture your customer’s attention and stand out from the competition with the use of autoplay video in email.

It works with all email clients and devices. Get up to 90% of views on your opened emails, against only 16% that can be achieved including a static picture linked to YouTube. Autoplay video in email is the best solution to quickly spread your message and get millions of video views.

Addon website | About the AddOn | Privacy Policy | Support

Gifs

The GIFs by GIPHY AddOn gives your customers the best source for GIFs, ready to use in their emails and pages, without leaving the application. This AddOn is developed by Beefree SDK and powered by GIPHY.

Once installed and configured, they will see a new content tile in the builder. Once dragged into the email or page, a click on a button in the stage area will launch a GIPHY search dialog. Clicking on a GIF will import it instantly into the email or page.

Addon website | About the AddOn | Privacy Policy | Support

Stickers

The Stickers by GIPHY AddOn gives your customers the best source for stickers, ready to use in their emails and pages, without leaving the application. This AddOn is developed by Beefree SDK and powered by GIPHY.

Once installed and configured, they will see a new content tile in the builder. Once dragged into the email or page, a click on a button in the stage area will launch a GIPHY search dialog. Clicking on a sticker will import it instantly into the email or page.

Addon website | About the AddOn | Privacy Policy | Support

AddOn Development

Introduction

Welcome to the Beefree SDK AddOn development documentation!

This document is for anyone that wants to start creating AddOns for Beefree SDK users.

Before you get started, you may want to review these .

Happy coding!

Creating a development app

First, so that you are not testing your new AddOn with a production application.

Development applications inherit the plan of the production application to which they are connected. You can only build AddOns when you are on the . If you are not on one of those plans:

Create a development application
Request an upgrade

Once you have a development application on the Superpowers plan or above, proceed to the next step.

Getting started

The process all starts in the :

Log into the Console at
If you have not done so yet, create a development app as indicated above
Click the Details link next to any application on the Superpowers plan or above
Click the AddOns link, under Application configuration
Click the Create a custom AddOn button

Name: The name of the AddOn is saved in the dashboard. This is not the name used for the tile in the Beefree editor’s Content tab but rather the internal name visible to other developers. In other words, it will not be shown to end-users of the editor.
Enable toggle: A toggle element to enable and disable the AddOn. When toggled OFF, the AddOn is not visible to end-users of the editor in your application (the host application).
Type: The type of content that the AddOn will create. Currently, the following content types are available:
- Image
- HTML
- Mixed
- Row
- Paragraph
- Button
- Title
- List
- Menu
- Icon
Handle: A unique identifier for this AddOn. This value will be the future reference between the AddOn and its content dialog. Additionally, it will be used to override settings per user or build a content dialog for the AddOn.
Method: This is an important selection and is covered in detail in the section below.
- External iframe: Choose this option if the AddOn is hosted outside the host application. If this is an AddOn that will be made available to other Beefree SDK applications via the Partner AddOn directory, then it is by definition hosted outside of the host application, and therefore you must select this method.
- Content Dialog: Choose this option for AddOn that lives inside the host application (e.g., internal AddOn). You cannot choose this method if you plan to make your AddOn available to others by listing it in the Partner AddOn directory.
Icon: Upload an image from your local computer that will become the icon associated with the tile shown in the editor’s Content tab. We recommend a 64 x 64 pixel SVG file.
Labels:
- Content Title: This is the name that will be used for the tile in the BEE editor’s Content tab (e.g., “Countdown timer,” “Product Recommendation,” etc.).
- Content button: The label for the call-to-action button (e.g., “Select a Countdown Timer”), which opens the content dialog or iframe.
- Placeholder message: This is the message shown in the editor’s stage when the tile is first dropped.

If you are using the iFrame method, some additional fields are shown on the form.

Iframe URL – Required The URL that will be loaded inside the Iframe.
API Key – Optional The API Key optionally authorizes the application to load the URL provided above. If authorization is not needed, this field can be left empty.
Authentication URL – Optional The endpoint that handles the optional authorization request. If authorization is not needed, this field can be left empty.
Healthcheck URL – Optional, but required for This URL will be contacted when the editor is started to verify the status of the AddOn. In the case of AddOn downtime, the editor hides it in the UI. Please note: if you are building a , this is a required field as it will allow applications that have installed your AddOn to protect the quality of their end-users experience if your service is unavailable.

Concepts

Content dialog vs. iframe methods

One of the important choices you will make is in regard to how your content creation AddOn loads.

The general rule of thumb is that if your AddOn lives within the host application, you can use a content dialog.

If your AddOn lives on another website outside of the host application or will be listed in the Partner AddOn directory, then you must select the external iframe method.

Overview of iframe method

The AddOn can be built using any technology stack. There are no specific rules about how your AddOn functions internally.

However, you will need to implement the following:

JavaScript API
- Protocol to communicate between iframe and the Beefree application.
Server API
- Conditional health check endpoint
- Optional authentication endpoint

Don’t worry about the fine details just yet! We’ll revisit each of these methods in more detail in the following sections.

Overview of content dialog method

Superpowers and Enterprise applications have the option to create their own, custom AddOn with content dialogs.

This option is convenient when the AddOn and host applications are hosted under the same domain.

You don’t need to implement a JavaScript API or Server API when using the content dialog.

Content types

An AddOn can only return one type of content. The type you choose will determine which sidebar properties are shown when your AddOn is selected.

Currently, you may choose between the following content types:

Image: Will insert an image module on the stage, and show the properties of an image content block in the sidebar. Adjusting the properties allows for customization of the content type.
HTML: Will insert an HTML module on the stage, and show the properties of a custom HTML content block in the sidebar, except the HTML text input will be hidden. That’s because the HTML cannot be edited outside of the content dialog or iframe made available by your AddOn.
Mixed: Will insert a module on the stage that allows for loading of different content blocks with a single action.
Row: Will insert a row module on the stage, and show the row properties in the sidebar. The row is pre-built with a specific use case in mind. For example, a row that serves of the purpose of allowing end users to add products to their builders.
Paragraph: Will insert a paragraph module on the stage, and show the properties of a paragraph content block in the sidebar.
Button: Will insert a button module on the stage, and show the properties of a button content block in the sidebar. This simplifies offering pre-built buttons to your end users.
Title: Will insert a title module on the stage, and show the properties of a title content block in the sidebar.
List: Will insert a list module on the stage, and show the properties of a list content block in the sidebar.
Menu: Will insert a menu module on the stage, and show the properties of a menu content block in the sidebar. This simplifies offering pre-built menus to your end users.
Icon: Will insert an icon module on the stage, and show the properties of an icon content block in the sidebar.

Mixed Content AddOns

To utilize this feature:

Create a new custom AddOn of type “Mixed Content” from , as described in the “Getting started” section of this article;
Add the (for example, if the user chose the “Content Dialog” method, it might look something like this):

The host application should return a valid response as the parameter of the “resolve” callback.

Response Content

A valid response that the hosting application should send to the Beefree app when the contents of a Mixed Content AddOn are selected must have the following structure:

For example:

If the response is not valid, an error is raised, and onError is called.

Modules definition

For each module type, here is the list of allowed properties.

Unless otherwise specified, the properties are optional.

Title

Value

Mandatory

List

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Property

Value

Mandatory

List Simplified Schema

Icons

The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.

Property

Value

Mandatory

Icons Simplified Schema

Custom AddOn - Row

This feature expands the capabilities of Custom AddOns by including:

additional integrations (e.g. a Product Block integrated with client’s e-commerce)
domain-specific contents (e.g Event Block for an application that offers event engagement)
.. and much more

To take advantage of this new feature, you have to:

Create a new custom AddOn of type “Row” from , as described in the “Getting started” section of this article;
Add the (for example, if the user chose the “Content Dialog” method, it might look something like this):



var beeConfig = { contentDialog: { addOn: { label: 'Custom AddOn Label',  handler: (resolve, reject, args) => { ... }  }  } }

The host application should return a valid response as the parameter of the “resolve” callback.

Response Content

A valid response that the hosting application should send to the Beefree app when the contents of a Row AddOn are selected must have the following structure:

For example:

The content dialog configuration, required for this custom AddOn is the same configuration used by the other AddOns. Please see the paragraph.

The Content dialog method

To set up the content dialogs you will need to add the contentDialog object to beeConfig. For more details about the content dialog, please review .

Configure content dialog in beeConfig

Image

HTML

Custom Fields

This is optional. Should you feel the need to add custom fields when resolving, we created a “customFields” key allowing to you place any additional custom fields inside of that object.

Row Simplified Schema

You can reference the simplified schema in the following code snippet:

The Iframe method

JavaScript API

General

This section describes the communication protocol between a Beefree app and an external AddOn (i.e. an AddOn that is loaded into an iframe inside a Beefree app).

The communication takes place using postMessage, which is a standard way of communicating between Window objects.

The data object sent in the messages exchanged between the Beefree app and the AddOn has a standardized form:


{
  action: string,  
  data: any
}

Actions

The application inside the iframe may trigger the following actions:

onCancel
onSave

Events

The application inside of the iframe may listen for the following events:

loaded
init
load

Protocol

The Beefree app creates an iframe for the AddOn and then expects it to start the conversation by sending the loaded action:


{ action: 'loaded' }

The AddOn may also pass optional arguments to define the shape and style of the modal dialog that will contain the AddOn. If no arguments are provided the modal will fill the screen with no border.

The following parameters are available for the loaded method:

isRounded: Boolean true or false value. If true, the modal will have rounded corners.
hasTitleBar: Boolean true or false value. If true, the modal will display a title bar.
showTitle: Boolean true or false value. If true, the name of the AddOn will display in the title bar.
width: The width of the modal in pixels. If not provided, the modal will be 100% width.
height: The height of the modal in pixels. If not provided, the modal will be 100% height.

The following is a full example of a fixed-size modal with rounded corners, no title, and no close button. In this case, a custom close button is provided by the AddOn using the onCancel method.

The Beefree app then responds with an init message that contains the current locale of the editor and any pass-through data defined by the host application:

This message may be followed by an optional load message from the Beefree app in case the user has already defined the content of this AddOn in a previous session:


{ 
  action: 'load', 
  data:  
}

Any further action is then on the AddOn. In case the user cancels the edit, it is expected to send an onCancel message:


{ action: 'onCancel' }

And if the user finishes editing and clicks on the save (or OK) button, the AddOn is expected to send an onSave message:


{
  action: 'onSave',
  data: {
    type: 'html | image',
    value: 
  }
}

Server API

Healthcheck

Authentication

An application is not required to use any authentication. For example, the Giphy AddOn by Beefree is FREE for all users and therefore has no need for authentication.

However, authentication can be enabled for applications of any kind, if you want to identify or authorize the user to access your resources.

To enable authentication, simply add the optional parameters to your AddOn in the Beefree SDK Console:

API Key: This is any globally unique identifier that can be used to identify the customers, but usually, this would be a bearer token or JWT.
Authentication URL: This is the URL of your authentication endpoint. More on this below.

Protocol

With authentication enabled, a specific protocol follows:

Before the Beefree app creates an iframe for the AddOn, it performs a proxied GET request to the authentication URL.
The following HTTP Headers are passed to the AddOn’s endpoint.
1. x-real-ip: The IP Address of the host application
2. authorization: It contains the API Key (e.g. bearer token), which you provided to the host application.
3. x-bee-clientid: It contains the client id of the host application.
4. x-bee-uid: It contains the uid defined in the BEE configuration.
The iframe application uses the Authorization Header to validate the user permissions.
1. In the event of success, the application returns a URL to load within the iframe. The URL is provided as plain text with a 200 status code, no JSON formatting is needed.
2. In the event of unauthorized, the application returns a 403 status code.
The Beefree app creates an iframe for the AddOn using the URL returned from the authorization endpoint.
The AddOn application loads the application or performs additional authentication.

Configuration parameters

Once you have initialized the Beefree app, you can pass a series of to it.

The AddOn section of the configuration allows you to override the parameters you configured at the application level, on a per-user basis.

See: .

Alternate Text Generation with AI

Overview

The Alternate Text Generation with AI AddOn enables host application end users to instantly generate alternate text for images using AI. This feature is only available for images.

Visit the Alternate Text Generation with AI Knowledge Base article to learn more about the key benefits and use cases of this feature. Continue in this article to learn more about how to implement the Alternate Text Generation with AI AddOn in your host application.

Prerequisites

Prior to getting started with the configuration, ensure you have the following:

A working subscription with Azure
Superpower or Enterprise plan

Configuration Steps

This section discusses the steps you need to take to configure alternate text generation in your host application.

Developer Console

To active alternate text generation with AI in your Beefree SDK Developer Console, take the following steps:

Go to the Beefree SDK Developer Console
Enter your application
Click on “AddOns”
Select the “Azure AI Vision – Image Analysis” AddOn
Click “Install”
Once you click “Install”, the “Set Up Content” pop up will appear to configure the AddOn
Toggle “Enable” to on
Insert your Azure API Key and Endpoint

Note: If you do not yet have an Azure API Key and Endpoint, navigate to the Microsoft Azure Configuration Steps of this guide.

Microsoft Azure Configuration Steps

Azure Computer Vision is a key component of the Alternate Text Generation with AI AddOn. The steps highlighted in this section will guide you through how to obtain your Computer Vision or Cognitive Services API Key and Endpoint. If you have already obtained both, you can skip this section and navigate to the Limit the Usage section of this guide to learn more about customizing the AddOn for your end users.

Take the following steps to configure Azure Computer Vision and successfully integrate the AddOn into your host application:

Login to the Microsoft Azure Portal
1. Go to “Azure services”
2. Click “Create a resource”
3. Search “Cognitive Services”
4. Select “Cognitive Services” or “Computer Vision”
Note: Cognitive Services allows you to use other functions of Azure AI, but either “Cognitive Services” or “Computer Vision” will work for configuring the alternate text generation. Ensure you select the feature that is best for your use case.
Click “Create”
It will ask you for “Project Details”
Complete the following information to satisfy the “Project Details” requirement:

Subscription
Resource group
Instance Details
Region
Name
Pricing tier

Note: Version 4.0 is not yet available in all regions, but it is required for this feature to work. If you only have access to the 3.2 version, this feature will not work. Ensure that you have access to the correct version.

Click “Review + create” to create the resource
Azure will create your resource with an endpoint and API key
Input in the endpoint in the provider url field within in the Beefree Developer Console
Input in the API key within the API key field within in the Beefree Developer Console

Note: Once you complete these steps, wait at least 15 minutes for the resources to become available. After 15 minutes, you will be able to move forward with using your API Key and Endpoint with the feature.

For more information, visit the Microsoft Azure Computer Vision documentation.

Properties and Parameters

Data Type

Example

Description

handle

String

'ai-alt-text'

Represents the identifier for the specific add-on handling alt text generation.

infoMessage.detail.consumedImages

Number

Indicates the number of images processed by the bulk alt text generation call.

imagesCounter

Number

Keeps a running total of the number of images that have been processed for alt text generation.

imagesAvailable

Number

100

Indicates the total number of images available for alt text generation based on the user's subscription or quota.

isIconDisabled

Boolean

true

Determines whether the icon for the add-on is disabled, based on whether the imagesCounter has reached the imagesAvailable limit. Default value is false.

isUpsellEnabled

Boolean

true

Determines whether upsell options or notifications should be enabled for the user.

refreshedUsageSettings

Object

{ addOns: [...] }

Contains the updated configuration settings for the add-on, including the current usage metrics and state settings.

bee.loadConfig

Function

bee.loadConfig(refreshedUsageSettings)

Responsible for reloading the configuration settings for the add-on to reflect the latest usage metrics and states.

Limit the Usage

After you complete the configuration, the Alternate Text Generation with AI tool will be available to your end users. At this point in the process, the tool is offered for free to your end users. Take the steps outlined in this section to limit the usage of this feature for your end users.

The onInfo call in the following code snippet updates the usage limits for the Alternate Text Generation with AI feature. When AI-generated alternate text is used, the infoMessage.detail.consumedImages field indicates how many images were processed. This number is added to imagesCounter, which keeps track of the total images used so far. The backend processes images in bulk, so imagesCounter reflects the cumulative count of consumedImages from a single backend call. The refreshed settings ensure that the isIconDisabled property is updated if the image usage limit (imagesAvailable) is reached, and the settings are reloaded with bee.loadConfig(refreshedUsageSettings).

If you’d like to limit the usage of the Alternate Text Generation with AI tool, take the following steps to configure usage limitations.

Implement the onInfo call

Sample code onInfo call:


else if (handle === 'ai-alt-text') {
            imagesCounter += infoMessage.detail.consumedImages
            const refreshedUsageSettings = {
              addOns: [
                {
                  id: "ai-alt-text",
                  settings: {
                    imagesAvailable: imagesAvailable,
                    imagesUsed: imagesCounter,
                    isIconDisabled: (imagesCounter >= imagesAvailable) ? true : false,
                    isUpsellEnabled: isUpsellEnabled,
                  }
                },
              ],
            }
            // Reload Config
            bee.loadConfig(refreshedUsageSettings)
          }

Confirm the AddOn handle is ai-alt-text

The following sample code shows imagesCounter and imagesAvailable, which determine how many images you have used, and the image limit the host application setup for users, respectively.


let imagesCounter = 0
let imagesAvailable = 5

Note: In this example, the end user can only make five requests in total, after the fifth request, the end user will no longer be able to generate alternate text. The number five is defined in the configuration and can be customized. For example, if imagesAvailable is set ten, the end user will be able to perform ten requests.

In the AddOn settings, isIconDisabled is configured to automatically disable the Alternate Text Generation with AI feature when the counter reaches zero. However, through the Token Upselling notification banner, application end users will have the opportunity to purchase more images and regain access to the feature.


  // Check which addon
        const handle = data.detail.handle
        if (handle === 'ai-alt-text') {
          imagesCounter += infoMessage.detail.consumedImages || 1
          const refreshedUsageSettings = {
            addOns: [
              {
                id: "ai-alt-text",
                settings: {
                  imagesAvailable: imagesAvailable,
                  imagesUsed: imagesCounter,
                  isIconDisabled: imagesCounter >= imagesAvailable,
                  isUpsellEnabled: isUpsellEnabled,
                }
              },
            ],
          }
          bee.loadConfig(refreshedUsageSettings)
        }

To display the widget usage, take the following steps:

The call looks for imagesAvailable value and imagesUsed value
To activate the display usage widget, provide the usage data via the AddOn settings. Since the editor doesn’t track usage, you’ll need to refresh the values via the bee.loadConfig method to keep the display widget data current

let imagesCounter = 0
let imagesAvailable = 1000
let isUpsellEnabled = true

const beeConfig = {
  uid: 'string',
  ...
  addOns: [
    {
      id: "ai-alt-text",
      settings: {
        imagesAvailable: imagesAvailable,
        imagesUsed: imagesCounter,
        isIconDisabled: false,
        isUpsellEnabled: isUpsellEnabled,
      }
    },
  ],
  ...
  onInfo: function (data) {
    if (data.code === 1000) {
      const handle = data.detail.handle
      
      if (handle === 'ai-alt-text') {
        imagesCounter += data.detail.consumedImages
        const refreshedUsageSettings = {
          addOns: [
            {
              id: "ai-alt-text",
              settings: {
                imagesAvailable: imagesAvailable,
                imagesUsed: imagesCounter,
                isIconDisabled: (imagesCounter >= imagesAvailable),
                isUpsellEnabled: isUpsellEnabled,
              }
            },
          ],
        }
        bee.loadConfig(refreshedUsageSettings)
      }
    }
  },
}

Note: If either of the settings imagesAvailable or imagesUsed are not sent, the application will not show the consumption.

Advanced Permissions

This section discusses advanced permissions for your application users. You can use the two settings IsIconDisabled and enabled to configure permissions for your end users. To configure both booleans, take the steps outlined in the subsequent sections.

Disable Prompts Per User

To disable prompts per user, perform the following:

Set isIconDisabled to true


{
                id: "ai-alt-text",
                settings: {
                  isIconDisabled: true
                }

Note: The end user will be able to see the button, but will not be able to use the button through setting the isIconDisabled setting to true

You can reference the difference in appearance in the following images.

Image 1.0 displays an example of the wand when the feature is not active.

Image 2.0 displays an example of the AI wand icon when the feature is active.

Disable AddOn Per User

To disable the AddOn completely for an end user, perform the following:

Set the enabled field to false


const beeConfig = {
    uid: 'inactive-user',
    ... 
    addOns: [
      {
        id: "ai-alt-text",
        enabled: false
      },
    ],
    ...
}

Feature Limitations

Ensure you familiarize yourself with the following feature limitations to ensure this AddOn is suitable for your application’s needs:

You can generate the caption for an image multiple times, but you’ll always get the same result for the alternate text
The AI model does not work well with PNG or SVG images with transparent backgrounds, especially when the outline is black
Only available in English
Not available for Multi-language templates
Images must have URLs and be publicly accessible
Only available for static images, not available for dynamic images
Not available for custom AddOn of image type

Billing

Unlike the OpenAI AddOn, the Alternate Text Generation AddOn does not charge by tokens. Rather, the AddOn charges for each image caption you generate. Reference the Microsoft Azure Pricing page for additional information.

If you want to know if you are being charged, and you have the usage widget enabled, you will only be charged if the counter goes down.

Note: If an error occurs after the icon for the Alternate Text Generation AddOn is clicked by an end user, and text is not generated, you will not be charged. You will only be charged for instances when a caption is successfully generated.

Error Handling

In the event an error occurs, the end user will see an alert and you will receive a message from the Azure API with additional details regarding the error.

For more information on potential errors and error codes, reference the Azure Cognitive Services REST API reference or the Computer Vision REST API reference – Azure Cognitive Services depending on which service you opted in for to configure this feature.

Additional Considerations

The AI Alternate Text Generator is compatible with token upselling. The token upselling feature notifies the end users when their token usage is running low and when it is completely out. Both notifications include an option for the end user to purchase more tokens. The appearance of these notifications are customizable. Read the Token Upselling documentation to learn more about configuring token upselling within your host application.

FAQs

Q: Will Azure keep the photos used with this feature?

A: The following answer is directly from the Azure Data and privacy for Image Analysis website:

The images you submit to Image Analysis service are processed in real time, and the input images and results are not retained or stored in the service after processing.

For more information on image processing and data security, refer to the Azure AI services security documentation.

DeepL

Automatically translate content for different language templates using the DeepL addOn.

The DeepL AddOn is only available for Superpowers and Enterprise plans.

MLT Automatic Bulk Translation with DeepL

The new DeepL addOn available in the Developer Console empowers your end users to translate all the translatable content within their designs using the new translate button. This feature requires that you have Multi-language templates configured for your application, and that you have a DeepL API key. Once you configure both within your host application, your end users will be able to automatically translate the translatable content within the different language versions of their designs. Also, now your end users can have up to six different language versions of their designs. Visit the Automatic Translations white label end user documentation to learn more about how this feature works for your application's end users.

The following content types qualify as translatable content:

Modules and translatable properties

Header Meta information

Button: label - The text displayed on the button.
Paragraph: html - The HTML content of the paragraph.
Heading/Title: text - The textual content of the heading or title.
List: html - The HTML content of the list.
Image: alt - The alternative text for the image.
Video: thumbAlt - The alternative text for the video's thumbnail.
Icon: text, alt, title - The textual content, alternative text, and title of the icon.
Menu: text, title - The textual content and title of the menu.

Title
Description
Subject
Preheader

The HTML translatable property refers to the text within the HTML tags of the element itself. For the "Button" module, the translatable property is "label," which specifies the text displayed on the button. In the "Paragraph" module, the translatable property is "html," indicating the HTML content within the paragraph tags. For "Heading/Title," the property is "text," representing the textual content of the heading or title. The "List" module also uses "html," referring to the HTML content within the list tags. The "Image" module has the "alt" property, which provides alternative text for the image. In the "Video" module, "thumbAlt" denotes the alternative text for the video's thumbnail. The "Icon" module includes "text," "alt," and "title," covering the textual content, alternative text, and title of the icon, respectively. Lastly, the "Menu" module uses "text" and "title" for its textual content and title.

The following video shows a template with Heading, Paragraph, and List modules. When the Translate button is clicked, the text within the translatable properties for those modules are translated. The following section displays a JSON example with a translation in Spanish.

Example JSON Translation

Example JSON with Spanish Translation

In the following JSON, English is the primary language and Spanish is set as the translation language.

{
  "page": {
    "body": {
      "container": {
        "style": {
          "background-color": "#FFFFFF"
        }
      },
      "content": {
        "computedStyle": {
          "linkColor": "#0068A5",
          "messageBackgroundColor": "transparent",
          "messageWidth": "500px"
        },
        "style": {
          "color": "#000000",
          "font-family": "Arial, Helvetica, sans-serif"
        },
        "type": "page-properties",
        "webFonts": []
      },
      "description": "Empty template for BEE",
      "head": {
        "meta": {
          "description": "Enjoy a heartwarming moment with your furry friends while savoring your morning coffee. Learn about life's lessons and the importance of hard work together.",
          "subject": "Morning Coffee Conversations with Pets",
          "title": "Morning Coffee Conversations with Pets",
          "translations": {
            "es-ES": {
              "title": "Café matinal Conversaciones con mascotas",
              "description": "Disfrute de un momento entrañable con sus amigos peludos mientras saborea su café matutino. Aprendan juntos las lecciones de la vida y la importancia del trabajo duro.",
              "subject": "Café matinal Conversaciones con mascotas"
            }
          }
        }
      },
      "language": {
        "label": "English",
        "value": "en-US"
      },
      "rows": [
        {
          "columns": [
            {
              "grid-columns": 12,
              "modules": [
                {
                  "descriptor": {
                    "computedStyle": {
                      "hideContentOnDesktop": false,
                      "hideContentOnMobile": false
                    },
                    "heading": {
                      "prompt": "00000000-0000-0000-0000-000000000000",
                      "style": {
                        "color": "#555555",
                        "direction": "ltr",
                        "font-family": "inherit",
                        "font-size": "23px",
                        "font-weight": "700",
                        "letter-spacing": "0px",
                        "line-height": "120%",
                        "link-color": "#E01253",
                        "text-align": "center"
                      },
                      "text": "Morning Coffee Conversations with Pets",
                      "title": "h1",
                      "translations": {
                        "es-ES": {
                          "text": "Café matinal Conversaciones con mascotas"
                        }
                      }
                    },
                    "style": {
                      "padding-bottom": "0px",
                      "padding-left": "0px",
                      "padding-right": "0px",
                      "padding-top": "0px",
                      "text-align": "center",
                      "width": "100%"
                    }
                  },
                  "locked": false,
                  "type": "newsletter-modules-heading",
                  "uuid": "11111111-1111-1111-1111-111111111111"
                },
                {
                  "descriptor": {
                    "computedStyle": {
                      "align": "center",
                      "hideContentOnMobile": false
                    },
                    "divider": {
                      "style": {
                        "border-top": "1px solid #BBBBBB",
                        "width": "100%"
                      }
                    },
                    "style": {
                      "padding-bottom": "10px",
                      "padding-left": "10px",
                      "padding-right": "10px",
                      "padding-top": "10px"
                    }
                  },
                  "locked": false,
                  "type": "newsletter-modules-divider",
                  "uuid": "22222222-2222-2222-2222-222222222222"
                },
                {
                  "descriptor": {
                    "computedStyle": {
                      "hideContentOnAmp": false,
                      "hideContentOnDesktop": false,
                      "hideContentOnHtml": false,
                      "hideContentOnMobile": false
                    },
                    "paragraph": {
                      "computedStyle": {
                        "linkColor": "#0068a5",
                        "paragraphSpacing": "16px"
                      },
                      "html": "<p>Once upon a time, a man sat at his kitchen table, enjoying his morning coffee as his two dogs and one cat gathered around him. With a warm cup in hand, he began to share with his furry companions the harsh reality of life after school. \"You see,\" he explained, \"we have to work every day to earn money so we can afford simple pleasures like pizza.\"</p>\n<p>The man's pets listened intently, their eyes filled with curiosity as he continued to elaborate on the importance of hard work and dedication. \"It may seem daunting at first,\" he reassured them, \"but with perseverance and a positive attitude, we can achieve our goals.\" The dogs wagged their tails in agreement, while the cat purred softly in approval.</p>\n<p>As the morning sun streamed through the windows, casting a warm glow over the kitchen, the man smiled at his beloved pets. \"Remember,\" he said affectionately, \"life is full of challenges, but as long as we stick together and work hard, we can enjoy the simple pleasures that make it all worthwhile.\" And with that heartwarming sentiment, they continued their morning ritual of coffee and conversation, grateful for each other's company.</p>",
                      "prompt": "33333333-3333-3333-3333-333333333333",
                      "style": {
                        "color": "#000000",
                        "direction": "ltr",
                        "font-family": "inherit",
                        "font-size": "14px",
                        "font-weight": "400",
                        "letter-spacing": "0px",
                        "line-height": "120%",
                        "text-align": "left"
                      },
                      "translations": {
                        "es-ES": {
                          "html": "<p>Érase una vez un hombre sentado a la mesa de su cocina, disfrutando de su café matutino mientras sus dos perros y un gato se reunían a su alrededor. Con una taza caliente en la mano, empezó a compartir con sus peludos compañeros la dura realidad de la vida después de la escuela. \"Veréis\", explicó, \"tenemos que trabajar todos los días para ganar dinero y poder permitirnos placeres sencillos como la pizza\"</p>\n<p>Las mascotas del hombre escuchaban atentamente, con los ojos llenos de curiosidad, mientras él seguía explicando la importancia del trabajo duro y la dedicación. \"Al principio puede parecer desalentador\", les tranquilizó, \"pero con perseverancia y una actitud positiva, podemos conseguir nuestros objetivos\" Los perros movieron la cola en señal de acuerdo, mientras el gato ronroneaba suavemente en señal de aprobación.</p>\n<p>Mientras el sol de la mañana se colaba por las ventanas, arrojando un cálido resplandor sobre la cocina, el hombre sonrió a sus queridas mascotas. \"Recordad\", les dijo cariñosamente, \"la vida está llena de retos, pero mientras permanezcamos unidos y trabajemos duro, podremos disfrutar de los placeres sencillos que hacen que todo merezca la pena\" Y con ese sentimiento reconfortante, continuaron su ritual matutino de café y conversación, agradecidos por la compañía mutua.</p>"
                        }
                      }
                    }
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

How to activate

This section discusses the prerequisites and steps you need to take to get started with this feature.

Prerequisites

Ensure the Multi-language templates feature is toggled on inside of the Developer Console.
DeepL API key
Note: DeepL offers a free tier for their plans. You can obtain an API key from DeepL for free to get started with this feature.

Activate the addOn in the Developer Console

Take the following steps to activate this feature:

Log in to the Beefree SDK Developer Console.
Navigate to the application you'd like install the addOn in.
Install the DeepL addOn.
Provide the requested details.
Save your changes.

Auto Translation Configuration Parameter

Activate this feature by adding the new configuration parameter templateLanguageAutoTranslation and setting it to true.

The following code sample displays an example of the templateLanguageAutoTranslation, templateLanguage, and templateLanguages parameters.

// Configuration for the bee plugin
// Configuration for the bee plugin
var beeConfig = {
  uid: 'fakeUid123',
  container: 'bee-plugin-container',
  templateLanguageAutoTranslation: true,
  templateLanguage: {
    value: 'en-US',
    label: 'English'
  },
  templateLanguages: [
    { value: 'it-IT', label: 'Italian' },
    { value: 'fr-FR', label: 'French' },
    { value: 'es-ES', label: 'Spanish' },
    { value: 'ru-RU', label: 'Russian' },
    { value: 'el-GR', label: 'Greek' },
    { value: 'hy-AM', label: 'Armenian' }
  ]
};

If you have a custom top bar in your application, take the following additional steps:

Describe how to translate a template:
1. translateTemplate → bee.translateTemplate({ language: 'it-IT' })
Describe how to reset a translation:
1. resetTemplateTranslation → bee.resetTemplateTranslation({ language: 'it-IT' })

Translate a Template

A function to translate the template to a specified language using the Beefree SDK.

React Translate a Template example

import React from 'react'; // Importing React
import { bee } from 'bee-plugin'; // Importing the bee plugin

// Define a functional component
const TranslateTemplateButton = () => {
  // Function to translate the template to Italian
  const translateTemplate = () => {
    bee.translateTemplate({ language: 'it-IT' }); // Calling the translateTemplate function with Italian language code
  };

  // Returning a button that triggers the translateTemplate function when clicked
  return (
    <button onClick={translateTemplate}>
      Translate Template to Italian
    </button>
  );
};

export default TranslateTemplateButton; // Exporting the component

JavaScript Translate a Template example

// Function to translate the template to Italian
function translateTemplate() {
  bee.translateTemplate({ language: 'it-IT' }); // Calling the translateTemplate function with Italian language code
}

// Adding an event listener to the button with id 'translateButton'
// When the button is clicked, the translateTemplate function is triggered
document.getElementById('translateButton').addEventListener('click', translateTemplate);

HTML example

<!-- Button that will translate the template to Italian when clicked -->
<button id="translateButton">Translate Template to Italian</button>

Reset a Translation

A function to reset the translation of the template to its original state using Beefree SDK.

React Reset a Translation example

import React from 'react'; // Importing React
import { bee } from 'bee-plugin'; // Importing the bee plugin

// Define a functional component
const ResetTemplateTranslationButton = () => {
  // Function to reset the template translation to the original state
  const resetTemplateTranslation = () => {
    bee.resetTemplateTranslation({ language: 'it-IT' }); // Calling the resetTemplateTranslation function with Italian language code
  };

  // Returning a button that triggers the resetTemplateTranslation function when clicked
  return (
    <button onClick={resetTemplateTranslation}>
      Reset Template Translation
    </button>
  );
};

export default ResetTemplateTranslationButton; // Exporting the component

Reset a Translation JavaScript example

// Function to reset the template translation to the original state
function resetTemplateTranslation() {
  bee.resetTemplateTranslation({ language: 'it-IT' }); // Calling the resetTemplateTranslation function with Italian language code
}

// Adding an event listener to the button with id 'resetButton'
// When the button is clicked, the resetTemplateTranslation function is triggered
document.getElementById('resetButton').addEventListener('click', resetTemplateTranslation);

HTML example

<!-- Button that will reset the template translation when clicked -->
<button id="resetButton">Reset Template Translation</button>

Error handling

If errors occur, onWarning or onError will be triggered. If the request completes successfully there’s no direct feedback.

The following errors are returned by the backend service when something goes wrong during the translation.

Code

Message

HTTP Status

Details

6001

Unauthorized

401

6050

Generic Error

500

6100

Bad Request

400

E.g. 'sourceLanguage' and 'targetLanguage' must be defined

6150

Validation Error

400

E.g. language X is not supported

6200

Bump service error

[error returned by the Bumper]

E.g. Error while computing the fields to translate

6250

Bump service error

500

E.g. Error while applying the translation

6350

Provider service error

500

[error returned by DeepL]

AI Writing Assistant

The AI Writing Assistant AddOn is only available for and plans.

AI Writing Assistant Overview

Use this AddOn to enable the AI Writing Assistant for your end users. This AddOn allows users to generate text within their designs using AI, helping them complete their designs faster and more efficiently. This AddOn integrates with OpenAI, Azure OpenAI, or Anthropic as the providers for this feature.

With this feature, your end users will see a Write with AI button for Title, Paragraph, List, and Button content blocks. Beefree SDK processes your end users' prompts, sends them to your AI provider, and returns the response to the end user. They can then decide to apply or regenerate the response.

By integrating the AI Writing Assistant, you provide your end users with a powerful tool to complete their designs quickly, which helps them maintain a competitive edge. This AddOn is quick and simple to integrate.

The following image provides an example of how the AI Writing Assistant looks to your end user:

How to activate the AI Writing Assistant

Prerequisites

Azure OpenAI, OpenAI, or Anthropic account and credentials.
AI Writing Assistant AddOn enabled in the Developer Console.

Switch Providers

Take the following steps to switch providers:

Log in to the Beefree SDK Developer Console.
1. Navigate to the application you'd like to use.
2. Navigate to the application's AddOns section.
Click on the Edit button for the AI Writing Assistant AddOn .
1. Click Manage providers.
2. Click Add provider.
  1. Complete the required information*.
Click Save.

*The following information is required for each provider.

Required Provider Information

Manage Providers

When managing your providers, you will have the following options:

Edit
Deactivate
Delete

Additional considerations

Azure OpenAI, OpenAI, and Anthropic are the only provider options for the AI Writing Assistant.
Cognitive Vision is the provider for the Alt text generation with AI feature.

Customize the AddOn's Configuration

In certain scenarios, you may find the need to personalize both the user interface (UI) and the operational features of the AI Writing Assistant AddOn. This is particularly applicable when you want to achieve objectives such as:

Controlling Access to the Prompt: You might want to limit who can access and manipulate the prompt. In a shared environment, for instance, you may want to restrict certain users from altering the prompt, which is crucial for maintaining consistency and avoiding unwanted changes.
Enabling Per User or Per Content Type: You might want to limit who can access the AI so you can up-sell the feature to end-users. Or, you may only want to enable the AI capability for specific content types, such as paragraphs vs. buttons.
Disabling Automatic Suggestions: The AI Writing Assistant AddOn can generate automatic suggestions at the prompt, which may not always be desirable. In such cases, you might want to disable this feature to have more control over the input and output at the prompt.

We’ll cover all of these scenarios in the following sections as we discuss the settings and configuration options available for developers.

General Settings

Currently, the following settings are supported:

AI Writing Assistant Configuration Example

The following code snippet displays an example of the AI Writing Assistant with the ai-integration id and available configuration settings.

Monitor Usage

With each prompt response, the addon will report the usage data provided by Azure OpenAI or OpenAI API via the editor’s onInfo callback without storing or tracking the data.

You can also monitor when the user applies a prompt response.

Monitor Usage Example

The following code snippet shows an example of how to monitor usage for this addOn.

You may choose to track the end-user’s total usage through the aforementioned onInfo callback if desired. Additionally, you may choose to show the usage data to the user via the built-in display widget. To activate the display usage widget, provide the usage data via the addon settings. Since the editor doesn’t track usage, you’ll need to refresh the values via the bee.loadConfig method to keep the display widget data current.

See below for an example of how the UI will render when provided with the optional display usage widget.

Disable Prompts Per User

To enable the AI Writing Assistant AddOn, but disable the prompt per user, pass the isPromptDisabled boolean parameter as true.

The following example will disable the prompts for the user with an uid of inactive-user.

Disable Prompts Per User Example

The following code snippet providesan example of how to disable prompts per user.

Disable AddOn Per User

To disable the AI Writing Assistant AddOn for a particular user, use the following configuration. Ensure the enabled parameter is set to false. To turn the AddOn back on for a user, edit the parameter to true.

Disable AddOn Per User Example

Disable AddOn Per Content Block Type

The AI Writing Assistant AddOn is available for the following content blocks:

Title
Paragraph
List
Button

You may utilize the Advanced Permissions configuration to disable AI Writing Assistant AddOn per content type.

The following example will disable the addon for the paragraph block:

Disable AddOn Per Content Block Type

The following code snippet displays an example of disabling the addOn per Content Block type.

Prompt Suggestions

The AI Writing Assistant AddOn includes preset prompt suggestions to facilitate the content creation process. These appear after the initial draft of your text has been formulated and whenever further refinement is needed. Please note that this function applies only when editing existing text through the AI prompt. The suggestions will not appear for placeholder text.

Here’s a simplified step-by-step guide on how to use suggestions, as shown below:

Start with your draft text added to the design area.
If you desire to adjust the tone to be more formal, for example, click on the paragraph, list, title, or button you want to modify.
Navigate to the ‘Write with AI’ option.
Click on the area designated for adding prompts.
You’ll notice the prompt suggestions popup.
Select the ‘Make it [desired tone]’ option, making sure to replace [desired tone] with a value (e.g., funny)
Click ‘Generate’.

The AI will then generate a revised version of your content, matching the tone you entered.

Customize Prompt Suggestions

Below are the preset prompt suggestions we have identified for the different content tiles, along with their corresponding translation key, in case you’d like to revise the prompt through our custom languages feature.

Paragraph

Button

List

Title

Additional considerations

Prior to configuring the AI Writing Assistant AddOn, consider the following:

Scrolling behavior

Scrolling Behavior

This section will discuss how to manage an odd scrolling behavior related to the AI Writing Assistant AddOn. At times, the AI Writing Assistant side panel opens and requires the end user to scroll down to reach the prompting area.

The following image shows an example of this behavior:

If you encounter this behavior, take the following steps to avoid the need for scrolling to access the prompting area:

Navigate to your CSS code.
Change the height of your container using the calc() function as shown in the following examples:

This sets the height of the element to be the full height of its parent (100%) minus 100px, which accounts for an offset such as a footer.

This sets the height of the element to be exactly 100% of its parent's height with no offset.

The calc() function allows for mathematical expressions in CSS values, making it versatile for dynamic layouts.

Save your updated CSS.

You can now access the prompting section of the AI Writing Assistant on the front end without scrolling down the side panel.

The following image shows an example of this result:

AI Providers and Data Security

Apply a Brand Tone

Learn how to provide your end users with the option to tailor the AI Writing Assistant's responses by adding a brand tone.

The AI Writing Assistant AddOn and Brand Tone feature are only available for Superpowers and Enterprise plans.

Introduction to Brand Tone

The Apply a Brand Tone feature is an optional enhancement to the AI Writing Assistant AddOn. This feature allows your application's end users to define which brand tone they want the AI Writing Assistant to use when generating text. This definition provides OpenAI with additional brand tone context it considers when generating text to return to your end user. The result is more precise, accurate, and useable copy for your application's end users.

By configuring the AI Writing Assistant to reflect a specific brand tone, you empower end users to create designs that consistently align with their brand identity, reducing the need for manual adjustments to the AI's responses. This feature can improve workflows through organic and beneficial adoption of the AI Writing Assistant, positioning your application as a powerful tool.

To learn more about the end user experience and what it looks like to utilize this feature on the frontend, visit the Apply a Brand Tone white label end user documentation. The markdown file is also available in our white label docs repository.

Note: OpenAI is currently the only compatible provider with this feature.

Prerequisites

Prior to getting started, ensure you have the following:

A Superpowers or Enterprise Beefree SDK plan
The AI Writing Assistant AddOn enabled in the Beefree SDK Developer Console.
OpenAI API Key

Integrating Brand Tone

This section will walk you through how to add the Apply brand tone option to the AI Writing Assistant integrated within your host application.

At a high-level, this section will cover how to take the following steps and successfully integrate Brand Tone:

Add isBrandTonesEnabled setting to ai-integration
Add hooks to BeeConfig for data storage and management

Note: Ensure you have the AI Writing Assistant AddOn configured and implemented prior to integrating the Brand Tone option. For details steps on how to configure this AddOn, visit the AI Writing Assistant documentation.

Configure the AI Writing Assistant with the Brand Tone Settings

Take the following steps to configure the AI Writing Assistant to include Brand Tone:

Add the ai-integration AddOn to your beeConfig object under the addOns array.
Add the isBrandTonesEnabled setting and set the boolean to true. This is the only required setting to enable this feature.
(Optional) Customize the settings for the Brand Tones feature to allow users to add, edit, delete, or select tones based on your application’s needs.

Sample Code for Brand Tones Settings

The following code snippet provides an example configuration for integrating the AI Writing Assistant AddOn with the settings for managing Brand Tones:

const beeConfig = {
  uid: 'unique_user_id', // Unique identifier for the user
  addOns: [
    {
      id: "ai-integration", // Identifier for the AI integration add-on
      settings: {
        isBrandTonesEnabled: true, // Mandatory to enable the Brand Tones feature
        canAddBrandTones: true, // Optional: Allow the user to add new Brand Tones
        canDeleteBrandTones: false, // Optional: Prevent the user from deleting existing Brand Tones
        canEditBrandTones: true, // Optional: Allow the user to edit existing Brand Tones
        canSelectBrandTones: true // Optional: Allow the user to select Brand Tones for use
      }
    }
  ],
  // Other configurations
};

Available Settings for Brand Tone

You can control the different settings for the Brand Tone using the following booleans. You can use these boolean flags to allow or restrict user actions.

For example:

Set isBrandTonesEnabled: true if you want to enable the Brand Tones feature.
Set canDeleteBrandTones: false to prevent end users from deleting existing tones.

The following table provides details about each setting and how you can customize them.

Setting

Data Type

Example Value

Description

isBrandTonesEnabled

Boolean

true

Determines if the Brand Tones feature is enabled for the user.

canAddBrandTones

Boolean

true

Allows users to add new Brand Tones to their account.

canDeleteBrandTones

Boolean

false

Allows users to delete existing Brand Tones.

canEditBrandTones

Boolean

true

Allows users to edit existing Brand Tones.

canSelectBrandTones

Boolean

true

Allows users to select from available Brand Tones for use in their session.

Add Hooks for Data Storage

This section explains how to add hooks for data storage and management.

Introduction to Hooks

Hooks allow your application to store and manage Brand Tone data. By defining the brandTone hook, you ensure communication between your system and Beefree SDK, enabling users to create and manage Brand Tones effectively.

Step-by-Step Instructions

1. Define the Hook

Add the brandTone hook to your beeConfig object. This hook handles all Brand Tone-related actions like retrieving, saving, and deleting tones.

Sample Code:

const beeConfig = {
    uid: 'unique_user_id',  // Unique identifier for the user
    addOns: [
        // ...
    ],
    hooks: {
      // ... ,
      brandTone: {
        handler: async (resolve, reject, { action, data }) => {
          switch (action) {
            case 'get':
              const brandVoiceList = await getBrandTones() // Your own implementation to retrieve saved brand tones
              resolve(brandVoiceList)
              break
            case 'save':
              await saveBrandTone(data) // Store brand tone to your own system
              resolve()
              break
            case 'saveSelected':
              await saveSelectedBrandTone(data) // Store the selected brand tone to your own system
              resolve()
              break
            case 'getSelected':
              const selectedBrandTone = await getSelectedBrandTone() // Get the stored selected brand (this will be autoselect when the users open the AI side panel)
              resolve(selectedBrandTone)
              break
            case 'delete':
              await deleteBrandTone(data) // Delete the brand tone from your system
              resolve()
              break
            case 'edit':
              await editBrandTone(data) // Update the just edited brand tone on your system 
              resolve()
              break
            default:
              break
          }
        }
      }
    }
};

2. Implement the Handler Logic

The brandTone hook supports various actions.

The handler receives the resolve and reject methods to fulfill the Promise for the requested data or action. Use reject only for issues encountered on your application's side, such as errors in data retrieval. Always call resolve after processing the data within your system.

Alongside resolve and reject, the handler also receives an object containing action and data properties. The action determines the specific scenario in the Brand Tones flow, while the data is used to store any necessary changes.

Refer to the table below for details on when and how each action will be triggered.

Action name

Description

Data received

Expected resolved value

get

Will be requested as soon as the AI Side Panel opens and after successful operations (e.g. edit, delete, save). It asks for a saved Brand Tones list that you’ll likely retrieve from your system.

none

Array of Brand Tone (in the exact form you received that in save action)

save

Will be requested when the user clicks on “Save” in the Modal to create a Brand Tone. This is where you store data in your system.

brandTone object

none (just a resolve() to confirm save action succeded)

edit

Will be requested when the user clicks on “Save” in the Modal to edit an existing Brand Tone. This is where you update data in your system.

brandTone object

none (just a resolve() to confirm edit action succeded)

delete

Will be requested when the user clicks on “Delete” in the Modal to manage existing Brand Tones. This is where you remove the brand tone data from your system.

brandTone object

none (just a resolve() to confirm delete action succeded)

getSelected

Will be requested as soon as the AI Side Panel opens and after successful operations (e.g. edit, delete, save).

It asks for the id of the Brand Tone to pre-select on the Brand Tones select.

none

string (the id of the Brand Tone)

saveSelected

Will be requested when the user selects the Brand Tone from the select and after successful operations (e.g. edit, delete, save).

This is to preserve the user selection between different sessions.

string (the id of the Brand Tone the user just selected)

none (just a resolve() to confirm saveSelected action succeded)

Additional Considerations

The Brand Tone feature is available only through the AI Writing Assistant AddOn with OpenAI as the provider.
Configuring hooks for data storage is required to enable this feature successfully.
Thoroughly test your implementation to ensure smooth communication between the SDK and your system.

Custom AI Writing Assistant

Learn how to connect your large language model (LLM) and create your own AI Writing Assistant with Beefree SDK.

This AddOn is available on Beefree SDK Enterprise and VPC plans.

Overview

This AddOn is compatible with the following modules:

Title
Paragraph
List
Button

With this AddOn, you can deliver a centralized assistant experience that caters to your specific application needs. By integrating your own LLM model, you reduce irrelevant content in AI-generated outputs and ensure consistency in how the AI generates content, all while aligning it with your brand’s voice and tone. This increased level of control helps increase AI adoption and usage across your customer base, because your end users are engaging with an AI tool that feels familiar and reliable.

Integrating your custom LLM also allows for continuous improvement, because the model can be trained and refined based on user feedback and real-world interactions. This results in more accurate suggestions, higher relevance, and greater user satisfaction, empowering your end users to create better content with minimal effort.

The following video displays an example of a Content Dialog with a custom built user interface that is connected to the Custom AI Writing Assistant AddOn.

Prerequisites

Prior to getting started with the configuration, ensure you have the following:

Enterprise plan
A custom LLM service to call from within the Content Dialog
Access to the Developer Console

Configuration Steps

This section outlines the steps you need to take to integrate the Custom AI Writing Assistant AddOn into your web application.

These steps are the following:

Install and enable the AddOn
Configure the Content Dialog
Manage Advanced Permissions

Install and Enable the AddOn

Take the following steps to install and enable the AddOn:

Log in to the Beefree SDK Developer Console.
Click on the Details button corresponding to the application you'd like to configure the AddOn for.
Go to the AddOns section and click Browse AddOns.
Search for and select the Custom AI Writing Assistant AddOn.
Once selected, click Install.
After installation, toggle the Enable button and save your changes.

Note: You can revisit this page in the future by clicking Edit in the AddOn card to turn the AddOn on or off as needed.

Once you activate the Custom AI Writing Assistant AddOn with your own LLM, you cannot activate the AI Writing Assistant AddOn, which uses either OpenAI or Azure OpenAI models. Only one of these two AddOns can be active.

Content Dialog Configuration

To use the Custom AI Writing Assistant AddOn, you need to configure the Content Dialog. This is important for defining how your custom LLM is called and how the response is handled.

The following code snippet displays an example configuration:

contentDialog: {   
  customLLM: {
    label: 'Custom LLM',
    handler: (resolve, reject, args) => {
      resolve({ generatedText: `This is module ${args.moduleUUID}, I'm a ${args.moduleType} and my content was ${args.moduleContent}` })
    }
  }
},

Args Parameter Details The args parameter contains the following:
Field
Explanation
moduleUUID
Unique identifier for the module
moduleType
Type of the module (e.g., TITLE, PARAGRAPH, LIST, BUTTON)
moduleContent
Current content of the module unless it matches the default content. If it does, the value will be an empty string.
Configure Resolve The content dialog must resolve an object corresponding to this interface:
```
{
  generatedText: string
}
```
- Handling Lists: If you are working with a list, ensure the generated text separates each item with a line break. The text will then be split on each line break to construct the list in the stage. The syntax for a line breaks is \n.

Advanced Permission Management

You can control the visibility and state of the Write with AI button using Advanced Permission settings. For example, disabling the AddOn will hide the button, while turning the button off will keep it visible but non-functional.

The following code snippet displays an example configuration for Advanced Permissions:

addOns: [
  ...,
  {
    id: "custom-ai-integration",
    enabled: true,
    settings: {
      isButtonDisabled: false
    }
  },
]

Disable the AddOn for Specific Blocks

You can disable the Custom AI Writing Assistant for specific content blocks using Advanced Permissions. As a reminder, this AddOn is compatible with the following content blocks:

You can use Advanced Permissions to disable access to a specific block using the following:

aiIntegration: {
            locked: false,
            show: false
          }

To hide the AddOn for a specific module, the show property should be set to false.

Settings

The table below outlines the settings available for the ai-integration AddOn in the Beefree SDK:

Setting

Data Type

Default

Description

enabled

boolean

true

If false, the “Write with AI” button is hidden

isButtonDisabled

boolean

false

If true, the “Write with AI” button is visible but disabled

Edit the Button Label

After your activate and configure this AddOn, a Write with AI button will appear to your application's end users for the applicable content blocks.

The following video displays how the Write with AI button inside the Content Properties once a content block is dragged and dropped onto the stage.

The following section provides an example of changing the Write with AI button text to "Generate copy". You can follow the same approach in the following example, but replace "Generate copy" with the text you'd like to use for your label.

Edit Label Example

To change the "Write with AI" button label to "Generate copy" using the mailup-bee-common-component-ai.config-label, follow these steps:

Set up the BeeFree SDK: Initialize your beeConfig object as usual.
Add the translations object: In your beeConfig, include the translations object where you will specify the label override.
Override the label: Inside the translations object, add the "mailup-bee-common-component-ai.config-label" key and set its value to "Generate copy".

var beeConfig = {
    uid: config.uid,
    // additional configuration properties...
    translations: {
        "mailup-bee-common-component-ai.config-label": "Generate copy"
    },
    // other properties...
};

This will update the button text from "Write with AI" to "Generate copy."

Additional Considerations

Consider the following when using the Custom AI Writing Assistant AddOn:

You can reference the AI Writing Assistant End user documentation as an example of how engaging with AI features looks like for end users.
We are committed to maintaining the highest standards of security to protect your data at every level. For more information on our security practices, visit our GDPR and Cybersecurity page.

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
Limit Usage
Content Dialog Config
Configure Resolve

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 total
tokensAvailable: Displays how many remaining tokens an end user had
isUpsellEnabled: 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.

 
 var tokenCounter = 0
  var tokensAvailable = 1000
  var isUpsellEnabled=true

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.


addOns: [
      {
        id: "ai-integration",
        settings: {
          tokensAvailable: tokensAvailable,
          tokensUsed: tokenCounter,
          tokenLabel: 'tokens',
          isPromptDisabled: (tokenCounter >= tokensAvailable) ? true : false,
          isSuggestionsDisabled: false,
          isUpsellEnabled: true,
          metadataGeneration: true // Enabled by default
        }
      },
    ],

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.

   // Watch for AddOn Usage
    onInfo: function (infoMessage) {

      if (infoMessage.code === 1000) {
        var handle = infoMessage.detail.handle

        if (handle === 'ai-integration') {
          var totalTokens = infoMessage.detail.usage.total_tokens
          tokenCounter = tokenCounter + totalTokens

          // Update AddOn Settings
          var newConfig = {
            addOns: [
              {
                id: "ai-integration",
                settings: {
                  tokensAvailable: tokensAvailable,
                  tokensUsed: tokenCounter,
                  tokenLabel: 'tokens',
                  isPromptDisabled: (tokenCounter >= tokensAvailable) ? true : false,
                  isUpsellEnabled:isUpsellEnabled
                }
              },
            ],
          }
          // Reload Config
          bee.loadConfig(newConfig)
        }
      }
    },

The code works by:

Retrieving the handle from the infoMessage.
Checking if the handle is ai-integration.
If the handle is ai-integration, retrieve the totalTokens from the infoMessage.
Updating the tokenCounter by adding the totalTokens.
Creating a newConfig object with the updated tokenCounter 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.

       upsell: {
          label: 'upsell',
          handler:(resolve, reject, args)=>{
            tokensAvailable+=1000
            resolve({
              addOns:[{
                  id: "ai-integration",
                  settings: {
                    tokensAvailable: tokensAvailable,
                    tokensUsed: tokenCounter,
                    tokenLabel: 'tokens',
                    isPromptDisabled: (tokenCounter >= tokensAvailable) ? true : false,
                    isUpsellEnabled:isUpsellEnabled
                    }}]
                  })
          }
        },

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.


contentDialog: {   
   upsell: {
          label: 'upsell',
          handler:(resolve, reject, args)=>{
            tokensAvailable+=1000
            resolve({
              addOns:[{
                  id: "ai-integration",
                  settings: {
                    tokensAvailable: tokensAvailable,
                    tokensUsed: tokenCounter,
                    tokenLabel: 'tokens',
                    isPromptDisabled: false,
                    isUpsellEnabled:isUpsellEnabled
                    }}]
                  })
          }
        },

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

tokenLabel

string

Default is “tokens”.

isPromptDisabled

boolean

Default is false. If changed to true, it can override tokens balance and disable the prompt.

isUpsellEnabled

boolean

Default is false. If changed to true, it enables the upsell.

tokensCounter

number

Tokens used, if not provided in the configuration, the user has unlimited tokens.

tokensAvailable

number

Tokens available to the end user. If not provided in the configuration, the user has unlimited tokens.

upsellTrigger

number

Default is 80 (%) of tokens available.

isSuggestionsDisabled

boolean

Default is false.

isRegenerateEnabled

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.


// Configure AddOn Settings
addOns: [{
  id: "ai-integration",
  settings: {
    tokensAvailable: tokensAvailable,
    tokensUsed: tokenCounter,
    tokenLabel: 'tokens',
    isPromptDisabled: (tokenCounter >= tokensAvailable) ? true: false,
    isSuggestionsDisabled: false,
    isUpsellEnabled: isUpsellEnabled,
    isRegenerateEnabled: false,
    upsellTrigger: 90],
  },
}

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


// Configure AddOn Settings
addOns: [{
  id: "ai-integration",
  settings: {
    tokensAvailable: tokensAvailable,
    tokensUsed: tokenCounter,
    tokenLabel: 'tokens',
    isPromptDisabled: (tokenCounter >= tokensAvailable) ? true: false,
    isSuggestionsDisabled: false,
    isUpsellEnabled: isUpsellEnabled,
    isRegenerateEnabled: false,
    upsellTrigger: 90],
  },
}

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`.

const notificationTemplateId = "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}.

const originalTemplate = "You're out of {tokenLabel}. {ctaLabel} to continue.";

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:
1. Removing the CTA button entirely.
2. Changing the CTA button label.
3. 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`.

/// Create a custom language entry with the same ID.
const customLanguageId = "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."

// To remove the CTA:
const customTemplateWithoutCTA = "You're out of {tokenLabel}.";

// To change the CTA label:
const customTemplateWithCustomCTA = "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.


// For the case without CTA
const notificationTextWithoutCTA = customLanguageEntries[customLanguageId];

// For the case with a custom CTA label
const notificationTextWithCustomCTA = customLanguageEntries[customLanguageId];

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.

// AddOns configuration
// This section configures the available add-ons and their settings.
addOns: [
    {
        id: "ai-integration",  // Unique identifier for the AI integration add-on
        settings: {
            tokensAvailable: tokensAvailable,  // Total tokens available for AI usage
            tokensUsed: tokenCounter,  // Counter for tokens used so far
            tokenLabel: 'tokens',  // Label for the tokens
            isPromptDisabled: false,  // Flag to disable prompt if needed
            isSuggestionsDisabled: false,  // Flag to disable suggestions if needed
            isUpsellEnabled: isUpsellEnabled,  // Flag to enable upsell functionality
        }
    },
    {
        id: "ai-alt-text",  // Unique identifier for the AI alt text add-on
        settings: {
            imagesAvailable: imagesAvailable,  // Total images available for alt text generation
            imagesUsed: imagesCounter,  // Counter for images used so far
            isPromptDisabled: (imagesCounter >= imagesAvailable) ? true : false,  // Disable prompt if images limit is reached
            isUpsellEnabled: isUpsellEnabled,  // Flag to enable upsell functionality
        }
    }
],

// onInfo callback
// This callback function handles various info messages received during the operation.
onInfo: function(infoMessage) {
    if (infoMessage.code === 1000) {  // Check if the info message code is 1000
        var handle = infoMessage.detail.handle;  // Get the handle from the message details
        if (handle === 'ai-integration') {  // Check if the handle is for AI integration
            var totalTokens = infoMessage.detail.usage.total_tokens;  // Get total tokens used from message details
            tokenCounter = tokenCounter + totalTokens;  // Update the token counter

            // Update AddOn Settings for AI Integration
            var newConfig = {
                addOns: [{
                    id: "ai-integration",
                    settings: {
                        tokensAvailable: tokensAvailable,  // Update available tokens
                        tokensUsed: tokenCounter,  // Update used tokens
                        tokenLabel: 'tokens',  // Token label
                        isPromptDisabled: (tokenCounter >= tokensAvailable) ? true : false,  // Disable prompt if token limit is reached
                        isUpsellEnabled: isUpsellEnabled  // Maintain upsell enabled status
                    }
                }]
            };
            // Reload Config
            bee.loadConfig(newConfig);  // Reload the configuration with updated settings
        } else if (handle === 'ai-alt-text') {  // Check if the handle is for AI alt text
            imagesCounter++;  // Increment the images counter

            // Update AddOn Settings for AI Alt Text
            const refreshedUsageSettings = {
                addOns: [{
                    id: "ai-alt-text",
                    settings: {
                        imagesAvailable: imagesAvailable,  // Update available images
                        imagesUsed: imagesCounter,  // Update used images
                        isPromptDisabled: (imagesCounter >= imagesAvailable) ? true : false,  // Disable prompt if images limit is reached
                        isUpsellEnabled: isUpsellEnabled  // Maintain upsell enabled status
                    }
                }]
            };
            // Reload Config
            bee.loadConfig(refreshedUsageSettings);  // Reload the configuration with updated settings
        }
    }
},

// content dialog
// This section handles the upsell dialog interactions.
upsell: {
    label: 'upsell',  // Label for the upsell dialog
    handler: (resolve, reject, args) => {
        if (args.handle === 'ai-integration') {  // Check if the handle is for AI integration
            tokensAvailable += 1000;  // Add 1000 tokens to the available tokens
            resolve({
                addOns: [{
                    id: "ai-integration",
                    settings: {
                        tokensAvailable: tokensAvailable,  // Update available tokens
                        tokensUsed: tokenCounter,  // Maintain the used tokens count
                        tokenLabel: 'tokens',  // Token label
                        isPromptDisabled: false,  // Ensure prompt is not disabled
                        isUpsellEnabled: isUpsellEnabled  // Maintain upsell enabled status
                    }
                }]
            });
        } else if (args.handle === 'ai-alt-text') {  // Check if the handle is for AI alt text
            imagesAvailable += 5;  // Add 5 images to the available images
            resolve({
                addOns: [{
                    id: "ai-alt-text",
                    settings: {
                        imagesAvailable: imagesAvailable,  // Update available images
                        imagesUsed: imagesCounter,  // Maintain the used images count
                        isPromptDisabled: false,  // Ensure prompt is not disabled
                        isUpsellEnabled: isUpsellEnabled  // Maintain upsell enabled status
                    }
                }]
            });
        }
    }
}

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.

AddOns

AddOns Overview

Why AddOns?

Everybody wins

Types of AddOns

Custom AddOns

Partner AddOns

Using vs. building AddOns

Using AddOns

Custom AddOns

Introduction

Example of a Custom AddOn

Availability

Getting started

AddOn Development

Introduction

Creating a development app

Getting started

Concepts

Content dialog vs. iframe methods

Overview of iframe method

Overview of content dialog method

Content types

Mixed Content AddOns

Response Content

For example:

Modules definition

Title

Title Simplified Schema

Image

Image Simplified Schema

Button

Button Simplified Schema

Paragraph

Paragraph Simplified Schema

HTML

HTML Simplified Schema

Menu

Menu Simplified Schema

List

List Simplified Schema

Icons

Icons Simplified Schema

Custom AddOn - Row

Response Content

For example:

The Content dialog method

Configure content dialog in beeConfig

Image

HTML

Custom Fields

Row Simplified Schema

The Iframe method

JavaScript API

General

Actions

Events

Protocol

Server API

Healthcheck

Authentication

Protocol

Configuration parameters

Contribute to the Partner AddOn Marketplace

Introduction

Getting started

Listing in the partner directory

Partner AddOns directory

Custom AI Writing Assistant

Stability AI

DeepL

AI Writing Assistant

Azure AI Vision - Image Analysis

IO Monetizer

Countdown Timers by NiftyImages

Countdown Timers by Sendtric

Viewed

Gifs

Stickers

AddOns