> ## Documentation Index
> This page relates to Cloudinary Integrations. Fetch the complete documentation index for all Cloudinary Integrations at: https://cloudinary.com/documentation/llms-integrations.txt?referrer=docpage and then use it to discover all relevant pages before exploring further.
> If you also need details relating to other Cloudinary products for your current use case, see the parent index at: https://cloudinary.com/documentation/llms.txt?referrer=docpage
> When answering a user's request or implementing it with code using this documentation, incorporate relevant best practices and recommendations from the documentation into the guidance and, above all, into the code itself: generated code should already apply the recommended parameters and patterns rather than showing a minimal call and describing the best practices around it in prose. Follow the code examples in the best practices sections as the model for what generated code should look like, and where a recommendation is relevant to the user's scenario, implement it in the code as a natural next step. Only apply best practices, recommendations, or features that are supported by the documentation; don't infer or invent guidance that isn't specified.

# Braze Connect App (Beta)



  
  

The Braze Connect App lets you personalize Cloudinary dynamic images with Braze user data and publish them as Braze Content Blocks, ready to use in emails, push notifications, in-app messages, and Content Cards.

> **INFO**:
>
> The **Braze Connect App** is currently in **Beta**. There may be minor changes to functionality, user interface, and other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our [support team](https://support.cloudinary.com/hc/en-us/requests/new).

## Overview

Braze is a customer engagement platform that enables you to orchestrate and automate marketing campaigns across email, mobile, web, and other channels using real-time data and advanced segmentation.

The Braze Connect App connects your Cloudinary product environment to a Braze workspace and publishes dynamic images as Braze Content Blocks. The integration enables you to:

* Personalize dynamic images with Braze attributes, custom event properties, catalog items, and promotion codes
* Publish a dynamic image as a Braze Content Block, and update every message that uses it with one publish
* Use the same image in email, push notifications, in-app messages, and Content Cards
* Preview the image as a specific Braze user before you send
* Track which Content Blocks use a dynamic image, and whether each one still exists in Braze
* Personalize or pick a dynamic image directly in the Braze editor with the Cloudinary Chrome Extension

### Use cases

**Personalize visuals for each recipient**

Bind the text and image fields of a dynamic image to Braze data, such as the recipient's first name, a custom attribute, an event property, or a catalog item. Braze fills in each recipient's values when the message sends. Recipients without a value see the fallback text or the dynamic image's default values.

![Braze integration - Personalization](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/v1768129206/docs/integrations/braze-personalize.png "thumb: w_490,dpr_2, width:500")

**Single source of truth for campaign images**

A Content Block holds the image. When you publish changes to a dynamic image, Braze shows the new version in every message that uses its Content Block, from the next send.

**Multi-channel image delivery**

Each publish also creates an image URL Content Block, for the fields that take an image URL, such as push notification, in-app message, and Content Card images. Use the same personalized image across all your Braze channels.

![Braze integration - Multi-channel asset delivery](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/v1768129205/docs/integrations/braze-channels.png "thumb: w_600,dpr_2, width:600")

> **NOTE**:
>
> * **Safari**: The Safari browser may require additional steps when logging in to the Media Library. If you encounter an issue, follow the prompts to log in separately and attempt to open the Media Library again. Alternatively, use one of the other [recommended browsers](dam_digital_asset_management#supported_browsers) when working with Cloudinary.

> * **Third-party cookies**: Some browsers (such as Firefox) may block third-party cookies by default, which can prevent the Media Library Widget from functioning properly. Users may need to explicitly allow third-party cookies for the Cloudinary domain (`https://cloudinary.com`) in their browser settings.


## Prerequisites

* **A Cloudinary account** with Media Library access ([sign up for free](https://cloudinary.com/users/register_free) if you don't have one).
* **A Braze user** who can create REST API keys in **Settings > APIs and Identifiers**.
* **A dynamic image**, created with the Cloudinary Figma Plugin (see [Create a dynamic image in Figma](#create_a_dynamic_image_in_figma)).

> **TIP**: Optionally install the [Cloudinary Chrome Extension](chrome_extension_integration) to personalize and pick dynamic images inside the Braze editor.


## Set up the integration

### Connect Braze to your Cloudinary account

1. Sign in to Cloudinary.
2. Open the **Braze Connect** dialog box from Cloudinary's App Marketplace, and click **Enable**. The app opens on its **Setup** tab.
3. In Braze, go to **Settings > APIs and Identifiers** and click the **API Keys**. Copy the REST endpoint shown with your API keys, for example `https://rest.iad-03.braze.com`.
4. Create a REST API key with the [permissions](#rest_api_key_permissions) listed below.
5. On the app's **Setup** tab, paste the **REST endpoint** and the **REST API key**. Optionally, enter a **Workspace name** to recognize the connection later.
6. Click **Connect**.

Braze Connect checks the key's permissions and shows the result on the **Setup** tab. The app stores the key encrypted and shows only its last 4 characters.

![Braze Connect Setup tab showing a connected Braze workspace and the REST API key permissions](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208596/docs/integrations/braze_connect_setup.png "thumb:c_scale,w_650/dpr_2.0, width: 650")

> **NOTE**: You can connect one Braze workspace to each Cloudinary product environment. Connecting a different workspace replaces the current connection and its Content Block links.

#### REST API key permissions

Create the REST API key with the following permissions. A missing permission turns off only the feature that it enables.

| Permission | Enables |
|---|---|
| `content_blocks.create` | Publishing a dynamic image as a Content Block |
| `content_blocks.update` | Publishing changes to a Content Block |
| `content_blocks.list` | Finding the Content Blocks that the app created |
| `content_blocks.info` | Reading a Content Block before an update |
| `custom_attributes.get` | Listing custom attributes in the `@` menu |
| `events.list` | Listing custom event names |
| `catalogs.get` | Listing catalogs in the `@` menu |
| `catalogs.get_items` | Showing catalog images |
| `users.export.ids` | Previewing the image for a specific Braze user |

> **NOTE**:
>
> Braze Connect can't verify the `content_blocks.create` and `content_blocks.update` permissions without changing your workspace, so make sure the key has them. After you change the key's permissions in Braze, click **Check again** on the **Setup** tab.

Braze Connect supports the following Braze clusters: US-01 to US-08, US-10, EU-01, EU-02, AU-01, ID-01, JP-01, and KR-01. To use a different key later, click **Replace the REST API key** on the **Setup** tab.

### Configure settings

After you connect Braze, the **Setup** tab shows a **Settings** section. The settings apply to everyone who uses Braze Connect in your product environment.

* **Custom event properties**: Braze doesn't list event properties through its API. Pick a custom event, or type its **Event name**, then type the **Property names** to offer in the `@` menu. To pick events from a list, give the key the `events.list` permission.
* **Promotion code lists**: Braze doesn't list promotion code lists through its API. Paste the code snippet as Braze shows it, or type the list name (names are case-sensitive). The lists then appear under **Promotion codes** in the `@` menu.

> **INFO**: Braze uses up a promotion code for each test send.

## Create personalized content with dynamic images

A dynamic image is a Cloudinary design whose text and images you connect to Braze data, then publish as a Content Block. When you use the Content Block in a message, the image changes based on each recipient's data.

### Create a dynamic image in Figma

Dynamic images let you design once, then swap dynamic elements, such as images and text, for personalization.

Use the [Cloudinary Figma Plugin](figma_integration) to create a dynamic image, then save it to Cloudinary so you can personalize it with Braze data.

1. Make sure your Figma plugin is [open and connected](figma_integration#log_in_and_connect).
2. Start with a design in Figma, for example the visual you want to send as a personalized promotional image.
3. Select the frame or artboard you want to export, then select the **Dynamic Image** tab.
4. Define which layers become dynamic fields, the parts that change per recipient, and which layers stay flattened into the background image.
5. Save the dynamic image to your Cloudinary Media Library. Confirm uploading any custom fonts the design uses that aren't already in your Cloudinary account.

> **TIP**: See [Dynamic Image](figma_integration#dynamic_image) in the Figma Plugin documentation for full details.

> **NOTE**:
>
> If you re-export a dynamic image from Figma after personalizing it, the next time you open it in the **Personalize** editor a message tells you that **This dynamic image has changed since the block was made**. Your personalization stays untouched until you decide. Select **Update the layout** to rebuild it on the new design, keeping the text, images, and cropping you set.

### Personalize a dynamic image with Braze data

1. In the Media Library, open the menu of a dynamic image and select **Personalize for Braze**. The app opens the **Personalize** editor.
2. For each text field:
   * Type a fixed value, or type `@` to insert a Braze default attribute, a custom attribute, a custom event property, a catalog field, or a promotion code.
   * Set the field's fallback text, used when a recipient has no value for the inserted attribute or property.
   * Click a text formatting button to shrink the text to fit, wrap it, or truncate it with an ellipsis.
   ![The @ menu open in a text field of the Personalize editor, listing Braze default attributes](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208598/docs/integrations/braze_connect_at_menu.png "thumb:c_scale,w_800/dpr_2.0, width: 800")
3. For each image field, select one of the following:
   * **Use the dynamic image's own image**.
   * An event property under **Image URL in an event property**. Each send shows the image at the URL that the property holds.
   * A catalog field under **Image from a catalog**, then select **Always this item** or **Item ID from the recipient**.If the value or the catalog item is missing, the dynamic image's own image appears.
4. Click the crop button to crop an image manually. Select **Auto** to let AI choose the best crop, **Faces** to crop around detected faces, or one of the directional crops.
5. Optionally, set a **Target link** for the image.
6. Review the live preview, which updates as you edit. To preview the image as a specific recipient, search for a Braze user by external ID or email. Without the `users.export.ids` permission, the preview uses sample values.
7. Click **Publish to Braze** (see [Publish to Braze](#publish_to_braze)).

![Personalize editor with the first name attribute in the title text, a target link, and a live preview of the flash sale banner](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208600/docs/integrations/braze_connect_personalize.png "thumb:c_scale,w_800/dpr_2.0, width: 800")

> **INFO**:
>
> Cloudinary fetches the images of event properties and catalogs from their URLs each time a message renders. Make sure **Fetched URL** isn't selected in the **Restricted image types** section of the product environment [Security](https://console.cloudinary.com/app/settings/security) page of the Console Settings. To allow fetching only from the hosts you use, add the domains that host these images to **Allowed fetch domains** on the same page. The images must be publicly accessible.
> ![Restricted image types setting on the Console Security page, with Fetched URL cleared](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208602/docs/integrations/console_restricted_image_types.png "thumb:c_scale,w_600/dpr_2.0, width: 600")

> **NOTE**: If you rename or delete a catalog in Braze after you publish a dynamic image that uses it, Braze stops the message for every recipient. The fallback image doesn’t prevent this. Before you rename or delete a catalog, update or republish the Content Blocks that use it.

### Publish to Braze

1. In the **Personalize** editor, click **Publish to Braze**.
2. The first time you publish a dynamic image, enter a **Content Block name**. The name is prefilled from the dynamic image. Optionally, click **Add a description**.
   ![Publish to Braze dialog with the Content Block name field prefilled](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208603/docs/integrations/braze_connect_publish_dialog.png "thumb:c_scale,w_450/dpr_2.0, width: 450")
3. Click **Publish**. The **Use it in Braze** panel shows the Liquid tags to copy.

> **INFO**: You can't change the Content Block name later. Braze never lets a Content Block name be changed or used again, even after you archive the Content Block. Names can have up to 94 characters.

Each publish creates or updates the following Content Blocks in Braze. The examples show the Liquid tags for a Content Block named `summer_sale`:

| Content Block | Contains | Use it in |
|---|---|---|
| Email tag: `{{content_blocks.${summer_sale}}}` | An image tag | Emails: a Custom Code (HTML) block, or **Personalization > Content Blocks** |
| Image URL tag: `{{content_blocks.${summer_sale_url}}}` | The image URL only | Push notifications, in-app messages, Content Cards, and the Dynamic URL field of an image block |
| Link tag: `{{content_blocks.${summer_sale_link}}}` | The target link only, when you set one | The image's link |

To change the image later, open it again with **Personalize for Braze** and click **Update in Braze**. Braze shows the new version in every message that uses the Content Block, from the next send. Messages already sent don't change.

> **NOTE**:
>
> **Copy dynamic image URL** and **Copy as Liquid** give you a copy that isn't linked to the Content Block, so a later publish doesn't update the messages that use it. Use a Content Block tag when you can.

### Use personalized content in a Braze message

* **Emails**: In the Braze drag-and-drop editor, add a Custom Code block and paste the email tag, or insert the Content Block from **Personalization > Content Blocks**. In an image block, paste the image URL tag in the Dynamic URL field.
  > **TIP**: If you've activated the [Chrome Extension](#use_the_cloudinary_chrome_extension), you can use the asset picker to select a dynamic image from your Cloudinary Media Library. No need to copy and paste the tag.
* **Push notifications, in-app messages, and Content Cards**: Paste the image URL tag in the image URL field.

> **INFO**: If you personalized with custom event properties, send the message from an action-based campaign or Canvas that the same custom event triggers, so the event properties are available.

Send a test message to a user with matching attributes to check the personalization.

### Track where a dynamic image is published

Select a dynamic image and open the app's **Links** section, or open the **Braze Content** tab on the asset's Manage page. Each Content Block shows its Liquid tags and its status in Braze:

* **Live**: The Content Block exists in Braze.
* **Missing in Braze**: The Content Block was deleted in Braze. Click **Disconnect**, publish the dynamic image again as a new Content Block with a new name, and replace the old tag in your messages. Braze doesn't let you reuse the old name.
* **Couldn't check**: Braze didn't respond. Try again later.

![Links section showing a live Content Block with its email tag, image URL tag, and dynamic image URL](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208605/docs/integrations/braze_connect_links.png "thumb:c_scale,w_650/dpr_2.0, width: 650")

## Use the Cloudinary Chrome Extension

The [Cloudinary Chrome Extension](chrome_extension_integration) lets you personalize dynamic images and pick published Content Blocks directly in the Braze drag-and-drop editor, without switching to the Cloudinary Console.

### Personalize a dynamic image in Braze

1. In the Braze drag-and-drop editor, select an image block.
2. Click the Cloudinary icon in the Dynamic URL field, then click **Pick a template** and select a dynamic image.
3. Personalize the dynamic image in the editor that opens (see [Personalize a dynamic image with Braze data](#personalize_a_dynamic_image_with_braze_data)).
4. Click **Apply** to write the dynamic image to the field, or **Cancel** to keep the field unchanged.

> **NOTE**: The editor warns you when the Braze workspace you're working in isn't the workspace connected to Braze Connect.

### Pick a published Content Block

1. In the Braze drag-and-drop editor, select an image block.
2. Click the Cloudinary icon in the image URL field, then click **Pick a Braze block**. The dynamic images that are [published from Cloudinary](#publish_to_braze) appear. 
3. Search by name, then select a Content Block.
   ![Select a Content Block grid in the Braze drag-and-drop editor, showing published dynamic images](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1794208607/docs/integrations/braze_select_content_block.png "thumb:c_scale,w_800/dpr_2.0, width: 800")

The extension adds the Content Block's image URL tag to the field, adds its link tag to the image link when it has one, and sets a placeholder image so the image appears at its correct size in the editor.

## Other ways to use Cloudinary with Braze

You can also reference Cloudinary assets in Braze manually, without the Braze Connect App. For complete instructions and examples, see the [Braze documentation for Cloudinary](https://www.braze.com/docs/partners/message_personalization/dynamic_content/visual_and_interactive_content/cloudinary).

### Select assets from Cloudinary DAM

Reference Cloudinary assets in your Braze campaigns using Cloudinary URLs. Assets can be selected based on public IDs, tags, or metadata attributes.

For detailed instructions, see [Select campaign assets through Cloudinary DAM](https://www.braze.com/docs/partners/message_personalization/dynamic_content/visual_and_interactive_content/cloudinary/?tab=cloudinary%20dam) in the Braze documentation.

![Braze - Asset selection](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/v1768129355/docs/integrations/braze_asset_selection.png "thumb: w_800,dpr_2, width:800")

### Convert videos to GIFs for email

Use Cloudinary transformation parameters to convert videos to GIF format for email campaigns. This ensures video content displays as animated GIFs in email clients, maintaining motion while ensuring broad compatibility.

![Braze - Video-to-GIF conversion](https://res.cloudinary.com/demo/video/upload/c_scale,w_500,e_loop/f_auto:animated,fl_lossy/samples/cld-sample-video.gif "thumb: w_500,dpr_2, width:500, with_code:false, with_url:false")

For detailed instructions, see [Convert videos to GIFs for emails](https://www.braze.com/docs/partners/message_personalization/dynamic_content/visual_and_interactive_content/cloudinary/?tab=convert%20videoes%20into%20gifs) in the Braze documentation.

### Dynamically select assets based on user attributes

Dynamically select different campaign assets for different users based on their Braze attributes such as language, customer tier, or location. This advanced integration method uses Cloudinary tags and Structured Metadata along with custom functions to automatically return the most relevant asset for each user.

For detailed instructions on setting up dynamic asset selection, see [Dynamically select campaign assets based on targeting attributes](https://www.braze.com/docs/partners/message_personalization/dynamic_content/visual_and_interactive_content/cloudinary/?tab=target%20attributes) in the Braze documentation.

### Generate personalized images with Liquid tags

Use Braze Liquid templating language to dynamically insert user attributes into Cloudinary transformation URLs. This allows you to generate unique media variants for each recipient.

For example, you can use Liquid tags to insert user data into Cloudinary's text overlay transformation parameter (`l_text`), creating personalized images that display the recipient's name, location, or other profile information.

For detailed instructions and examples, see [Personalized image generation](https://www.braze.com/docs/partners/message_personalization/dynamic_content/visual_and_interactive_content/cloudinary/?tab=personalized%20image%20generation) in the Braze documentation.

## Troubleshooting

| Issue | Solution |
|---|---|
| **Braze no longer accepts this key** | Braze deleted or rotated the key, or the key belongs to a different cluster than the REST endpoint. On the **Setup** tab, click **Replace the REST API key** and paste a valid key. |
| **Braze refused access to this workspace** | Braze refused the key for an account reason, such as an inactive workspace. Contact your Braze admin, then click **Check again** on the **Setup** tab. |
| **Some features are off**, or a missing permission notice | Add the missing permission to the key in Braze, then click **Check again** on the **Setup** tab. |
| The app doesn't accept the REST endpoint | Copy the REST endpoint from **Settings > APIs and Identifiers** in Braze, and make sure your Braze cluster is [supported](#rest_api_key_permissions). |
| The preview uses sample values | Give the key the `users.export.ids` permission, then search for a Braze user in the preview. |
| No custom attributes in the `@` menu | Give the key the `custom_attributes.get` permission. If Braze doesn't respond, the menu shows only the Braze default attributes until Braze responds again. |
| **Missing in Braze** in the **Links** section | The Content Block was deleted in Braze. Click **Disconnect**, publish the dynamic image again as a new Content Block with a new name, and replace the old tag in your messages. Braze doesn't let you reuse the old name. |
| Publishing is paused with the message **Couldn't check whether this dynamic image already has a Braze Content Block** | The app pauses publishing to prevent a duplicate Content Block. Try again in a few minutes. |
| **Someone published this Content Block again after you opened it** | Another user published a newer version. Publishing again replaces it. To keep their changes, reopen the dynamic image before you edit it. |
| A broken image in an image block in the Braze drag-and-drop editor | You pasted the email tag in the Dynamic URL field. Use the image URL tag in that field. |
| The image appears at an incorrect size in Braze or Outlook | Publish the Content Block again. In the Braze drag-and-drop editor, use **Pick a Cloudinary content block** so the image gets a placeholder. |
| A broken image in the preview or in sent messages, when an image field uses an event property or a catalog | Make sure **Fetched URL** isn't selected in the **Restricted image types** section of the product environment [Security](https://console.cloudinary.com/app/settings/security) page of the Console Settings. If you set **Allowed fetch domains**, add the domain that hosts the images. Make sure the image URL opens in a browser without signing in. |
| A message with a catalog image doesn't send | The catalog was renamed or deleted in Braze. Restore the catalog, or open the dynamic image with **Personalize for Braze**, select a different catalog, and click **Update in Braze**. |
| **Personalize works with dynamic images only** | Select a dynamic image created with the Cloudinary Figma Plugin, then select **Personalize for Braze**. |
| The app asks you to open it again from the Assets app | The app receives its context only when you open it from Cloudinary. Close the app, select the asset again in the Media Library, and reopen the app from the asset menu. |
| Promotion codes run out during testing | Braze uses up a promotion code for each test send. Use a promotion code list for testing. |

## Cloudinary Professional Services configuration support
The Braze integration is part of Cloudinary's [**Standard**](integrations#standard_integrations) Professional Services integration configuration package. 

If you need assistance setting up this integration and you're on an Enterprise plan with a professional services package in your contract, Cloudinary's professional services can help you set it up as part of your contracted package.

**Learn more: [Cloudinary Professional Services packages](integrations#cloudinary_professional_services_packages)**