export const vendorImg = '/docs/images/logos/bubble.svg'
export const bentoLogoImg = '/docs/images/logos/bento-text-logo.svg'
export const headerBackground = '/docs/images/headers/header_background.webp';


# Bento Bubble Integration

Learn how to set up and use Bento's Bubble plugin for server-side actions, events, subscriber management, and transactional emails. 


## Overview
Bento's Bubble plugin enables server-side actions within your Bubble workflows, providing:
- **Bento Events** - Track user actions and behaviors
- **Subscriber Management** - Import and manage subscribers with commands
- **Transactional Emails** - Send dynamic emails from Bubble workflows
- **Real-time Integration** - Seamless data flow between Bubble and Bento

## Prerequisites
- An active Bento account
- A Bubble account with the ability to install plugins
- Your Bento API keys (publishable key, secret key, and site UUID)

## Setup Guide


  

    1. In your Bubble app, navigate to the Plugins tab
    2. Search for "Bento" in the plugin marketplace
    3. Install the Bento plugin

  


  

    The plugin requires three settings to be set in the plugin settings:

    - **publishable_key**: Your Bento publishable key
    - **secret_key**: Your Bento secret key
    - **site_uuid**: Your Bento site UUID

    These will be used across all Bento actions in your workflows.

    
> Keep your API keys secure and never expose them in client-side code.


    Note for testing you will want to enter the same keys in the test settings fields, if you use a separate bento site for testing use that site uuid.


  


## Available Actions

### 1. Bento - Send Event (Dynamic)

**Category**: Data (Things)

Track user actions and behaviors in your Bubble app. Events sent will add the subscriber via the email address if they do not already exist. If the subscriber does exist, the event will be added to the existing subscriber. Events can also start flows, and other automations.

**Required Parameters:**

  - **email** (`dynamic text`): 
    User's email address
  
  - **type** (`static text`): 
    Event type (e.g., "$completed_onboarding", "$purchase")
  


**Optional Parameters:**

  - **detail_data** (`dynamic json text`): 
    Event details json, e.g., `{ plan: "pro", quantity: 10 }`
  
  - **first_name** (`dynamic text`): 
    User's first name
  
  - **last_name** (`dynamic text`): 
    User's last name
  
  - **company_name** (`dynamic text`): 
    User's company name (e.g., "Acme Inc")
  
  - **job_title** (`dynamic text`): 
    User's job title (e.g., "CEO")
  
  - **phone_number** (`dynamic text`): 
    User's phone number (e.g., "+1 555-555-5555")
  
  - **source** (`dynamic text`): 
    Sign-up source (e.g., "website", "event", "app")
  
  - **status** (`dynamic text`): 
    User status (e.g., "active", "inactive")
  


**Example Usage:**
```
email: Input Email's value
type: "$completed_onboarding"
first_name: Input First Name's value
last_name: Input Last Name's value
detail_data: {"purchase_amount": 99.99, "product_id": "SKU123"}
```


### 2. Subscriber Action

**Category**: Data (Things)

Manage subscribers with various commands. This is effective for managing subscriber status (subscribed or unsubscribed), or fields and tags for updating subscriber metadata in one-off cases. This action should not be used for batch updates, and is heavily rate limited.

**Required Parameters:**

  - **email** (`dynamic text`): 
    Target subscriber email address
  
  - **command** (`static select`): 
    The command to execute
  


**Available Commands:**
- `subscribe` - Add subscriber to list
- `unsubscribe` - Remove subscriber from list
- `add_tag` - Add tag to subscriber
- `remove_tag` - Remove tag from subscriber
- `add_field` - Add custom field value
- `remove_field` - Remove custom field

**Optional Parameters:**

  - **query** (`dynamic text`): 
    Command parameter (required for most commands, e.g., tag name or field value)
  
  - **field_name** (`dynamic text`): 
    Used with "add_field" to define the field key
  
  - **field_value** (`dynamic text`): 
    Used with "add_field" to define the field value
  


**Example Usage:**
```
command: "add_tag"
email: "jesse@example.com"
query: "purchased"
```


> ⚠️ **Warning**
> If you need to updated many tags, fields at once, use the subscriber update action instead, this will allow you to make all the changes in one request.


### 3. Subscriber Update

**Category**: Data (Things)

Update subscriber information during import.

**Required Parameters:**

  - **email** (`dynamic text`): 
    Subscriber email address (validated)
  


