> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tappd.io/llms.txt
> Use this file to discover all available pages before exploring further.
# In-App Message Bridge: Two-Way Data Communication
> Use the Bridge API to process button clicks and form submissions in in-app messages — track events, update profiles, and capture data in real time.
The In-App Message Bridge gives your in-app messages a direct line to the Tappd backend. When a user clicks a button or submits a form inside a message, the SDK automatically fires a request to the Bridge API, which processes the action — tracking an event, updating a profile, or capturing form data — and links it to the identified customer. You configure all of this in the Tappd dashboard; no custom code is required.
## How It Works
When a user interacts with an in-app message, the SDK follows this sequence:
The SDK detects a button click or form submission inside the rendered message.
The SDK constructs a request payload — including the action type, any form data, and the customer's identifiers — and sends it to the appropriate Bridge API endpoint.
The Tappd backend processes the action: tracking an event, updating profile attributes, or saving form data.
The customer is automatically identified from the included identifiers and linked to the action. If no matching customer exists, one is created automatically.
## Button Actions
Buttons in in-app messages can trigger four types of actions. You configure the action type for each button in the message editor inside the Tappd dashboard.
The `close` action dismisses the message when the button is clicked. No additional configuration or API call is required — the SDK handles this entirely client-side.
```javascript theme={null}
// Dashboard configuration:
// Action type: "close"
// No additional configuration needed
```
The `track_event` action fires a custom event and sends it to the Bridge API. Configure the event name and any event properties in the dashboard message editor.
```javascript theme={null}
// Dashboard configuration:
// Action type: "track_event"
// Event name: "button_clicked"
// Event properties: { source: "promo_banner", campaign: "summer_sale" }
```
The `update_profile` action writes one or more attributes to the customer's profile when the button is clicked. Define the `profileAttributes` object in the dashboard message editor.
```javascript theme={null}
// Dashboard configuration:
// Action type: "update_profile"
// Profile attributes: {
// "user_segment": "premium",
// "last_promotion_viewed": "summer_sale"
// }
```
The `link` action opens a URL when the button is clicked. This is handled entirely in the browser — the SDK navigates to the configured URL without making any Bridge API call.
```javascript theme={null}
// Dashboard configuration:
// Action type: "link"
// Link: "https://example.com/promo"
// Link behavior: "browser" (new tab) or "same_window"
```
Because the link action is client-side only, no event is tracked automatically. To also record the click, add a separate `track_event` button action, or use the form button combination pattern described below.
## Form Data Capture
Forms inside in-app messages capture user input and forward it to the Bridge API's `/capture` endpoint on submission. You control what happens to that data by setting a **submit action type** in the dashboard message editor.
Creates an event in Tappd and maps form field values to event properties.
```javascript theme={null}
// Dashboard configuration:
// Submit action type: "track_event"
// Event name: "newsletter_signup"
// Event properties mapping:
// "email_address" ← form field "email"
// "user_name" ← form field "name"
```
Combining Button Actions with Form Data
Combining Button Actions with Form Data
When a submit button lives inside a form block, the SDK automatically attaches the collected `formData` to the button's bridge action request. You don't need any additional configuration.
## Customer Identification
The Bridge API identifies customers using one or more of the following fields, all of which the SDK includes automatically in every request:
| Field | Source |
| ------------- | ------------------------------------ |
| `userId` | SDK `currentUserId` or `anonymousId` |
| `external_id` | Set via `identify()` call |
| `email` | Set via `identify()` call |
| `phone` | Set via `identify()` call |
At least one identifier must be present in every bridge request. If no matching customer is found, Tappd automatically creates one using the provided identifiers.
Call `identify()` before your messages are displayed to ensure clean customer linking:
```javascript theme={null}
tappd.identify("your_user_id", {
email: "user@example.com",
phone: "+1234567890"
});
```
## Examples
A promotional banner has a "Learn More" button. Clicking it fires a `track_event` action configured entirely in the dashboard.
**Dashboard configuration:**
* Action type: `track_event`
* Event name: `promo_banner_clicked`
* Event properties: `{ "campaign": "summer_sale", "position": "top" }`
When the user clicks the button, the SDK calls `/bridge/action` with `actionType: "track_event"` and the configured event name and properties. The event is created in Tappd immediately and linked to the identified customer.
A modal form collects email addresses and first names for a newsletter opt-in.
**Dashboard configuration:**
* Form fields: `email` (required), `name` (optional)
* Submit action type: `both`
* Event name: `newsletter_signup`
* Event properties mapping: `{ "email": "email" }`
* Profile attributes mapping: `{ "newsletter_subscribed": "true", "email": "email" }`
On submission, the SDK calls `/bridge/capture`. Tappd creates a `newsletter_signup` event and updates the customer profile with `newsletter_subscribed = true` and their email address — in a single API call.
A banner button upgrades the user's segment immediately when clicked, which can then gate them into a separate journey.
**Dashboard configuration:**
* Action type: `update_profile`
* Profile attributes: `{ "user_segment": "premium", "upgrade_date": "{{ date }}" }`
When the user clicks the button, the SDK calls `/bridge/action` with `actionType: "update_profile"`. Tappd writes the `user_segment` and `upgrade_date` attributes to the customer's profile. Other journeys listening for a `user_segment = "premium"` condition can then enroll the customer automatically.
## Best Practices
Call `identify()` before any in-app message is shown. Without at least one identifier, the Bridge API cannot link the action to a customer record.
Use consistent, descriptive event names such as `newsletter_signup` or `promo_banner_clicked`. Clear naming makes analytics and journey conditions easier to manage as your workspace grows.
Use the property/attribute **mapping** feature to rename form fields to semantically meaningful keys. For example, map the form field `name` to the profile attribute `full_name` so your data model stays clean.
Use the `both` submit action type when you want to record an event for analytics **and** update the customer profile at the same time — this is more efficient than chaining two separate actions.
The SDK handles bridge errors internally, but errors are visible in the browser console. Always test button actions and form submissions in a development environment — check the Network tab in DevTools to verify that `/bridge/action` and `/bridge/capture` requests are firing with the expected payloads.