**Optional Parameters:**

  - **first_name** (`dynamic text`): 
    Subscriber's first name
  
  - **last_name** (`dynamic text`): 
    Subscriber's last name
  
  - **tags** (`dynamic text`): 
    Comma-separated string of tags to add (e.g., "lead,mql")
  
  - **remove_tags** (`dynamic text`): 
    Comma-separated string of tags to remove
  
  - **custom_fields** (`dynamic object`): 
    Any additional custom fields, automatically handled
  


**Features:**
- Automatic custom field handling
- Tag management during import

 Subscriber update is a bulk update action, so it can take a moment before all changes are applied. 

### 4. Bento Transactional

**Category**: Data (Things)

Send transactional emails from Bubble workflows.

**Required Parameters:**

  - **to** (`dynamic text`): 
    Recipient email address
  
  - **from** (`static text`): 
    Sender email address. <strong>MUST be an existing author in your account</strong>
  
  - **subject** (`dynamic text`): 
    Email subject line
  
  - **html_body** (`dynamic text`): 
    HTML content of the email
  
  - **transactional** (`boolean`): 
    Set to true to send a transactional email that ignores if the user has unsubscribed. <strong>USE WITH CAUTION</strong>
  


**Optional Parameters:**

  - **text_body** (`dynamic text`): 
    Plain text version of the email
  
  - **personalizations** (`dynamic object`): 
    Dynamic variables for the email
  


**Example Usage:**
```
to: "user@example.com"
from: "noreply@yourcompany.com"
subject: "Welcome to our platform!"
html_body: "<h1>Welcome {{name}}!</h1><p>Thanks for signing up.</p>"
personalizations: '{"name": "John Doe", "link": "https://example.com"}'
```


> ⚠️ **Warning**
> Don't use transactional emails directly from public forms. Always validate and sanitize input data.


## Best Practices


  
    ### Event Best Practices

    - Use descriptive event types (e.g., "$purchase", "$signup")
    - Include relevant detail_data for segmentation of subscribers
    - Track user journey milestones
    - Use consistent naming conventions
  

  
    ### Subscriber Best Practices

    - Always validate email addresses
    - Use meaningful tag names and namespaced tags
    - Implement proper consent management
    - Handle unsubscribe requests promptly
  

  
    ### Email Best Practices

    - Use personalizations for dynamic content
    - Secure forms with ratelimiting, captcha, and other security measures
    - Include both HTML and text versions
    - Test email templates thoroughly
  

  
    ### Security Best Practices

    - Never expose API keys in client-side code
    - Validate all input data
    - Use HTTPS for all communications
    - Implement rate limiting
  


## Common Use Cases

### User Registration Flow
1. User signs up in Bubble
2. Send "Subscriber Update" action to add to Bento
3. Send "$signup" event with user details
4. Event triggers welcome email and starts onboarding journey

### E-commerce Purchase
1. User completes purchase
2. Send "$purchase" event with order details
3. Send order confirmation email via event and Bento flow

### User Engagement
1. User completes onboarding
2. Send "$completed_onboarding" event
3. Add "onboarded" tag via Bento flow
4. Trigger next steps in workflow

## Troubleshooting


  
    ### Authentication Issues

    - Verify API keys are correct
    - Check site UUID format
  

  
    ### Event Tracking Issues

    - Validate email format
    - Check event type syntax
    - Verify detail_data format (JSON)
    - Monitor API response codes
  

  
    ### Subscriber Management Issues

    - Confirm email address format
    - Check command syntax
    - Validate tag names
    - Review error messages
  

  
    ### Email Delivery Issues

    - Verify sender email format
    - Check personalizations syntax
    - Test with simple content first
  


## Error Handling

The plugin includes comprehensive error handling with detailed messages for troubleshooting:

- **Authentication errors**: Check API keys and permissions
- **Validation errors**: Verify input data format
- **Network errors**: Check connectivity and API status
- **Rate limiting**: Implement appropriate delays

## Advanced Features

### Custom Fields
- Automatically handle any additional properties in detail_data for easy enrichment
- Support for complex data structures
- Flexible field naming conventions

### Tag Management
- Use comma-separated strings for easy Bubble integration
- Support for bulk tag operations
- Automatic tag validation, if it doesn't exist it will be created

### Personalizations
- Accept JSON strings
- Dynamic content injection in emails

## Support

Contact Bento support via:
- Email: support@bentonow.com
- Discord: [Bento Community](https://discord.gg/ssXXFRmt5F)