# Aampe API Guide
Source: https://kb.aampe.com/api-guide/api-guide



## Overview

Aampe provides two main APIs that work together to power personalized experiences:

| API | Purpose | Base URL |
| - | - | - |
| **Content API** | Retrieve personalized content for Surfaces | `https://content.{region}.api.aampe.com` |
| **Ingestion API** | Send user events and properties to Aampe | `https://ingestion.{region}.api.aampe.com` |

Both APIs require authentication. [See Authentication](/api-guide/authentication) for how to authenticate with each.

***

## Content API (Surfaces)

The Content API provides programmatic access to retrieve personalized content for your users across different surfaces. This API powers real-time content decisioning based on your configured agents and optimization strategies.

**Base URL:** `https://content.{region}.api.aampe.com`

**Regions:** `us-east1` | `europe-west3` | `asia-southeast1`

**Authentication:** `X-API-Key` header (Surfaces API key)

### Use Cases

* Fetch personalized content for in-app Surfaces
* Get content assignments for a user at a specific surface
* Verify API connection via health endpoint

***

## Ingestion API (Data)

The Ingestion API allows you to send user events and property updates to Aampe in real time. Use it to stream behavioral data and user attributes that power personalization.

**Base URL:** `https://ingestion.{region}.api.aampe.com`

**Regions:** `us-east1` | `europe-west3` | `asia-southeast1`

**Authentication:** `Authorization: Bearer <Ingestion API Key>` header

### Use Cases

* Stream user events (clicks, purchases, page views) as they happen
* Update user properties (attributes, traits, preferences)
* Power real-time personalization and audience targeting

***

## Core Concepts

### Surfaces

Surfaces represent locations in your application where Aampe can deliver personalized content. Each surface has a unique UUID and associated configuration.

### Assignments

When you request content for a surface, Aampe returns an assignment — the specific content variant selected for that user at that moment, along with any configured alternates.

### Contact IDs

Your user identifiers that Aampe uses to personalize content delivery and track performance. Use the same contact IDs when sending events (Ingestion API) and requesting content (Content API).

***

## Response Formats

All API responses return JSON. Successful requests return appropriate HTTP status codes along with the requested data.

***

## Error Handling

Both APIs use standard HTTP status codes:

| Code | Description |
| - | - |
| 200 | Success (Content API) |
| 202 | Accepted (Ingestion API — request queued for processing) |
| 400 | Bad Request |
| 401 | Unauthorized (invalid or missing API key) |
| 422 | Validation Error |
| 429 | Rate Limited |
| 500 | Server Error |

***

## Getting Started

1. **Get your API keys** — Navigate to Integrations > API keys in the Aampe Dashboard
2. **Choose your API** — Use the Surfaces key for Content API, Ingestion key for Ingestion API
3. **Test your connection** — Use the health endpoint for Content API
4. **Start building** — Send events, update properties, and fetch personalized content

***

## Need Help?

Feeling stuck? We're here to help! Reach out to your customer service rep and we will help you build something amazing with Aampe.


# API Keys
Source: https://kb.aampe.com/api-guide/api-keys

Where can I find my API keys?

## Aampe API Keys

To find your API keys, navigate to **Integrations > API keys**

<img alt="Composer Api Key Page Pn" />

You'll find two API keys

* **Ingestion API key:** this is for sending data to Aampe via the [Aampe Streaming API](/developer-guide/data-ingest/data-sources/streaming-aampe-api).
* **Surfaces API key:** this is for pulling personalized content from Aampe for [Surfaces](/developer-guide/surfaces/surfaces-embed).

<Warning>
  Please keep your API keys secure.
</Warning>


# Authentication
Source: https://kb.aampe.com/api-guide/authentication



Aampe has two APIs with **different authentication methods**. Use the correct method for the API you're calling.

***

## Quick Reference

| API | Header | Example | Base URL |
| - | - | - | - |
| **Content API** (Surfaces) | `X-API-Key` | `X-API-Key: your_surfaces_api_key` | `https://content.api.aampe.com` |
| **Ingestion API** (Data) | `Authorization: Bearer` | `Authorization: Bearer your_ingestion_api_key` | `https://ingestion.{region}.api.aampe.com` |

***

## Content API Authentication

Use the **Surfaces API key** when calling the Content API (e.g., Get Surface Content, Health).

<ParamField type="string">
  Your Surfaces API key for the Content API
</ParamField>

**Base URL:** `https://content.api.aampe.com`

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
    'https://content.api.aampe.com/health' \
    -H 'X-API-Key: YOUR_SURFACES_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://content.api.aampe.com/health",
      headers={"X-API-Key": "YOUR_SURFACES_API_KEY"}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://content.api.aampe.com/health', {
    headers: {
      'X-API-Key': 'YOUR_SURFACES_API_KEY'
    }
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

***

## Ingestion API Authentication

Use the **Ingestion API key** when sending events or property updates to Aampe.

<ParamField type="string">
  Bearer token with your Ingestion API key. Format: `Authorization: Bearer YOUR_INGESTION_API_KEY`
</ParamField>

**Base URL:** `https://ingestion.{region}.api.aampe.com` (e.g., `us-east1`, `europe-west3`, `asia-southeast1`)

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    'https://ingestion.us-east1.api.aampe.com/v1/events' \
    -H 'Authorization: Bearer YOUR_INGESTION_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "contact_id": "user123",
      "event_name": "button_click",
      "timestamp": 1638360000
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://ingestion.us-east1.api.aampe.com/v1/events",
      headers={
          "Authorization": "Bearer YOUR_INGESTION_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "contact_id": "user123",
          "event_name": "button_click",
          "timestamp": 1638360000
      }
  )
  print(response.status_code)  # 202 = Accepted
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://ingestion.us-east1.api.aampe.com/v1/events', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_INGESTION_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      contact_id: 'user123',
      event_name: 'button_click',
      timestamp: 1638360000
    })
  });
  console.log(response.status);  // 202 = Accepted
  ```
</RequestExample>

***

## Obtaining an API Key

To find your API keys, navigate to **Integrations > API keys**

<img alt="Composer Api Key Page Pn" />

You'll find two API keys:

* **Surfaces API key:** For pulling personalized content from Aampe for [Surfaces](/developer-guide/surfaces/surfaces-embed)
* **Ingestion API key:** For sending data to Aampe via the [Aampe Streaming API](/developer-guide/data-ingest/data-sources/streaming-aampe-api)

### Key Generation Steps

1. Log into your Aampe Dashboard
2. Navigate to System settings → Integrations → Aampe Endpoint
3. Copy the API Key (hidden)

***

## Configure API Playground

To test endpoints interactively:

1. Click the "Configure" button on any API endpoint page
2. Enter your API key in the appropriate field:
   * **Content API endpoints:** Use `X-API-Key` field
   * **Ingestion API endpoints:** Use Bearer token field
3. Your key will be saved locally in your browser for this session
4. Try making requests directly from the documentation

<Note>
  Your API key is stored locally in your browser and never sent to our documentation servers. It's only used for direct API calls to the Aampe API.
</Note>

***

## Security Best Practices

<Warning>
  Never expose your API key in client-side code or public repositories. Use environment variables or secure secret management for your keys. Rotate keys if you suspect they've been compromised.
</Warning>

***

## Next Steps

<CardGroup>
  <Card icon="heart-pulse" href="/api-reference/health/get-health" title="Test the Health Endpoint">
    Verify your Content API connection is working
  </Card>

  <Card icon="layer-group" href="/api-reference/surface/get-surface-content" title="Get Surface Content">
    Retrieve personalized content for users
  </Card>

  <Card icon="arrow-right-to-bracket" href="/api-reference/aampe-ingest" title="Aampe Events Ingestion">
    Stream events to Aampe
  </Card>

  <Card icon="user-pen" href="/api-reference/aampe-property-update" title="Aampe Property Update">
    Update user properties
  </Card>
</CardGroup>


# Audit Log
Source: https://kb.aampe.com/api-guide/composer-api/audit-log

Read the history of configuration changes in your Aampe account: who made each change, when, and what changed.

The audit log records configuration changes in your Aampe account (who made each one, when, and for most kinds of item the values before and after), and you can read it with three endpoints on the public API.

## Authentication

Send your Aampe API key in the `X-API-KEY` header on every request (see [Authentication](/api-guide/composer-api/authentication)). All endpoints are read-only `GET` requests under `https://composer.api.aampe.com/api`, and the key's user needs read access to the account.

```bash theme={null}
curl https://composer.api.aampe.com/api/activity-logs/account \
  -H "X-API-KEY: <your API key>"
```

Each request only ever returns your own account's history. Times are UTC, in ISO 8601 format.

***

## What's Recorded

Each change is one entry: who made it, when, what changed and, for most kinds of item, the values before and after. Entries are never edited or removed after they're written.

| What changed | `object_type` | Filed under (`target_type`) |
| - | - | - |
| Labels and label weights | `Label` | `Label` itself, for a label's creation |
| A label's component type | `LabelVariantType` | `Label` |
| Audiences and their filters | `Audience` | — |
| Triggers and their rules | `CompoundTrigger` | — |
| Frequency caps | `FrequencyLimit` | `CompoundTrigger`, when the cap belongs to a trigger |
| Default frequency caps, for the account or for one trigger | `DefaultFrequencyLimits` | `CompoundTrigger`, when the default belongs to a trigger |
| Reward functions, their target events and weight overrides | `RewardFunction` | — |
| A message created, or its settings or status changed | `Formula` | `Formula` itself |
| A label added to or removed from a message | `FormulaLabel` | `Formula` |
| A message's audience set | `FormulaAudience` | `Formula` |
| An alternate added to or removed from a message | `Variant` | `Formula` |

<Note>
  Some changes are recorded without values for now: their `data` is `null`, so an entry says who changed which item and when, but not what changed. This covers every `Formula`, `FormulaLabel`, `FormulaAudience`, `Variant` and `LabelVariantType` entry, and a label's creation. Tag changes and edits to an alternate's text aren't recorded yet.
</Note>

In every entry:

| Field | Meaning |
| - | - |
| `id` | The entry's id |
| `verb` | `CREATE`, `UPDATE`, `DELETE` or `ARCHIVE` |
| `object_type`, `object_id`, `object_name` | The item that changed, and its current name if it has one |
| `target_type`, `target_id`, `target_name` | The item it's filed under, if any |
| `user_id`, `user_name` | Who made the change |
| `created_at` | When (UTC) |
| `data` | `before`, `after` and `changed_fields`: the item's values before and after, and which fields differ |
| `transaction_id` | The save the change was part of. Changes made in one save share it. |
| `save_count`, `first_activity_id`, `first_created_at` | See [Combined saves](#combined-saves) |

`before` is `null` for a creation. Use `verb` to tell a deletion or archive apart: most items are kept when deleted or archived, so `after` holds the item with `deleted_at` or `archived_at` set, and `after` is `null` only when the item is removed outright. Ids of events and of audience-filter attributes and operators come with their names alongside, for example `event_id` with `event_name` and `event_code`. Snapshots in the examples on this page are excerpts. Older entries, from before the audit log launched, can have a simpler `data` shape without `before` and `after`.

***

## Account Log

```
GET /activity-logs/account
```

Returns every change in your account, newest first, one page at a time. All parameters are optional and combine with AND.

| Parameter | Type | Meaning |
| - | - | - |
| `start` | ISO 8601 datetime | Only changes at or after this time. Without a timezone, UTC is assumed. |
| `end` | ISO 8601 datetime | Only changes before this time. Must not be earlier than `start`. |
| `scope` | type, e.g. `Formula` | One kind of item and everything filed under it. `scope=Formula` covers messages with the labels, audiences and alternates filed under them; `scope=CompoundTrigger` covers triggers with their frequency caps. |
| `object_type` | type | Only this kind of item, matched exactly. |
| `user_id` | integer | Only changes by this person. [Who made changes](#who-made-changes) lists the ids. |
| `target_model` + `target_id` | type + id | One item's history: changes to it and to everything filed under it. Give both or neither. |
| `surface_id` | UUID | Every message on one surface. |
| `ungrouped` | boolean, default `false` | One entry per recorded change instead of [combined saves](#combined-saves). |
| `page` | integer, default `1` | Page number, from 1. |
| `per_page` | integer, default `10` | Entries per page. `0` returns only the count. |

For example, the changes Ana made in September:

```bash theme={null}
curl "https://composer.api.aampe.com/api/activity-logs/account?user_id=42&start=2026-09-01T00:00:00Z&end=2026-10-01T00:00:00Z&per_page=50" \
  -H "X-API-KEY: <your API key>"
```

The response wraps the entries with paging details:

```json theme={null}
{
  "items": [
    {
      "id": 9182,
      "verb": "UPDATE",
      "object_type": "FrequencyLimit",
      "object_id": "6f1c2a0e-8d3b-4c55-9a51-2b7e0c4d9f10",
      "object_name": null,
      "target_type": null,
      "target_id": null,
      "target_name": null,
      "user_id": 42,
      "user_name": "Ana Lopez",
      "created_at": "2026-09-14T10:02:11",
      "transaction_id": 55410,
      "save_count": 1,
      "first_activity_id": 9182,
      "first_created_at": "2026-09-14T10:02:11",
      "data": {
        "before": {"max_messages": 3, "time_frame": "daily_limit", "aggregation_type": "channel", "aggregation_value": "email"},
        "after": {"max_messages": 5, "time_frame": "daily_limit", "aggregation_type": "channel", "aggregation_value": "email"},
        "changed_fields": ["max_messages"]
      }
    }
  ],
  "total_count": 128,
  "page": 1,
  "per_page": 50,
  "total_pages": 3,
  "has_prev": false,
  "has_next": true,
  "prev_page": null,
  "next_page": 2
}
```

***

## Combined Saves

Settings are often saved several times in quick succession, so the log combines a person's back-to-back saves of the same item into one entry. Saves are combined when they are by the same person, on the same item, and each within 10 minutes of the one before. Another person's save in between starts a new entry.

A combined entry shows the net change:

* `data.before` is the item before the first save, `data.after` is the item after the last.
* `changed_fields` lists only fields that end up different. A field edited and then put back isn't listed, so an entry can show `[]`: no net change.
* `save_count` is how many saves it combines; `first_activity_id` and `first_created_at` are the first save's. `id` and `created_at` are the last save's.
* A single save has `save_count` 1, and its `first_*` fields equal its own.

Only changes to existing items combine. A creation, deletion or archive is always its own entry, and message changes aren't combined yet. Combining never crosses the edges of a `start`/`end` range, and never changes what's stored: add `ungrouped=true` to see every save on its own.

***

## One Item's History

```
GET /activity-logs
```

Returns every change to one item and to everything filed under it, oldest first, as a plain list with no paging. It uses the same entries and [combined saves](#combined-saves) as the account log.

| Parameter | Required | Meaning |
| - | - | - |
| `target_model` | Yes | The item's type, e.g. `Formula`. An unknown type returns an empty list. |
| `target_id` | Yes | The item's id |
| `ungrouped` | No | `true` for one entry per save |

```bash theme={null}
curl "https://composer.api.aampe.com/api/activity-logs?target_model=Formula&target_id=1204" \
  -H "X-API-KEY: <your API key>"
```

<Tip>
  For large histories, prefer the account log with `target_model` and `target_id`, which pages and can be filtered by date and person.
</Tip>

***

## Who Made Changes

```
GET /activity-logs/account/users
```

Lists everyone who has changed your account, for filtering the log by `user_id`. It includes people who have since left or been deactivated, and Aampe staff who changed your configuration on your behalf.

| Parameter | Meaning |
| - | - |
| `start`, `end` | Only people with changes in this range, as on the account log |
| `scope` | Only people who changed this kind of item, as on the account log |

```json theme={null}
[
  {"user_id": 42, "user_name": "Ana Lopez", "email": "ana@example.com"},
  {"user_id": 57, "user_name": "Sam Chen", "email": null}
]
```

`user_name` is the name on the person's latest change, or their current name if that change has none. `email` is `null` when their user account no longer exists. The list is sorted by name.

***

## Errors

| Status | When |
| - | - |
| `401` | The API key is missing or invalid |
| `403` | The key's user can't read this account |
| `422` | A parameter is invalid: an unknown type, `start` after `end`, or only one of `target_model`/`target_id`. On [one item's history](#one-items-history), an unknown `target_model` returns an empty list instead. |

Errors return a JSON body with a `detail` message.


# Authentication
Source: https://kb.aampe.com/api-guide/composer-api/authentication

How to obtain and use an API key to authenticate with the Aampe Composer API.

## Overview

The Composer API uses API key authentication. Every request must include your API key in the `X-API-KEY` header.

```python theme={null}
import requests

response = requests.get(
    "https://composer.api.aampe.com/api/formulas",
    headers={"X-API-KEY": "YOUR_API_KEY"},
)
```

***

## Getting Your API Key

1. In the Aampe dashboard, navigate to **System setup → Integrations → API Keys**
2. Click **+ Create new**
3. Copy the generated key immediately — it will not be shown again

<Warning>
  Store your API key somewhere safe as soon as you create it. The dashboard will not show the full key again after you leave the page.
</Warning>

***

## Using the Key

Pass the key in the `X-API-KEY` request header on every call:

```python theme={null}
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",  # required for POST/PUT requests with a body
}
```

Requests without a valid key, or with a key that has been revoked, receive a `401 Unauthorized` response.

***

## Best Practices

* Store keys in environment variables or a secrets manager — never hard-code them in source files
* Use a separate key for each environment (production, staging, local development)
* Rotate keys immediately if you suspect compromise
* Contact [support@aampe.com](mailto:support@aampe.com) to revoke or regenerate a key


# Create a Formula
Source: https://kb.aampe.com/api-guide/composer-api/formulas/create-formula

Complete guide to creating a formula with labeled alternates using the Composer API.

## Overview

A **formula** is a reusable message template that drives a campaign. It defines the channel (push, SMS, email, etc.), message slots, and the labeled alternates Aampe uses to personalize each send.

Formulas start in **Draft** status and must go through a review/approval workflow before going live.

***

## Core Concepts

### Slots vs. Alternates

The structure defines **slots** — one position per section (header, body). It does **not** list all alternates inline. Alternates for a slot are linked by a shared `component_id`.

```
Formula structure
└── section (header)
│     └── ONE variant node  ← slot; node id = component_id for this slot
└── section (body)
      └── ONE variant node  ← slot; node id = component_id for this slot

Variants (separate)
├── component_id = header_slot_id  label = Calm       ← alternate 1
├── component_id = header_slot_id  label = Breathe    ← alternate 2
├── component_id = header_slot_id  label = Stillness  ← alternate 3
├── component_id = body_slot_id    label = Science    ← alternate 1
└── component_id = body_slot_id    label = Sleep      ← alternate 2
```

### Component IDs — two distinct concepts

There are two different IDs called "component ID" and confusing them is the most common source of errors:

| Name | Type | Source | Used for |
| - | - | - | - |
| **Component type ID** | UUID | `GET /component-types` → `id` | `componentId` in structure nodes; identifies what *kind* of slot this is |
| **Component instance ID** | UUID (self-generated) | You create it with `uuid.uuid4()` | Variant node `id` in the structure; `component_id` when creating variants — links all alternates to the same slot |

### Seed variant

When you put text in a variant node's `children[0].text`, that text is automatically created as the **first alternate** for that slot. Do not re-submit it via the bulk endpoint — it will create a duplicate.

### componentId — component type UUIDs

The `componentId` in a structure variant node is the component type UUID from `GET /component-types`:

| Component type | `data_key` | UUID |
| - | - | - |
| Offering | `Offering` | `8e3f0698-7564-4522-9c07-49686667c0b4` |
| Value Proposition | `ValueProposition` | `72150aa9-6b20-4d95-9659-0c05701ef7de` |
| Call to Action | `CallToAction` | `8c0b9b73-b305-4f93-b41f-bde62cebac98` |
| Greeting | `Greeting` | `43cb8b03-4503-48ed-a09a-9110fd260e3d` |
| Incentive | `Incentive` | `27eb65fc-75ec-4a38-8576-03672ee6c562` |
| Tone | `Tone` | `0fb13b80-d999-48c3-9ca9-3975c0af0bf7` |

Fetch the live list at any time:

```python theme={null}
response = requests.get(
    "https://composer.api.aampe.com/api/component-types",
    headers={"X-API-KEY": "YOUR_API_KEY"},
)
CT = {ct["data_key"]: ct["id"] for ct in response.json()}
```

### Labels and `variant_type`

When associating a label with a variant, the label's `variant_type` must exactly match the `data_key` of the component type.

<Warning>
  A label created with `variant_type: "Offering"` **cannot** be used on a `ValueProposition` variant, and vice versa. Create separate labels for each component type you need.
</Warning>

***

## Creation Flow (4 Steps)

### Step 1 — Create the formula

Create the formula with `structure: []`. The message structure is set separately on the message-content record in Step 3.

```python theme={null}
import uuid, requests

BASE_URL = "https://composer.api.aampe.com/api"
headers  = {"X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json"}

CT_OFFERING          = "8e3f0698-7564-4522-9c07-49686667c0b4"
CT_VALUE_PROPOSITION = "72150aa9-6b20-4d95-9659-0c05701ef7de"

response = requests.post(f"{BASE_URL}/formulas", headers=headers, json={
    "name": "My Formula",
    "message_type": "push",
    "structure": [],
    "labels": [
        {"label_id": 101, "variant_type": "Offering",          "component_type_id": CT_OFFERING},
        {"label_id": 102, "variant_type": "Offering",          "component_type_id": CT_OFFERING},
        {"label_id": 103, "variant_type": "ValueProposition",  "component_type_id": CT_VALUE_PROPOSITION},
    ],
})
response.raise_for_status()
formula_id = response.json()["id"]
```

### Step 2 — Fetch the message-content ID

When a formula is created, the API automatically creates a message-content record for it. Fetch its ID:

```python theme={null}
mc_resp = requests.get(
    f"{BASE_URL}/formulas/{formula_id}/message-contents",
    headers=headers,
)
mc_resp.raise_for_status()
message_content_id = mc_resp.json()[0]["id"]
```

### Step 3 — Set the structure

Pre-generate a UUID for each slot. That UUID is the **component instance ID** — it links all of that slot's alternates together and must be referenced when creating variants in Step 4.

The text in `children[0].text` is the **seed variant** — it is automatically created as the first alternate for that slot.

```python theme={null}
# Pre-generate component instance IDs (one per slot)
header_component_id = str(uuid.uuid4())
body_component_id   = str(uuid.uuid4())

put_resp = requests.put(
    f"{BASE_URL}/message-contents/{message_content_id}",
    headers=headers,
    json={
        "id": message_content_id,
        "structure": [
            {
                "kind": "section",
                "sectionType": "header",
                "children": [
                    {
                        "id":            header_component_id,  # ← you generated this
                        "kind":          "variant",
                        "variantType":   "Offering",
                        "componentId":   CT_OFFERING,          # ← component type UUID
                        "labelId":       101,                  # ← label for the seed variant
                        "children":      [{"text": "Your first header alternate"}],
                    }
                ],
            },
            {
                "kind": "section",
                "sectionType": "body",
                "children": [
                    {
                        "id":            body_component_id,
                        "kind":          "variant",
                        "variantType":   "ValueProposition",
                        "componentId":   CT_VALUE_PROPOSITION,
                        "labelId":       103,
                        "children":      [{"text": "Your first body alternate"}],
                    }
                ],
            },
        ],
        "deeplink": None,
        "deeplink_dataset_field_id": None,
    },
)
put_resp.raise_for_status()
```

<Warning>
  Each slot must have exactly **one** variant node in the structure. Do not add multiple sibling variant nodes — they render as separate inline components, not as alternatives for the same slot.
</Warning>

### Step 4 — Add the remaining alternates

Add all remaining alternates using either `POST /variants/create/bulk` (multiple at once) or `POST /variants` (one at a time). Use the component instance IDs you generated in Step 3. Do **not** include the seed variants — they were already created in Step 3.

```python theme={null}
bulk_resp = requests.post(
    f"{BASE_URL}/variants/create/bulk",
    headers=headers,
    json=[
        # Additional header alternates (seed "Your first header alternate" was already created)
        {"component_id": header_component_id, "content": "Your second header alternate", "label_id": 102},
        {"component_id": header_component_id, "content": "Your third header alternate",  "label_id": 101},
        # Additional body alternates
        {"component_id": body_component_id,   "content": "Your second body alternate",   "label_id": 103},
    ],
)
bulk_resp.raise_for_status()
```

After this call the formula has 3 header alternates × 2 body alternates = **6 unique message combinations**.

***

## Endpoint Reference

### `POST /formulas`

Creates a new formula.

| Field | Type | Required | Description |
| - | - | - | - |
| `message_type` | string | Yes | `push`, `sms`, `whatsapp`, `web_push`, `in_app_banner`, `in_app_fullpage`, `email`, `content_cards`, `surface` |
| `name` | string | No | Display name (must be unique within `message_type`) |
| `structure` | array | Yes | Always pass `[]` — structure is set on the message-content in a separate call |
| `labels` | array | No | Formula-level label associations |
| `topic_id` | uuid | No | Topic this formula belongs to |
| `audience_id` | uuid | No | Restrict delivery to a segment |
| `send_start` | datetime | No | ISO 8601 start of delivery window |
| `is_controlled_message` | boolean | No | Controlled A/B test (default: `false`) |

**`labels` item:**

```python theme={null}
{"label_id": 101, "variant_type": "Offering", "component_type_id": CT_OFFERING}
```

***

### `PUT /message-contents/{id}`

Sets the message structure and seed variants on the message-content record.

**Variant node fields:**

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | uuid | Yes | Component instance ID — a UUID you generate; used as `component_id` when creating variants |
| `kind` | string | Yes | Always `"variant"` |
| `variantType` | string | Yes | Component type `data_key` (e.g. `"Offering"`) |
| `componentId` | uuid | Yes | Component type UUID from `GET /component-types` |
| `labelId` | integer | No | Label for the seed variant |
| `children` | array | Yes | `[{"text": "seed text"}]` — becomes the first alternate for this slot |

***

### `POST /variants/create/bulk`

Creates multiple variants in a single request. Use this when you have several alternates to add at once.

| Field | Type | Required | Description |
| - | - | - | - |
| `component_id` | uuid | Yes | The component instance ID from the structure (the `id` you generated) |
| `content` | string | Yes | The alternate's message copy |
| `label_id` | integer | No | Label for this alternate |

### `POST /variants`

Creates a single variant. Use this for one-off additions. Accepts the same fields as a bulk item, plus `formula_id` and `message_content_id` for context.

| Field | Type | Required | Description |
| - | - | - | - |
| `component_id` | uuid | Yes | The component instance ID from the structure |
| `content` | string | Yes | The alternate's message copy |
| `label_id` | integer | No | Label for this alternate |
| `formula_id` | integer | No | The formula this variant belongs to |
| `message_content_id` | uuid | No | The message-content this variant belongs to |

***

## Formula Lifecycle

```
Draft → Review → Approved → Live / Scheduled / Expired
                     ↓
                 Archived
```

Use the state-transition endpoints (`/review`, `/approve`, `/archive`) to progress a formula.


# Concepts and System Objects
Source: https://kb.aampe.com/api-guide/composer-api/formulas/overview

What formulas are and how they map to the messages you see in Composer.

## What Is a Formula?

A **formula** is the API's internal representation of a message in Composer. Every message you see listed in the Composer UI corresponds to exactly one formula under the hood.

When you open a message in Composer, browse its alternates, or trigger a send — you are interacting with a formula and the variants attached to it.

***

## What a Formula Contains

A formula captures everything needed to describe a message:

| Property | Description |
| - | - |
| `name` | The display name shown in the Composer UI |
| `message_type` | The channel — push, SMS, email, in-app, etc. |
| `status` | The current lifecycle state — Draft, Review, Approved, Live, etc. |
| `labels` | Tags that describe the formula's overall intent and which component types they apply to |
| `topic_id` | The topic this message belongs to |
| `audience_id` | An optional segment filter controlling who can receive it |
| `send_start` | Optional delivery window start |

The message structure and all actual copy live in the **message-content** record, which is a separate object automatically created alongside the formula.

***

## Message-Content

Every formula has exactly one **message-content** record. This is where the structure (the slot layout) and all variants (the actual copy) live — not on the formula itself.

The formula is the container: name, channel, status, targeting. The message-content is the payload: what the message looks like and what it says.

When you create a formula, the API automatically creates a message-content record alongside it. You then set the structure and variants on that record directly.

```
Formula  →  created via POST /formulas
               └── message-content  →  auto-created, fetched via GET /formulas/{id}/message-contents
                     ├── structure  →  set via PUT /message-contents/{id}
                     └── variants   →  created via POST /variants or POST /variants/create/bulk
```

You'll need the message-content ID for most content operations:

| Endpoint | What it does |
| - | - |
| `GET /formulas/{id}/message-contents` | Returns the message-content ID |
| `PUT /message-contents/{id}` | Sets or replaces the structure and seed variants |
| `GET /message-contents/{id}` | Reads the current structure |
| `GET /message-contents/{id}/variants` | Lists all variants |

***

## Structure, Variants, Components, and Alternates

These four concepts work together to describe a message and all the ways it can be personalized.

### Structure and Slots

The message-content's `structure` defines the skeleton of the message — what slots exist (header, body, etc.) and what type of content each slot holds. It does not contain the message text itself.

Each slot is one variant node in the structure. The node's `id` is the **component instance ID** — a UUID you generate that identifies the slot and ties all its alternates together.

### Variants

A **variant** is a single piece of message copy for a slot. It has a label, a text value, and a `component_id` pointing to the slot it belongs to. Every slot has at least one variant — the **seed variant**, which is set inline in the structure when you first define it.

### Components

A **component** is a slot, identified by its component instance ID. In the Composer UI, a component appears as a single content block within a message that shows how many alternates it has. All variants sharing the same `component_id` belong to the same component.

### Alternates

**Alternates** are the multiple variants grouped under a single component. If a header slot has three variants (Calm, Breathe, Stillness), those three are the alternates for that component. Aampe picks one alternate per component per send.

```
Formula
└── message-content
      ├── structure
      │     ├── slot: header  (component instance id = X)  ← seed text auto-creates first alternate
      │     └── slot: body    (component instance id = Y)
      └── variants
            ├── component_id = X, label = Calm       ← alternate 1 for header (seed)
            ├── component_id = X, label = Breathe    ← alternate 2 for header
            ├── component_id = X, label = Stillness  ← alternate 3 for header
            ├── component_id = Y, label = Science    ← alternate 1 for body (seed)
            └── component_id = Y, label = Sleep      ← alternate 2 for body
```

This formula produces `3 × 2 = 6` unique message combinations.

***

## The Two Component IDs

There are two distinct IDs named "component ID" in the system. Confusing them is the most common source of errors:

| Name | Type | Source | Used in |
| - | - | - | - |
| **Component type ID** | UUID | `GET /component-types` → `id` | `componentId` in structure nodes; identifies what *kind* of content a slot holds |
| **Component instance ID** | UUID | You generate with `uuid.uuid4()` | Variant node `id` in the structure; `component_id` when creating variants |

The component type ID says *what kind* of slot this is (e.g. Offering, CallToAction). The component instance ID says *which specific slot* in this message a variant belongs to.

***

## Formula Lifecycle

```
Draft → Review → Approved → Live / Scheduled / Expired
                     ↓
                 Archived
```

Only formulas in **Approved** or **Live** status are eligible for delivery. Formulas stay in **Draft** until explicitly submitted for review.


# Update a Formula
Source: https://kb.aampe.com/api-guide/composer-api/formulas/update-formula

Learn how to update the settings and content of an existing formula.

## Overview

You can update a formula's name, targeting settings, schedule, and more using the update endpoint. To replace the message structure or add new alternates, use the message-content endpoints.

***

## Updating Formula Metadata

```
POST /formulas/{formula_id}/update
```

All fields are optional — only include the fields you want to change.

| Field | Type | Description |
| - | - | - |
| `name` | string | The display name of the formula |
| `deeplink` | string | Deep link URL for the message CTA |
| `send_start` | datetime | ISO 8601 datetime when delivery becomes eligible |
| `send_stop` | datetime | ISO 8601 datetime when delivery stops |
| `send_start_date` | date | Date-only version of send start |
| `send_stop_date` | date | Date-only version of send stop |
| `is_controlled_message` | boolean | Whether this is a controlled A/B test message |
| `timezone` | string | IANA timezone string (e.g. `"America/New_York"`) |
| `audience_id` | uuid | Target audience segment |
| `topic_id` | uuid | Topic association |
| `tags` | array of uuids | Replace all tag associations |
| `labels` | array | Replace formula-level label associations |
| `compound_trigger_id` | uuid | Compound trigger rule for delivery |
| `dataset_id` | integer | Dataset used for user-level personalization |
| `override_provider_frequency_limits` | boolean | Bypass provider-level send frequency caps |
| `additional_metadata` | object | Free-form metadata |

### Example: Rename a formula and set a schedule

```python theme={null}
import requests

BASE_URL  = "https://composer.api.aampe.com/api"
headers   = {"X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json"}
FORMULA_ID = 215

response = requests.post(
    f"{BASE_URL}/formulas/{FORMULA_ID}/update",
    headers=headers,
    json={
        "name":      "Welcome Back Campaign — Spring",
        "send_start": "2026-04-10T09:00:00Z",
        "send_stop":  "2026-04-30T23:59:59Z",
        "timezone":   "America/New_York",
    },
)
response.raise_for_status()
print(f"Updated: {response.json()['name']}")
```

***

## Replacing the Message Structure

To replace what a formula's message looks like — its slots and seed variants — update the message-content directly:

```
PUT /message-contents/{message_content_id}
```

<Warning>
  This is a **full replacement**. Include every section and slot you want to keep — anything omitted will be removed.
</Warning>

### Step 1 — Get the message-content ID

```python theme={null}
mc_resp = requests.get(
    f"{BASE_URL}/formulas/{FORMULA_ID}/message-contents",
    headers=headers,
)
mc_resp.raise_for_status()
message_content_id = mc_resp.json()[0]["id"]
```

### Step 2 — Replace the structure

Pre-generate a component instance ID for each slot. The text in `children[0].text` becomes the seed variant (first alternate) for that slot.

```python theme={null}
import uuid

CT_OFFERING = "8e3f0698-7564-4522-9c07-49686667c0b4"
CT_CTA      = "8c0b9b73-b305-4f93-b41f-bde62cebac98"

header_component_id = str(uuid.uuid4())
body_component_id   = str(uuid.uuid4())

response = requests.put(
    f"{BASE_URL}/message-contents/{message_content_id}",
    headers=headers,
    json={
        "id": message_content_id,
        "structure": [
            {
                "kind": "section",
                "sectionType": "header",
                "children": [
                    {
                        "id":          header_component_id,
                        "kind":        "variant",
                        "variantType": "Offering",
                        "componentId": CT_OFFERING,
                        "children":    [{"text": "Spring is here, {{first_name}}!"}],
                    }
                ],
            },
            {
                "kind": "section",
                "sectionType": "body",
                "children": [
                    {
                        "id":          body_component_id,
                        "kind":        "variant",
                        "variantType": "CallToAction",
                        "componentId": CT_CTA,
                        "children":    [{"text": "Check out what's new."}],
                    }
                ],
            },
        ],
        "deeplink": None,
        "deeplink_dataset_field_id": None,
    },
)
response.raise_for_status()
```

After replacing the structure, add more alternates via `POST /variants/create/bulk` using the component instance IDs.

***

## Adding Alternates to an Existing Formula

To add alternates to a formula without touching the structure, first fetch the existing component instance IDs from the message-content, then bulk-create:

```python theme={null}
# Get the existing structure to find component instance IDs
mc_detail = requests.get(
    f"{BASE_URL}/message-contents/{message_content_id}",
    headers={"X-API-KEY": "YOUR_API_KEY"},
)
mc_detail.raise_for_status()
structure = mc_detail.json()["structure"]

# Build a map: variantType → component instance ID
slot_ids = {}
for section in structure:
    for child in section.get("children", []):
        if child.get("kind") == "variant":
            slot_ids[child["variantType"]] = child["id"]

# Add new alternates
requests.post(
    f"{BASE_URL}/variants/create/bulk",
    headers={"X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json"},
    json=[
        {"component_id": slot_ids["Offering"], "content": "New spring deals await.", "label_id": 104},
        {"component_id": slot_ids["Offering"], "content": "Your seasonal picks are here.", "label_id": 105},
    ],
).raise_for_status()
```

***

## Finding a Formula ID

Formulas are listed by lifecycle category and message type:

```python theme={null}
import requests

BASE_URL = "https://composer.api.aampe.com/api"
headers  = {"X-API-KEY": "YOUR_API_KEY"}

for category in ("Draft", "Live"):
    resp = requests.get(
        f"{BASE_URL}/formulas/category/{category}",
        headers=headers,
        params={"message_type": "push"},
    )
    resp.raise_for_status()
    for f in resp.json():
        print(f"[{category}] ID: {f['id']}  Name: {f['name']}")
```


# Manage Labels
Source: https://kb.aampe.com/api-guide/composer-api/labels/manage-labels

How to list, create, and use labels with the Composer API.

## List Existing Labels

Before creating new labels, fetch the ones that already exist. Labels rarely change — you can cache this list for the duration of a session.

```python theme={null}
import requests

BASE_URL = "https://composer.api.aampe.com/api"
headers  = {"X-API-KEY": "YOUR_API_KEY"}

response = requests.get(f"{BASE_URL}/labels", headers=headers)
response.raise_for_status()

labels = response.json()
for label in labels:
    if label["archived_at"] is None:  # skip archived labels
        print(f"[{label['variant_type']}] {label['id']}: {label['label_name']}")
```

**Response:**

```json theme={null}
[
  {
    "id": 101,
    "label_name": "Curiosity",
    "label_description": "Piques interest and invites exploration",
    "variant_type": "Offering",
    "archived_at": null
  },
  {
    "id": 102,
    "label_name": "Urgency",
    "label_description": "Creates time pressure",
    "variant_type": "Offering",
    "archived_at": null
  }
]
```

To look up labels by component type:

```python theme={null}
from collections import defaultdict

by_type = defaultdict(list)
for label in labels:
    if label["archived_at"] is None:
        by_type[label["variant_type"]].append(label)

# e.g. by_type["Offering"] → list of all Offering labels
```

***

## Create a Label

```
POST /labels
```

```python theme={null}
response = requests.post(
    f"{BASE_URL}/labels",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "label_name":        "Calm",
        "label_description": "Gentle, reassuring tone",
        "variant_type":      "Offering",
    },
)
response.raise_for_status()
label_id = response.json()["id"]
print(f"Created label: {label_id}")
```

| Field | Type | Required | Description |
| - | - | - | - |
| `label_name` | string | Yes | Human-readable name |
| `label_description` | string | No | What this label means |
| `variant_type` | string | Yes | The component type `data_key` this label applies to — must match exactly (e.g. `"Offering"`, `"ValueProposition"`) |

<Note>
  Create one label per semantic concept per component type. If you need a `"Calm"` label for both Offering and ValueProposition variants, create two separate labels — one with each `variant_type`.
</Note>

***

## Using Label IDs

Once you have label IDs, they appear in three places:

### 1. Formula creation — declare which labels the formula uses

```python theme={null}
requests.post(f"{BASE_URL}/formulas", headers=headers, json={
    "name": "My Formula",
    "message_type": "push",
    "structure": [],
    "labels": [
        {"label_id": 101, "variant_type": "Offering",         "component_type_id": CT_OFFERING},
        {"label_id": 102, "variant_type": "Offering",         "component_type_id": CT_OFFERING},
        {"label_id": 103, "variant_type": "ValueProposition", "component_type_id": CT_VALUE_PROPOSITION},
    ],
})
```

### 2. Structure definition — label the seed variant

```python theme={null}
{
    "id":          component_instance_id,
    "kind":        "variant",
    "variantType": "Offering",
    "componentId": CT_OFFERING,
    "labelId":     101,                    # ← label for this seed variant
    "children":    [{"text": "Your copy here"}],
}
```

### 3. Variant creation — label each alternate

```python theme={null}
requests.post(f"{BASE_URL}/variants/create/bulk", headers=headers, json=[
    {"component_id": component_instance_id, "content": "Your copy",       "label_id": 101},
    {"component_id": component_instance_id, "content": "More urgent copy", "label_id": 102},
])
```


# Labels
Source: https://kb.aampe.com/api-guide/composer-api/labels/overview

What labels are and how they classify variants in Composer.

## What Is a Label?

A **label** is a semantic tag that classifies a variant — it captures the intent, tone, or strategy behind a piece of message copy. Examples: `Curiosity`, `Urgency`, `Calm`, `Social Proof`.

Labels are how Aampe learns which type of message resonates with which user. Over time, Aampe associates each user with the labels they respond to and selects variants accordingly.

***

## Labels and Component Types

Every label is scoped to a specific **component type** via its `variant_type` field. A label with `variant_type: "Offering"` can only be used on Offering variants — it cannot be applied to a `ValueProposition` or `CallToAction` variant.

This means you need separate labels for each component type you use in a formula.

<Warning>
  If you try to attach a label to a variant whose component type doesn't match the label's `variant_type`, the API will return an error.
</Warning>

***

## How Labels Flow Through the System

```
Label (id, variant_type, label_name)
  │
  ├─► Formula-level label association
  │     {"label_id": 101, "variant_type": "Offering", "component_type_id": "..."}
  │     Declares which labels this formula uses per component type
  │
  └─► Variant-level label assignment
        {"component_id": "...", "content": "...", "label_id": 101}
        Tags each individual alternate with its semantic meaning
```

Labels appear in two places:

* **On the formula** (`labels` array at creation time) — declares which labels are associated with each component type in this formula
* **On each variant** (`label_id` at variant creation time) — tags the specific alternate with its meaning

***

## Label Fields

| Field | Type | Description |
| - | - | - |
| `id` | integer | The label's unique ID — used as `label_id` everywhere |
| `label_name` | string | Human-readable name (e.g. `"Curiosity"`) |
| `label_description` | string | What this label means |
| `variant_type` | string | The component type `data_key` this label applies to |
| `archived_at` | datetime or null | If set, the label is archived and should not be used |

See [Manage Labels](./manage-labels) for how to fetch and create labels.


# Multilanguage Formulas
Source: https://kb.aampe.com/api-guide/composer-api/languages/multilanguage

How to create formulas with content in multiple languages.

## How Multilanguage Works

Each formula can have one version of its content per language. These language versions are separate **message-content** records — each with its own structure and variants.

```
Formula
├── message-content (English — default)
│     ├── structure
│     └── variants: "Find your calm", "Breathe and begin", ...
└── message-content (German)
      ├── structure
      └── variants: "Finde deine Ruhe", "Atme und beginne", ...
```

When Aampe sends a message, it selects the message-content that matches the user's language. Each language version is personalized independently — Aampe learns label preferences per language.

***

## Step 1 — List Available Languages

```python theme={null}
import requests

BASE_URL = "https://composer.api.aampe.com/api"
headers  = {"X-API-KEY": "YOUR_API_KEY"}

response = requests.get(f"{BASE_URL}/languages", headers=headers)
response.raise_for_status()

for lang in response.json():
    default = " (default)" if lang["is_default"] else ""
    print(f"{lang['id']}  {lang['name']}{default}")
```

**Response:**

```json theme={null}
[
  {
    "id": "4abd0bdd-9d63-44de-b9d1-affcd3f61bfc",
    "name": "Default Language",
    "is_default": true,
    "status": "active"
  }
]
```

***

## Step 2 — Create a Language (if it doesn't exist)

```python theme={null}
response = requests.post(
    f"{BASE_URL}/languages",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "name":        "German",
        "description": "German language",
    },
)
response.raise_for_status()
german_language_id = response.json()["id"]
```

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Display name for the language |
| `description` | string | No | Optional description |

***

## Step 3 — Create the Formula

Create the formula as normal. The API automatically creates a message-content for the **default language**. You will add the German message-content separately.

```python theme={null}
import uuid

CT_OFFERING          = "8e3f0698-7564-4522-9c07-49686667c0b4"
CT_VALUE_PROPOSITION = "72150aa9-6b20-4d95-9659-0c05701ef7de"

headers_json = {**headers, "Content-Type": "application/json"}

formula_resp = requests.post(f"{BASE_URL}/formulas", headers=headers_json, json={
    "name":         "My Multilanguage Formula",
    "message_type": "push",
    "structure":    [],
})
formula_resp.raise_for_status()
formula_id = formula_resp.json()["id"]

# Default language message-content is auto-created
mc_resp = requests.get(f"{BASE_URL}/formulas/{formula_id}/message-contents", headers=headers)
mc_resp.raise_for_status()
default_mc_id = mc_resp.json()[0]["id"]
```

***

## Step 4 — Set the Default Language Content

Pre-generate component instance IDs. These identify the slots for the default language — **each language uses its own component instance IDs**.

```python theme={null}
en_header_cid = str(uuid.uuid4())
en_body_cid   = str(uuid.uuid4())

requests.put(
    f"{BASE_URL}/message-contents/{default_mc_id}",
    headers=headers_json,
    json={
        "id": default_mc_id,
        "structure": [
            {
                "kind": "section",
                "sectionType": "header",
                "children": [{
                    "id":          en_header_cid,
                    "kind":        "variant",
                    "variantType": "Offering",
                    "componentId": CT_OFFERING,
                    "labelId":     101,
                    "children":    [{"text": "Find your calm"}],
                }],
            },
            {
                "kind": "section",
                "sectionType": "body",
                "children": [{
                    "id":          en_body_cid,
                    "kind":        "variant",
                    "variantType": "ValueProposition",
                    "componentId": CT_VALUE_PROPOSITION,
                    "labelId":     103,
                    "children":    [{"text": "5 minutes a day reduces stress hormones 30%."}],
                }],
            },
        ],
        "deeplink": None,
        "deeplink_dataset_field_id": None,
    },
).raise_for_status()

# Add remaining English alternates
requests.post(f"{BASE_URL}/variants/create/bulk", headers=headers_json, json=[
    {"component_id": en_header_cid, "content": "Breathe and begin",              "label_id": 102},
    {"component_id": en_header_cid, "content": "A moment of stillness awaits",   "label_id": 101},
    {"component_id": en_body_cid,   "content": "Fall asleep faster and wake up restored.", "label_id": 103},
]).raise_for_status()
```

***

## Step 5 — Add a New Language Version

Create a new message-content for German by posting with `formula_id` and `language_id`:

```python theme={null}
de_mc_resp = requests.post(
    f"{BASE_URL}/message-contents",
    headers=headers_json,
    json={
        "formula_id":  formula_id,
        "language_id": german_language_id,
    },
)
de_mc_resp.raise_for_status()
german_mc_id = de_mc_resp.json()["id"]
```

Then set its structure and variants the same way as the default language — using new component instance IDs:

```python theme={null}
de_header_cid = str(uuid.uuid4())
de_body_cid   = str(uuid.uuid4())

requests.put(
    f"{BASE_URL}/message-contents/{german_mc_id}",
    headers=headers_json,
    json={
        "id": german_mc_id,
        "structure": [
            {
                "kind": "section",
                "sectionType": "header",
                "children": [{
                    "id":          de_header_cid,
                    "kind":        "variant",
                    "variantType": "Offering",
                    "componentId": CT_OFFERING,
                    "labelId":     101,
                    "children":    [{"text": "Finde deine Ruhe"}],
                }],
            },
            {
                "kind": "section",
                "sectionType": "body",
                "children": [{
                    "id":          de_body_cid,
                    "kind":        "variant",
                    "variantType": "ValueProposition",
                    "componentId": CT_VALUE_PROPOSITION,
                    "labelId":     103,
                    "children":    [{"text": "5 Minuten täglich senken Stresshormone um 30%."}],
                }],
            },
        ],
        "deeplink": None,
        "deeplink_dataset_field_id": None,
    },
).raise_for_status()

requests.post(f"{BASE_URL}/variants/create/bulk", headers=headers_json, json=[
    {"component_id": de_header_cid, "content": "Atme und beginne",                          "label_id": 102},
    {"component_id": de_header_cid, "content": "Ein Moment der Stille erwartet dich",       "label_id": 101},
    {"component_id": de_body_cid,   "content": "Schlaf schneller ein und wache erholt auf.", "label_id": 103},
]).raise_for_status()
```

***

## Reading Back All Language Versions

```python theme={null}
all_mc = requests.get(
    f"{BASE_URL}/formulas/{formula_id}/message-contents",
    headers=headers,
).json()

for mc in all_mc:
    lang_id  = mc["language_id"]
    mc_id    = mc["id"]
    variants = requests.get(f"{BASE_URL}/message-contents/{mc_id}/variants", headers=headers).json()
    print(f"Language: {lang_id}  —  {len(variants)} variants")
```

***

## Key Points

* The default language's message-content is auto-created with the formula — do not create it manually
* Each language version uses its own component instance IDs (the UUIDs you generate per slot)
* Labels and component types are shared across languages — you do not need to recreate them
* Each language version is personalized independently by Aampe


# Aampe Events Ingestion
Source: https://kb.aampe.com/api-reference/aampe-events-ingestion

/api-guide/ingestion-openapi.json post /v1/events
Handle an event coming from an Aampe Webhook.



# Aampe Property Update
Source: https://kb.aampe.com/api-reference/aampe-property-update

/api-guide/ingestion-openapi.json post /v1/properties
Handle property updates coming from Aampe identify calls.
Expects data in the exact format needed for publishing.



# Get surface content
Source: https://kb.aampe.com/api-reference/surface/get-surface-content

/api-guide/content-openapi.json get /v1/surface/content
Returns one result per surface that could be resolved, in the same order as requested.
Surfaces that cannot be resolved are omitted from the list.



# Archiving Message Groups
Source: https://kb.aampe.com/archiving-message-groups



## Overview

Need a campaign to take a breather? Maybe you're running an experiment, setting up a holdout, or rethinking the copy. Aampe doesn't have a pause button, and it doesn't need one: **archiving a message works as a clean, reversible pause.**

The message steps out of rotation, and your agents keep everything they've learned about it. When you're ready, un-archive it and they pick up right where they left off.

## How to pause a campaign

1. Find the message group(s) you want to pause under your Live messages
2. Click the orange Archive icon on the right of each Message Group to archive it
   <img alt="Image" />
3. When asked for confirmation, click "Archive" again

<img alt="Image" />

4. Make sure your newly-archived message now shows up under "Archived" in the Message Group list

That's it. Archived messages drop out of rotation and stop being served, so your agents won't pick them for anyone until you bring them back.

> **Tip:** Jot down which messages you archived and why (your experiment plan is a good spot). Future you will thank you when it's time to resume.

## Why archiving makes a good pause

* **It stops the sends.** The message leaves active rotation, so the campaign goes quiet.
* **It's fully reversible.** Nothing is deleted. Un-archive whenever you're ready.
* **Your agents don't forget.** Everything they've learned about the message stays intact while it's paused.

## How to resume

1. Find the archived messages in the message list.
2. Un-archive each one.

Your campaign is back in rotation, and **there's no cold start**. Agents don't have to re-explore the message from scratch. They carry on from what they already know.


# BigQuery data share
Source: https://kb.aampe.com/developer-guide/aampe-data/data-share-bigquery

Query your Aampe data share in Google BigQuery with a service account

Aampe delivers your data share into Google BigQuery as read-only tables. Use a service account. That account is the identity Aampe grants, and the identity your jobs use to query.

You pay for the queries you run. There is no storage charge for the shared tables. Tables refresh daily. Column definitions are on the [table descriptions](/developer-guide/aampe-data/data_share_tables) page.

## Send this to Aampe

* Service account email, in the form `aampe-data-share@YOUR_PROJECT_ID.iam.gserviceaccount.com`
* The BigQuery region you query from, such as `US` or `us-central1`

Aampe grants that service account and sends you a Google Cloud link to the listing.

## 1. Prepare your project

In the Google Cloud project where you want the tables:

1. Turn on [billing](https://console.cloud.google.com/billing).
2. Enable the [BigQuery API](https://console.cloud.google.com/apis/library/bigquery.googleapis.com).
3. Enable the [Analytics Hub API](https://console.cloud.google.com/apis/library/analyticshub.googleapis.com).

## 2. Create a service account

1. Open [Service accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) for that project.
2. Click **Create service account**.
3. Name it `aampe-data-share`.
4. Copy the email address.

## 3. Grant roles on your project

On **your** project, grant that service account:

* **BigQuery User** (`roles/bigquery.user`), so it can create the linked dataset and run queries
* **BigQuery Data Viewer** (`roles/bigquery.dataViewer`), so it can read the shared tables

1. Open [IAM](https://console.cloud.google.com/iam-admin/iam).
2. Click **Grant access**.
3. Paste the service account email.
4. Add both roles and save.

## 4. Subscribe once

Wait until Aampe confirms the share is ready, then open the link Aampe sends. Subscribing creates a read-only linked dataset in your project.

The link path contains four values:

`projects/PUBLISHER_PROJECT/locations/LOCATION/dataExchanges/DATA_EXCHANGE_ID/listings/LISTING_ID`

A service account cannot click **Subscribe** in the browser. Run the command below once as that service account. The person who runs it needs **Service Account Token Creator** (`roles/iam.serviceAccountTokenCreator`) on the service account.

```bash theme={null}
SA=aampe-data-share@YOUR_PROJECT_ID.iam.gserviceaccount.com

curl -sS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account="$SA")" \
  -H "Content-Type: application/json" \
  "https://analyticshub.googleapis.com/v1/projects/PUBLISHER_PROJECT/locations/LOCATION/dataExchanges/DATA_EXCHANGE_ID/listings/LISTING_ID:subscribe" \
  -d '{
    "destinationDataset": {
      "datasetReference": {
        "projectId": "YOUR_PROJECT_ID",
        "datasetId": "aampe"
      },
      "location": "LOCATION"
    }
  }'
```

`PUBLISHER_PROJECT`, `LOCATION`, `DATA_EXCHANGE_ID`, and `LISTING_ID` come from the link. `YOUR_PROJECT_ID` is your project. `datasetId` is the name of the dataset in your project. Set `location` to the region you sent Aampe.

## 5. Query

```sql theme={null}
SELECT *
FROM `YOUR_PROJECT_ID.aampe.TABLE_NAME`
LIMIT 10;
```

<Warning>
  If this project sits inside a VPC Service Controls perimeter, add ingress and egress rules for BigQuery and Analytics Hub before you subscribe. Otherwise the subscribe call and later queries are blocked.
</Warning>


# Aampe Data Share
Source: https://kb.aampe.com/developer-guide/aampe-data/data-share-overview

Make Aampe data part of your data science toolkit

## What is a Data Share?

A data share is a mechanism for accessing external datasets directly within your data warehouse environment.

Instead of receiving data through file transfers, APIs, or ETL pipelines, data shares appear as read-only tables in your warehouse that you can query alongside your own data. The tables remain stored in Aampe's infrastructure but are queryable from your environment.

**Key Characteristics:**

* **No ETL Latency** - Data refreshes in real-time as production systems update
* **Easy Access** - Tables appear directly in your warehouse environment as read-only objects
* **No Storage Costs** - You're responsible only for compute resources used when querying. There are no ingestion or storage costs.

## What Data Does Aampe Share?

See our page [with detailed table and column descriptions](/developer-guide/aampe-data/data_share_tables).

## How Do I Activate Data Sharing?

Contact your Aampe representative to turn on a data share.

For Google BigQuery, create a service account in your project and send us the email. The steps are on the [BigQuery](/developer-guide/aampe-data/data-share-bigquery) page.

Once the share is active, the tables appear in your project as read-only. You can join them with your own data using standard SQL.

## Supported Destinations

* Amazon S3
* Azure Blob Storage
* Google Cloud Storage
* Amazon Redshift
* [Google BigQuery](/developer-guide/aampe-data/data-share-bigquery)
* Databricks
* Snowflake

## Change Management

<Warning>
  Backwards compatible changes may happen at any time (e.g. new columns).

  \
  Breaking changes (removing columns or tables, renaming columns) will be communicated in advance.
</Warning>

## Data Share FAQs

<Accordion title="Does activating a data share cost extra? " icon="sparkles">
  No. Data sharing is currently part of our standard offering. 
</Accordion>

<Accordion title="How often do the tables update?" icon="sparkles">
  The tables update daily.
</Accordion>

<Accordion title="How are the user propensities computed?" icon="sparkles">
  For each user, we simulate hundreds of future potential messages given the current Bayesian priors for each label. We repeat this process for value propositions, offerings, tone, etc. and then report the percent of messages with each label. 
</Accordion>


# Table Descriptions
Source: https://kb.aampe.com/developer-guide/aampe-data/data_share_tables

See details on the Aampe datasets

## Overview

Aampe is ready to share granular data about users, messages, and other events straight to your data warehouse. While there are many potential applications, customers generally find these datasets useful for

* Reporting and monitoring
* Causal inference and offline message evaluation
* Inputs into various AI models (llm prompts, ML features, etc.)

Expand the tables below to see column descriptions, example queries, and more.

## Active Tables

<Accordion title="AAMPE_CONTACT_PROFILES">
  Aampe generates a profile for each user that has interacted with an agent. \
  \
  The **propensity** for each label within a given label set reflects the agent's estimate for how often that label will outperform the other label options. (If I were to simulate 100 messages from Aampe for each user, how often would the agent choose each label?)

  | Column | Type | Description |
  | :- | :-: | :- |
  | `contact_id` | STR | Unique person identifier |
  | `propensities_offering` | ARRAY | User propensities for each **offering** |
  | `propensities_valueproposition` | ARRAY | User propensities for each **value proposition** |
  | `propensities_tone` | ARRAY | User propensities for each **tone** label |
  | `propensities_timing` | ARRAY | User propensities for each **timing** window |
  | `propensities_channel` | ARRAY | User propensities for each **channel** |

  The propensity arrays contain scores that sum to one and look like the following:

  ```text theme={null}
  [
  	{"label_id":5678, "propensity":0.5432, "label_name":"Food"},
  	{"label_id":6789, "propensity":0.4568, "label_name":"Travel"}
  ]
  ```

  ### User Profiles - Example Queries

  <CodeGroup>
    ```rust BigQuery theme={null}
    // for a given user, what's their propensity for each offering label

    SELECT 
      contact_id, 
      label_name, 
      propensity
    FROM aampe_contact_profiles,
    UNNEST(propensities_offering)
    WHERE contact_id = '1a2b3c4d'
    ORDER BY propensity DESC
    ```
  </CodeGroup>
</Accordion>

<Accordion title="AAMPE_MESSAGE_EVENTS">
  Agents save the details of each decision they make, including the parameters of the statistical models, sampling results, and the final decision result.\
  \
  With a row for every message event, this table helps with day-to-day reporting and monitoring. It also plays a key role in offline analysis and causal inference.

  | Column | <Tooltip>Type</Tooltip> | Description |
  | :- | :-: | :- |
  | `aampe_message_id (pk)` | STR | Aampe's unique identifier for a message event |
  | `provider_message_id` | STR | The event identifier from the message provider (e.g. Braze). Not available for all message providers. |
  | `contact_id` | STR | Unique person identifier |
  | `message_timestamp` | TIMESTAMP | When the message was sent |
  | `received_timestamp` | TIMESTAMP | When the message provider confirmed a successful delivery. |
  | `message_timezone` | STR | Timezone for `message_timestamp` |
  | `message_formula_id` | INT | Numerical Identifier for a message formula (called "messages" in the Aampe composer.) |
  | `message_formula_name` | STR | Name for a message formula (called "messages" in the Aampe composer) |
  | `message_content` | STRUCT | `title`: title of message<br />`body`: main message content |
  | `message_diversity_score` | FLOAT | Computed by Aampe. When several message alternates are available within a chosen set of labels, we send the alternate with the best message diversity score. This ensures messages vary their language even if the offering or value proposition is the same. |
  | `reward_baseline` | FLOAT | Computed by Aampe. This is the reward Aampe expects to observe if the agent does nothing. |
  | `channel_assignment_id` | STR | Unique decision ID for channel selection |
  | `channel` | STR | Channel |
  | `timing_assignment_id` | STR | Decision ID for timing selection (potentially a joint decision with channel) |
  | `timing_label_assigned` | STR | `label_set`: the decision being made (typically "day\_time" for timing decisions)<br />`label_id`: numeric ID for the timing label<br />`label_name`: human-friendly name for the timing label<br />`score`: Model score for timing-decision model<br />`assignment_type`: description of the model output (is it exploratory or not) |
  | `trigger_id` | STR | Identifier for trigger associated with message. There is always a trigger id, even if the message was not triggered by an event. |
  | `messaging_type` | STR | Either "controlled" (scheduled message blasts). Or "automated" which means an agent decided the message to send and when to send it. |
  | `copy_assignment_id` | STR | Decision ID for message copy elements |
  | `tags` | ARRAY | Array of tags associated with the message event |
  | `message_to` | STR | Delivery to address |
  | `message_from` | STR | Delivery from address |
  | `message_date` | DATE | Date of `message_timestamp` - for easier partitioning when needed |
  | `click_action` | STR | Type: what happens when the message is clicked (e.g. deeplink)<br />Value: deeplink URL or other api call resulting from click |
  | `image_url` | STR | Image URL (when not included in `message_content`) |
  | `reward_delta` | FLOAT | The extent to which the message event outperformed expectations (given by `reward_baseline`). |
  | `trigger_name` | STR | Name of trigger (or else "no trigger") |
  | `copy_assignment` | STR | `action_set_family`: the agents decision set (typically "copy" for copy decisions) <br />`action_set`: Label groups such as value proposition, offering, ... <br />`action_name`: the specific label<br />`probability`: mean-concentration parameter of the Beta distribution for the chosen action<br />`aggregated_signal`: another mean-concentration parameter of the Beta distribution for the chosen action |

  ### Aampe Messages - Example Queries

  <CodeGroup>
    ```rust BigQuery theme={null}
    // for each message, what were the labels, label parameters, etc.?

    SELECT 
        aampe_message_id,
        message_date,
        action_set,
        action_name as label_name,
        probability,
        aggregated_signal
    FROM 
        aampe_message_events,
        UNNEST(copy_assignment)
    WHERE 
        aampe_message_id = '1234-asdf'
    ```
  </CodeGroup>
</Accordion>

<Accordion title="AAMPE_MESSAGE_ATTEMPTS">
  Not all messages are delivered successfully. Some messages fail between Aampe and the message provider. Other messages fail between the message provider and the customer. The `aampe_message_attempts` table provides message-level details on which messages were delivered successfully.

  | Column | <Tooltip>Type</Tooltip> | Description |
  | :- | :-: | :- |
  | `aampe_message_id (pk)` | STR | Aampe's unique identifier for a message event |
  | `provider_message_id` | STR | The event identifier from the message provider (e.g. Braze). Not available for all message providers. |
  | `contact_id` | STR | Unique person identifier |
  | `message_timestamp` | TIMESTAMP | When the message was sent |
  | `message_date` | DATE | Date of `message_timestamp` - for easier partitioning when needed |
  | `message_timezone` | STR | Timezone for `message_timestamp` |
  | `channel` | STR | Channel |
  | `message_formula_id` | INT | Numerical Identifier for a message formula (called "messages" in the Aampe composer.) |
  | `message_formula_name` | STR | Name for a message formula (called "messages" in the Aampe composer) |
  | `trigger_id` | STR | Identifier for trigger associated with message. There is always a trigger id, even if the message was not triggered by an event. |
  | `copy_assignment_id` | STR | Decision ID for message copy elements |
  | `message_content` | STRUCT | `title`: title of message<br />`body`: main message content |
  | `tags` | ARRAY | Array of tags associated with the message event |
  | `delivery_status` | STR | Whether or not the message was successfully delivered |
</Accordion>

<Accordion title="AAMPE_CONTACT_EVENTS_PARTIAL">
  This table contains events delivered to Aampe from the message provider. Depending on your message provider, channels, and Aampe settings Aampe, these events may include:

  * `aampe_clicked`
  * `aampe_email_clicked`
  * `aampe_email_opened`
  * `aampe_email_unsubscribed`
  * `aampe_email_bounced`

  This is a subset of all Aampe events visible in the composer, hence the `_partial` suffix. 

  | Column | <Tooltip>Type</Tooltip> | Description |
  | :- | :-: | :- |
  | `event_instance_id (pk)` | STR | Aampe's unique identifier for an event occurance event |
  | `event_name` | STR | The event name (as seen in the Aampe composer). |
  | `contact_id` | STR | Unique person identifier |
  | `event_timestamp` | TIMESTAMP | When the message was sent |
  | `event_date` | DATE | Date of `event_timestamp` |
  | `metadata` | STRUCT | Numerical Identifier for a message formula (called "messages" in the Aampe composer.) |
</Accordion>


# Recommender System
Source: https://kb.aampe.com/developer-guide/cms-integration/recommender-systems

A combination of user behavior data with catalog information to deliver personalized product recommendations.

## Introduction

Aampe's recommender system **combines user behavior data with catalog information** to deliver personalized product recommendations in push notifications and surfaces. The system also allows a cool-down period to be set, so if a recommendation is made today, N days can elapse before the recommendation can be used again in a communication. The customer can control how long or short this cool-down period is.

The process starts with catalog data ingestion through CSV files, data aggregators, or cloud buckets, capturing essential product details like IDs, names, prices, and deep-links. This data can then be leveraged using CMS filters to write messages specifically for sub-categories in your catalog. **Aampe offers different recommenders for all your use-case ideas, e.g., abandoned cart, browse abandonment, new products, and more**.

The recommendation engine tracks user consumption patterns and creates an item-to-item transition matrix based on factors like sequence frequency and timing. It generates personalized recommendations by matching user history against this matrix, selecting high-scoring items while avoiding previous recommendations.

Implementation is straightforward - recommendations are inserted into messages through a simple interface during content creation. The system continuously learns from user interactions, improving recommendation accuracy over time while effectively handling both popular and niche products across large catalogs.

## Integration Steps

Our dedicated developers will be with you every step of the way to ensure that the integration is smooth and easy. Here’s a step-by-step overview of the process:

### Prepare your CMS data: Ensure your product catalog includes essential fields such as:

* Item ID/SKU
* Item name
* Item price (Optional for in-depth analytics)
* Other relevant catalog properties you wish to include in your messaging (e.g., brand, category, description)

Depending on the recommender you want to use, we require more information. Example: For abandoned cart messages, we would need details of items in both the add\_to\_cart event and the purchase event to process them using CMS. Our developers will go through the use case with you to define what information is needed per use case.

### Choose your integration method:

* Cloud bucket integration

### Verify the integration: Work with our support team to ensure the data is being correctly received and processed.

### Additional Information

**Content Types:** Aampe's recommender works with various content types, including products, blog posts, articles, lessons, videos, and more. **Support**: Integration support is available for any questions or assistance.


# Data Security and Privacy
Source: https://kb.aampe.com/developer-guide/data-ingest/data-ingest-help/data-security-and-privacy



## Data Security FAQs

<Accordion title="Where does Aampe store our data?" icon="sparkles">
  Each customer has a dedicated pipeline that pulls data into Aampe and applies the necessary transformations to fit our data model. Aampe uses a multi-tenant architecture to ensure customer datasets remain separate.

  We are able to co-locate BigQuery instances into any [Google Cloud location](https://cloud.google.com/about/locations) to satisfy any needs on data storage location.
</Accordion>

<Accordion title="Is our data used for global model training?" icon="sparkles">
  No. Aampe follows a strict multi-tenant data and model architecture. No data is ever shared between customers. 
</Accordion>

<Accordion title="Where and how are models fine-tuned?" icon="sparkles">
  Aampe doesn’t operate around a central model that undergoes training or fine-tuning cycles. There’s no global predictive function, shared parameter space, or batch-training pipeline.  \
  \
  Because of that, there is nothing in the system that resembles a model checkpoint, a retraining schedule, or a fine-tuning workflow. Each agent learns continuously from its own interactions with a single user. Learning is online, individual, and incremental, driven entirely by the feedback generated in that user’s own history.
</Accordion>

<Accordion title="Does Aampe need PII?" icon="sparkles">
  Many customers use Aampe without sending any PII. Since Aampe is not the final sender of any message, we do not need user names or emails. The Aampe message uses placeholders that are populated by the final-mile sender.

  At times certain user attributes (e.g. state of residence) are helpful to create audiences. Many customers choose to send limited PII on an as-needed basis.
</Accordion>

<Accordion title="What is Aampe's data retention policy?" icon="sparkles">
  Data is retained by Aampe throughout the contract period. This enables embedded charts and analytics, auditing, and offline policy evaluation.\
  \
  For more information, please visit our [trust center](http://trust.aampe.com/).
</Accordion>

<Accordion title="What precautions does Aampe take to keep our data secure?" icon="sparkles">
  All data is encrypted at rest and in transit. Access to data is restricted to authorized personnel only. Aampe conducts regular security audits.

  Security certificates and reports are available upon request.
</Accordion>

<Accordion title="Does Aampe follow an AI security framework?" icon="sparkles">
  Yes. Our AI security program is aligned with the OWASP AI Security & Privacy Top 10 for vulnerability identification and mitigation, and we incorporate the NIST AI Risk Management Framework (AI RMF) into our governance and risk-assessment processes.
</Accordion>

<Accordion title="How does Aampe prevent model poisoning, adversarial attacks, and prompt injection?" icon="sparkles">
  Aampe agents don’t share a global model, and there’s no promptable inference surface that a user can manipulate. Each agent learns only from observed behavioral signals through its own causal-learning loop. This architecture reduces Aampe's exposure to these kinds of attacks.
</Accordion>

<Accordion title="How does Aampe monitor for anomalous behavior?" icon="sparkles">
  Aampe maintains continuous monitoring across all production systems to detect anomalous or high-risk behavior, including unexpected API calls, traffic spikes, or abnormal system activity.

  * API Behavior Analytics: We track request patterns, rate anomalies, unauthorized endpoints, and abnormal payloads. Threshold- and behavior-based alerts trigger on deviation from established baselines.
  * Traffic & Volume Monitoring: Real-time metrics detect sudden spikes, unusual burst patterns, or other deviations in system load.
  * Centralized Logging & Telemetry: Aampe uses GCP Cloud Logging for centralized log collection and an OpenTelemetry-compatible platform for telemetry and alerting. Logs are aggregated, immutable, access-controlled, and continuously monitored in alignment with our SOC 2–compliant security program.
  * System Health & Drift Checks: Automated checks validate system integrity, operational stability, and drift from expected behavior.
</Accordion>

<Accordion title="What are Aampe's escalation paths for a software incident?" icon="sparkles">
  Aampe employs the following procedures in response to high-severity anomalies:

  * Automated Safeguards: High-severity anomalies trigger automatic containment (rate limiting, endpoint blocking, or disabling an action/service).
  * On-Call Engineering Escalation: Alerts route to the 24/7 on-call SRE/security team, who investigate and mitigate under defined SLAs.
  * Security Incident Response: Events meeting incident criteria are escalated to our Security Incident Response Team following SOC 2–aligned incident response procedures.
  * Customer Notification: If an incident affects customer data, notifications follow contractual and regulatory obligations.
</Accordion>


# How Often Should We Send Data to Aampe?
Source: https://kb.aampe.com/developer-guide/data-ingest/data-ingest-help/how-often-data-sync

Is once a day enough? Do things need to update in real time? 

## The Choice is Yours

You have full control over how often Aampe syncs data from your integrated data sources. The right frequency depends on your specific use case and how you want to balance responsiveness with potential cost and complexity.

### **Lower Frequency Syncs**

Syncing once or twice a day is low complexity and still provides Aampe agents with the data they need to learn. Audiences based on user events or attributes may not reflect real-time changes, but many messages can still be effective. This approach works well when:

* Customer data changes slowly
* You're running campaigns based on stable attributes (demographics, historical patterns)
* Cost efficiency is a priority

Aampe's learning still works effectively and adapts to data that is backfilled or otherwise delayed. That said, **Aampe recommends syncing no less than once a day.**

### **Higher Frequency Syncs**

Syncing more frequently (e.g. hourly batch or real-time via API) creates more accurate audiences, enabling real-time or near-real-time personalization. This enables time-sensitive use cases like:

* Abandoned carts or browse recovery
* Location-based triggers
* Flash sales or limited-time offers

This comes at the potential cost of higher compute and may require additional engineering resources.

### **Syncing Fast and Slow**

Many customers start with a daily sync and then sync more often as needed. Sometimes this comes through more frequent batch syncs. Other times this comes from sending specific events via API in addition to a daily sync. \
\
The sync frequency doesn't affect Aampe's ability to optimize and personalize. But fresh data improves the integrity of audiences and enables event-based messages.


# What Events Should We Send To Aampe?
Source: https://kb.aampe.com/developer-guide/data-ingest/data-ingest-help/what-events-should-i-send-to-aampe

Timestamps! We love timestamps!

# What Is a "Good" Event Feed?

Agentic learning systems depend on high-quality behavioral data to evaluate the impact of their actions. This guide explains which data matters most and provides a framework for prioritizing event instrumentation.

## Categories of Data in Agentic Systems

Agentic systems are designed to learn by observing the effects of their actions on users. To facilitate that learning, they rely on three fundamental categories of data: user attributes, content attributes, and timestamped events. Each of these serves a distinct role in the agent’s learning environment.

* **User attributes** (location, language, subscription tier, behavioral rollups) are static and lack timestamp precision. They can't measure treatment impact directly but help filter eligibility and match similar users for learning acceleration.
* **Content attributes** (genre, artist, brand, feature category) enable content personalization but describe treatments rather than outcomes. They show what was recommended, not how users responded.
* **Timestamped user events** are most valuable for learning. These actions occur at specific moments (starting a stream, completing a purchase, reading an article), enabling causal inferences about treatment effects.

## Why Timestamped Events Matter Most

Agentic learning requires isolating individual treatment effects. Agents must track when treatments are delivered, to whom, and what happened afterward. Timestamped events make this linkage robust. Without them, or with only coarse aggregates, agents lose the ability to learn precise cause-effect relationships.

Not all events are equally valuable. The best signals represent volitional, meaningful, spontaneous engagement. Subscription renewals are business-critical but predictable and scheduled, making them poor reward events. Account linking actions are finite and non-repeatable, failing to provide ongoing feedback.

Quantity matters alongside quality. Too narrow an event set starves agents of signal. Rich event variety captures subtle response patterns and prevents agents from misinterpreting missing data as non-response. Broad coverage ensures genuine influence patterns remain visible.

## Characteristics of Good Reward Events

Good reward events are distinguished by a set of properties that make them reliable indicators of user intent and value alignment. These events provide the backbone for agentic learning because they allow the system to observe how users react to treatments in ways that are both timely and meaningful. Not every user action qualifies. Some are noisy, passive, or structurally unsuitable for learning.

The most effective reward events share these qualities:

* **Volitional**: The user initiates the action by choice, not passively or automatically.
* **Spontaneous**: The event can occur at any time; it is not bound to a predefined schedule.
* **Repeatable**: The user can perform the action multiple times without exhausting the opportunity.
* **Value-Aligned**: The event reflects real usage of the product or service in a way that supports the business's long-term goals.

These traits ensure that the system learns from actions that are not only detectable but also meaningful. For instance, a user streaming a song, purchasing a product, or completing a fitness goal are all behaviors that are voluntary, time-sensitive, and repeatable.

By contrast, subscription renewals or account linkages may be strategically important, but they occur on predictable schedules or as one-time actions, making them poor choices for continuous feedback and learning.

## A Checklist for Event Prioritization

This checklist ranks event types by usefulness to agentic learning. Provide as many as possible, starting from the top:

* **Tier 1: Core Value Actions**\
  Direct indicators of meaningful product use: content streamed/consumed (music, video, articles), products purchased, transactions completed (bill payments, fund transfers), key actions logged.
* **Tier 2: Feature Engagement**\
  Deliberate interaction with features: adding to playlists/wishlists/carts, toggling settings or features, modifying subscription plans. Strong signals of intentional use.
* **Tier 3: Session and Message Engagement**\
  User presence indicators: app opens, session starts/stops, notification clicks, message views. Establishes attribution windows and general engagement, though more ambiguous for value measurement.
* **Tier 4: Utility Interactions**\
  Intent signals weakly linked to consumption: site search, browsing, tag-based exploration. Often preliminary to meaningful behaviors but less discriminative alone.
* **Tier 5: Passive Interaction Events**\
  Generic page views or button clicks not tied to specific features/content. Useful for interface flow and debugging, but limited value for modeling satisfaction or preferences.
* **Tier 6: Scheduled or One-Time Outcomes**\
  Business milestones that are externally timed or terminal: subscription renewals, trial completions, account linkages. Poor causal indicators, unsuitable as reward signals.

Note that events that make very poor reward signal may still be very important to the business. Agents generally cannot learn user preferences based on subscription auto-renewals, but those renewals should still be tracked over time, since better, more meaningful, and more frequent engagement should correlate with increased retention.

## Avoiding Unnecessary Data Volume

For many organizations - particularly those operating in event-driven architectures such as streaming services - the volume of raw behavioral data can be immense. Ingesting and transmitting all raw playback events, particularly if sampled at regular time intervals, is both financially and technically infeasible.

In these situations, it helps to identify compact and representative signals. For streaming apps, a single "stream start" event per session or item is typically sufficient. This approach preserves the essential behavioral insight without overwhelming infrastructure.

The broader principle is that agentic learning depends on timing, not exhaustive detail. A sparse set of carefully selected, timestamped events offers more actionable learning signal than high-volume logs that are costly to transmit and difficult to operationalize.


# Sending Data to Aampe
Source: https://kb.aampe.com/developer-guide/data-ingest/data-integrations

See the following guides for instructions on how to send data to Aampe

## Supported Data Sources

Don't see your preferred data source? Send an email to [support@aampe.com](mailto:support@aampe.com) and we'll find a solution.

<Accordion title="API" icon="code">
  * [Aampe Streaming API](/developer-guide/data-ingest/data-sources/streaming-aampe-api)
</Accordion>

<Accordion title="Cloud Database" icon="database">
  * [Amazon RDS](/developer-guide/data-ingest/data-sources/database-aws-rds)
  * [Google Spanner](/developer-guide/data-ingest/data-sources/database-spanner)
</Accordion>

<Accordion title="Cloud Storage" icon="bucket">
  * [Amazon S3](/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3)
  * [Google Cloud Storage](/developer-guide/data-ingest/data-sources/cloud-storage-gcs)
  * [SFTP](/developer-guide/data-ingest/data-sources/sftp)
</Accordion>

<Accordion title="Customer Data Platform" icon="user">
  * [Amplitude - batch](/developer-guide/data-ingest/data-sources/amplitude-batch)
  * [Amplitude - cohort](/developer-guide/data-ingest/data-sources/amplitude-cohort)
  * [Amplitude - streaming](/developer-guide/data-ingest/data-sources/amplitude-streaming)
  * [Clevertap](/developer-guide/data-ingest/data-sources/clevertap)
  * [Firebase Cloud Messaging](/developer-guide/data-ingest/data-sources/firebase)
  * [Mixpanel](/developer-guide/data-ingest/data-sources/mixpanel)
  * [Segment](/developer-guide/data-ingest/data-sources/segment)
</Accordion>

<Accordion title="Data Warehouse" icon="cloud">
  * [Databricks](/developer-guide/data-ingest/data-sources/data-warehouse-databricks)
  * [Google BigQuery](/developer-guide/data-ingest/data-sources/data-warehouse-bigquery)
  * [Snowflake](/developer-guide/data-ingest/data-sources/data-warehouse-snowflake)
  * [Redshift](/developer-guide/data-ingest/data-sources/data-warehouse-redshift)
</Accordion>

## Data Integration FAQs

<Accordion title="What should we include in our event feed?" icon="sparkles">
  Aampe needs a high-fidelity event feed that includes key conversion events *and* day-to-day engagement events.

  [Read more about what a "good" event feed looks like.](/developer-guide/data-ingest/data-ingest-help/what-events-should-i-send-to-aampe)
</Accordion>

<Accordion title="How often should we send data to Aampe?" icon="sparkles">
  For most customers, a daily sync is a good starting point. More frequent syncs will improve the accuracy of audiences, but introduces some cost and complexity.

  For real-time use cases (e.g. abandoned cart messages), you will want to [send events to Aampe via API](developer-guide/data-ingest/data-sources/streaming-aampe-api.mdx).

  [Continue reading about what to consider when deciding how frequently to send data to Aampe.](/developer-guide/data-ingest/data-ingest-help/how-often-data-sync)
</Accordion>

<Accordion title="Do we need to format data in a specific way?" icon="sparkles">
  Yes. Both event and user-attribute data should be formatted to be compatible with Aampe's system. Depending on where your data originates, this may not require any work on your part.\
  \
  [Continue reading about data formatting](/developer-guide/data-ingest/data-model). 
</Accordion>

<Accordion title="How does Aampe use event and attribute data?" icon="sparkles">
  Event data is central to how agents measure their success and learn what messages successfully influence user behavior.

  User attributes are primarily used to define which users are eligible for receiving a given message. Eligibility can also be based on events (we will send message ABC to users who have attribute X and performed Y action in the last week).

  [Read a more detailed explanation of why we built Aampe agents to learn from events instead of user attributes.](/user-guide/welcome-to-aampe/how-does-aampe-work/agent-help/events-vs-attributes)
</Accordion>


# Aampe Data Management
Source: https://kb.aampe.com/developer-guide/data-ingest/data-management

Aampe Data Management Practices

## Definitions

**Enduser data**: This includes contact\_ids, behavior event data and attribute information on your end users. See our [data model documentation](/developer-guide/data-ingest/data-models) for more information.

**System data**: This includes information such as server logs and error reports.

**Aampe customer records**: Usernames, billing related information

## Data Storage Location

Each customer has a **dedicated pipeline** that reads enduser data from their sources and transforms it into Aampe's data model.

Any PII present is **removed or anonymized**, ensuring compliance and security.

Once transformed, enduser data is stored in our cloud warehouse as a separate, **tenant-specific dataset**.

<Info>
  We are able to co-locate BigQuery instances into any [Google Cloud location](https://cloud.google.com/about/locations) to satisfy any needs on data storage location.
</Info>

Every tenant has their own message queues. These queues handle messages across all channels.

## Agentic Learning

Your agents learn **based only on your data**. While your agents may share information amongst themselves, they cannot share information with agents from other Aampe customers.

Agentic learning based on users message interactions is stored into the same tenant-specific dataset. This data includes preferences over labels, timing, and channels for each user.

Aampe data on users and content decisions can be exported directly to your data warehouse. See [here](/developer-guide/aampe-data/data-share-overview) for information on receiving data from Aampe.

## Data Retention

Data is retained by Aampe throughout the contract period.

## Additional Information

All data is encrypted at rest and in transit. Access to data is restricted to authorized personnel only. Regular security audits are conducted to ensure the security of data.


# Aampe Data Model
Source: https://kb.aampe.com/developer-guide/data-ingest/data-model

To start with Aampe, you need to send Aampe two datasets

## Two Datasets

Aampe needs two datasets to function.

1. A table of users along with important user properties. Any properties included will be available within the audience builder.
2. A table of user events. This table powers agentic learning and is also available within the audience builder.

## User Properties

Following is the data model Aampe uses to store properties about users.

| Column Name | Data Type | Description |
| :- | :- | :- |
| **contact\_id** | String | A unique user identifier |
| **country** | String | Required |
| **\<property\_1>** (e.g language) | ... | ... |
| **\<property\_n>** (e.g subscription\_status) | | |
| **push\_token** | String (Optional) | Token of the user that will be used to send out push-messages, if different from **contact\_id** |
| **phone\_number** | String (Optional) | Number to be used to send out SMS and whatsapp messages, if different from **contact\_id** |
| **email\_address** | String (Optional) | Email of the user that will be used to send out email messages, if different from **contact\_id** |

<Info>
  See this page for industry-specific examples of [user attributes](/developer-guide/data-ingest/user-properties)
</Info>

## Events

| Column Name | Data type | Description |
| - | - | - |
| **contact\_id** | String | A unique user identifier |
| **timestamp** | Timestamp | The timestamp of when the event happened in UTC |
| **event\_name** | String | An event name corresponding to the event that was triggered |
| **event\_instance\_id** | String (Optional) | An event identifier |
| **timezone** | String (Optional) | Local timezone of the user/event - locale |
| **metadata** | JSON (Optional) | Any useful data points about the event |

<Info>
  See this page for industry-specific examples of [events and event properties](/developer-guide/data-ingest/event-properties)
</Info>

## Data Model FAQs

<Accordion icon="sparkles" title="Which events should we send to Aampe?">
  We love any event that represents a conscious consumer choice. App opens, button clicks, form submissions, streaming, and similar product usage events are all excellent material to include in addition to the core conversion events of purchases or enrollments. Read more about [what makes for a quality event feed](/developer-guide/data-ingest/data-ingest-help/what-events-should-i-send-to-aampe). 
</Accordion>

<Accordion icon="sparkles" title="Do Aampe agents learn from user attributes?">
  They do not. User attributes are helpful and important for defining who is eligible to receive a given message, but all learning anchors against real human behavior observed through your event feed. 
</Accordion>

<Accordion icon="sparkles" title="Why does Aampe need so many events?">
  Every time agents interact with a customer, they look for a change in behavior in the customer's event feed. A higher resolution event feed makes it much easier for agents to detect subtle (but important) changes in behavior. This in turn leads to agents that can reach conclusions about your customers more quickly and accurately than if they were given only purchase events. 
</Accordion>


# Amplitude (Batch)
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/amplitude-batch

Estimated setup time: 30 minutes

## Requirements

* Amplitude Project with your Aampe datasets defined (users, events)
* Service Account Key (optional)

## Batch Sync

Amplitude and Aampe will sync data at a regular cadence (e.g. daily, hourly).

You have several options for syncing an Amplitude dataset with Aampe.

* Option 1: Amplitude pushes to Aampe-provisioned Google Cloud Storage
* Option 2: Amplitude pushes to Aampe's BigQuery
* Option 3: Aampe pulls data using the Amplitude API

## Option 1: Google Cloud Storage

1. In Amplitude, navigate to the **Data** tab

   <img alt="1 Main Page Pn" />
2. Find **Destinations** on the Data menu. Be sure you're using an Amplitude project with comprehensive data for all the users and events you wish to send to Aampe.

   <img alt="2 Destinations Pn" />
3. Find **Google Cloud Storage** in the catalog of available destinations.

   <img alt="5 Gcp Menu Pn" />
4. Select the following options from the `Export Data to Google Cloud` menu
   * Export events ingested today and moving forward
   * Export all merged Amplitude IDs
   * Select all events (or apply filters if needed)
5. Review the tables and click **Next**.

   <img alt="5a Gcp Settings Pn" />
6. Aampe will provide you with a Service Account Key file. If you have your key file ready, upload it to Amplitude along with the corresponding bucket information. Click **Next**.

   <img alt="5b Gcp Key Pn" />
7. Amplitude will attempt a test upload to check that the entered credentials work. If the upload is successful, click **Finish** to complete the GCS destination configuration and activation.

## Option 2: Google BigQuery

1. Amplitude will directly write data to the Aampe BigQuery instance
2. In Amplitude Data, click **Catalog** and select the **Destinations** tab.

   <img alt="1 Main Page Pn" />
3. In Amplitude Data, click **Catalog** and select the **Destinations** tab.

   <img alt="2 Destinations Pn" />
4. Add destination

   <img alt="3 Add Destination Pn" />
5. In the **Warehouse Destination** section, click **BigQuery**.

   <img alt="4 Add Bigquery Pn" />
6. On the **Getting Started** tab, select the data you'd like to export and the export's cadence. You can Export events ingested today and moving forward, Export all merged Amplitude IDs, or both. For events, you can also specify filtering conditions to only export events that meet certain criteria.
7. Review the schemas for the Event table and the Merge IDs table and click **Next**.

   <img alt="4a Bigquery Step1 Pn" />
8. Specify the BigQuery dataset to receive your Amplitude data, and upload the service account key file. This file must be in JSON format and will be provided by Aampe.

   <img alt="4b Bigquery Pn" />
9. Click **Next**. Amplitude attempts a test upload to test the credentials. If the upload is successful, click **Finish** to complete the BigQuery destination configuration and activation.

## Option 3: Amplitude Export API

Aampe will pull data from the [Amplitude Export API](https://www.docs.developers.amplitude.com/analytics/apis/export-api/).

<Info>
  The Amplitude Export API is only best for small datasets. For large data sets, please consider exporting to Google Cloud Storage or Google BigQuery.
</Info>

To send Aampe the necessary credentials

1. In your Amplitude workspace, click on **Settings** at the bottom left of your screen

   <img alt="6 Organization Settings Pn" />
2. Select **Projects** from the navigation bar that opens.
3. Select the project with the events you would like Aampe to ingest.

   <img alt="6b Project List Pn" />
4. Copy your **API Key** and **Secret Key**

   <img alt="6c Project Details Pn" />
5. Navigate to **System Settings > Integrations** and select the **Data Import** tab

   <img alt="7a Aampe Amplitude Pn" />
6. Select **Amplitude** and add your credentials

   <img alt="7b Aampe Amplitude Keys Pn" />
7. Click **Request Integration** to complete the integration between Aampe and Amplitude.

Unsure what events to send to Aampe? See [here](/developer-guide/data-ingest/what-events-should-i-send-to-aampe) for what a "good" event feed looks like.


# Amplitude (Cohort Sync)
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/amplitude-cohort

Estimated setup time: 1 hour

## Requirements

* A user cohort in Amplitude
* Your Aampe API Key

<Info>
  To get your Aampe API Key

  * Go to [https://compose.aampe.com/system-setup/integrations/events](https://compose.aampe.com/system-setup/integrations/events)
  * Login using your org credentials
  * Select **Connect** next to the **Aampe** endpoint
  * Copy the API key
</Info>

## Aampe Official Destination

1. Select **Data** from the main menu

   <img alt="1 Main Page Pn" />
2. Click **Destinations**

   <img alt="2 Destinations Pn" />
3. Click the `+ Add Destination` button

   <img alt="3 Add Destination Pn" />
4. Search the destination catalog for **Aampe** and select **Cohorts**

   <img alt="9 Cohort Pn" />
5. In the `Connect to Aampe` menu, select `Add another destination`

   <img alt="9a Cohort Add Pn" />
6. Enter the following details:
   * **Name:** Aampe - Cohorts
   * **API key:** api\_key
   * Select the **User ID mapping**. Here you want to select user ID which connects to your other Aampe data. Aim for a non-PII identifier if available. Click **Save**.

     <img alt="9b Cohort Form Pn" />
7. From the Amplitude home page, go to **Users → Cohorts**.

   <img alt="11 User Cohort Pn" />
8. Select any Cohort that you want to sync. Click **Target Users**

   <img alt="11a Target Cohort Pn" />
9. **Sync to Aampe destination**

   <img alt="11b Target Aampe Pn" />
10. Choose the API you're sending data to

    <img alt="11c Select Api Pn" />
11. Finally, select **Real-time Sync** and hit **Sync**

    <img alt="11d Define Cadence Pn" />

Congrats. Your Aampe cohort integration is live!

***


# Amplitude (Streaming)
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/amplitude-streaming

Estimated setup time: 30 minutes

## Requirements

* Your Aampe API Key

<Info>
  To get your Aampe API Key

  * Go to [https://compose.aampe.com/system-setup/integrations/events](https://compose.aampe.com/system-setup/integrations/events)
  * Login using your org credentials
  * Select **Connect** next to the **Aampe** endpoint
  * Copy the API key
</Info>

## **Amplitude's Destination Catalog**

1. Go to **Menu -> Data**

   <img alt="1 Main Page Pn" />
2. Click on **Destinations**

   <img alt="2 Destinations Pn" />
3. Click Add a new destination.

   <img alt="8 Add New Destination Pn" />
4. Search for **Aampe** and select **Events and User Properties**

   <img alt="8 Destination Menu Aampe Pn" />
5. Enter the following details
   1. Sync Name: Aampe - Data Integration

      <img alt="8b Name Pn" />
   2. Set the following destination settings
      * Status: Enabled
      * Aampe API Key
      * User identifier: Select the User ID mapping. Here you want to select user ID which connects to your other Aampe data. Aim for a non-PII identifier if available.
      * Check that both **Send Users** and **Send Events** are selected

        <img alt="8d Destination Menu Pn" />
6. Select the events and properties you want to send.

   <Tip>
     Unsure what events to send? See [here](/developer-guide/data-ingest/what-events-should-i-send-to-aampe) for guidance on what a "good" event stream looks like.
   </Tip>
7. Hit **Save**

Congrats. Your Amplitude-Aampe data integration is live!


# CleverTap
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/clevertap

Estimated setup time: 15 minutes

## Requirements

* CleverTap admin permissions
* A GCP bucket (provided by Aampe)
* Service account key (provided by Aampe)

<Info>
  If you would prefer to provision your own cloud storage, you can follow the guide using your own bucket and key. To complete the sync, simply provide Aampe with the bucket details.
</Info>

## Step 1: Integrate Google Cloud as a Partner

1. Navigate to **Settings > Partners** from the CleverTap dashboard

   <img alt="1 Select Integration Pn" />
2. Hover on the **Google Cloud** icon and click **Integrate**
3. Click **+ Google Cloud Bucket** to add a bucket. You can also add multiple buckets from this popup
4. Enter the following details and click **Save Credentials**:
   * **Bucket nickname:** Enter a nickname for this bucket integration
   * **Service Account Key:** Copy/paste the JSON string provided by Aampe (or the contents of the service account key JSON file if you decided to set up your own bucket)
   * **Bucket name:** Enter the name of the storage bucket provided by Aampe (or that you created if you decided to set up your own bucket)

     <img alt="2 SA Key Pn" />

The new integration will appear on the list of Google Cloud integrations.

5. Press on **Done** to continue

## Step 2: Create Data Export

Aampe uses both event and profile data, and this guide walks you through setting up an export for both CleverTap User Events and User Profiles.

1. Navigate to **Settings > Partners** from the CleverTap dashboard
2. Click on the **Exports** tab
3. Click **+ Export** and select **Google Cloud** from the partners dropdown

   <img alt="3 Create Data Export Pn" />

### Create Export for Events

1. The **Export to Google Cloud** modal will show up on the right side of the screen.
2. Select the bucket defined in the previous step
3. Configure the following settings:

   * **Type:** All events
   * **Frequency:** Recurring
   * **Frequency of data export:** Every 24 Hours
   * **Format:** JSON

   <img alt="4 Export Menu Pn" title="4 Export Menu Pn" />
4. Click **Export**

On clicking, the popup closes, and the "Google export has initiated" message displays at the top of the Exports page. You will now be able to see the newly-created export for Google Cloud.

<img alt="5 Initiate Export Pn" />

### Create Export for User Profiles

We will now repeat steps 2 through 5 to create an export for User Profiles:

1. Click **+ Export** and select **Google Cloud** from the partners dropdown
2. The **Export to Google Cloud** window displays on the right side of the screen. Please select the bucket defined in integration earlier
3. Configure the following settings:
   * **Type:** All user profiles
   * **Frequency:** Recurring (Every 24 Hours)
   * **Format:** JSON
4. Click **Export**

Congrats. Your CleverTap data integration is all set!

***


# AWS S3
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3

Estimated setup time: 1 hour

## Getting Started

Connect your Amazon S3 bucket to Aampe to ingest event data for personalization.

## Bucket Ownership Options

Aampe supports two approaches for S3 data ingestion:

| Option | Best For | Setup Time |
| - | - | - |
| [Customer-Owned Bucket](/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-customer-owned) | Enterprise customers who need full control over data storage and security policies | \~1 hour |
| [Aampe-Owned Bucket](/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-aampe-owned) | Customers who prefer a simpler setup without managing bucket permissions | \~30 minutes |

## Which Option Should I Choose?

**Choose Customer-Owned Bucket if you:**

* Have existing data pipelines writing to S3
* Need to comply with data residency requirements
* Want full control over bucket lifecycle policies, encryption, and access logs
* Prefer to manage data in your own AWS account

**Choose Aampe-Owned Bucket if you:**

* Want the fastest setup experience
* Don't have existing S3 infrastructure
* Prefer Aampe to manage the storage infrastructure

## Data Format

Regardless of which option you choose, your event data should follow the [Aampe Data Model](/developer-guide/data-ingest/data-model). Supported file formats include:

* JSON or Newline Delimited JSON (ndJSON) - *Preferred*
* CSV
* Parquet

<Info>
  The Aampe team is happy to help with providing alternatives if the above is in conflict with your IT policies. Please send an email to [support@aampe.com](mailto:support@aampe.com) and we'll find a solution.
</Info>


# Cloud Storage Aws S3 Aampe Owned
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-aampe-owned

Estimated setup time: 1 hour

Use this guide when you want Aampe to provide and manage the S3 bucket. You simply upload your event data to a bucket we provision for you.

***

## Getting Started

### Step 1: Request a Bucket from Aampe

Contact the Aampe team at [support@aampe.com](mailto:support@aampe.com) to request a dedicated S3 bucket. We will provision a bucket and provide you with:

* **Bucket name**
* **Region**
* **Write credentials** (one of the options below)

### Step 2: Choose a Credential Type

Aampe can provide credentials in several formats depending on your infrastructure:

| Credential Type | Best For |
| - | - |
| IAM User Access Keys | Direct S3 uploads, AWS CLI, most ETL tools |
| Pre-signed URLs | One-time uploads, serverless workflows |
| Cross-Account Role | Organizations that prefer role-based access from their AWS account |

Let us know your preference when requesting the bucket.

### Step 3: Configure Your Data Pipeline

Once you receive credentials, configure your data pipeline to write to the Aampe bucket.

#### Using AWS CLI

```bash theme={null}
aws s3 cp events_20240115.json s3://<AAMPE_BUCKET_NAME>/events_20240115.json
```

#### Using AWS SDK (Python Example)

```python theme={null}
import boto3

s3 = boto3.client(
    's3',
    aws_access_key_id='<ACCESS_KEY_PROVIDED_BY_AAMPE>',
    aws_secret_access_key='<SECRET_KEY_PROVIDED_BY_AAMPE>',
    region_name='<REGION_PROVIDED_BY_AAMPE>'
)

s3.upload_file('events_20240115.json', '<AAMPE_BUCKET_NAME>', 'events_20240115.json')
```

#### Using Pre-signed URLs

If Aampe provides pre-signed URLs, you can upload directly via HTTP:

```bash theme={null}
curl -X PUT -T events_20240115.json "<PRE_SIGNED_URL>"
```

***

## Step 4: Upload Your Data

Upload event data in one of these formats:

* JSON or Newline Delimited JSON (ndJSON) - *Preferred*
* CSV
* Parquet

### File Naming Convention

Use a consistent naming pattern:

* **Daily files:** `events_YYYYMMDD.json` (e.g., `events_20240115.json`)
* **With partitions:** `/year=2024/month=01/day=15/events_20240115.json`

### Data Format

Your event data should follow the [Aampe Data Model](/developer-guide/data-ingest/data-model).

***

## Verification

Once you start uploading, the Aampe team will confirm that we are successfully receiving your data.

***

## Frequently Asked Questions

### Where is the data stored?

Aampe buckets are hosted in AWS regions optimized for our data processing infrastructure. If you have specific data residency requirements, let us know and we will accommodate where possible.

### Can I use my existing data pipeline?

Yes. Most ETL tools (Fivetran, Airbyte, dbt, etc.) and cloud services (AWS Glue, Lambda, Step Functions) support writing to S3 with access keys.

### What happens to my data?

Aampe processes your event data according to our [data processing agreement](https://aampe.com/legal/dpa). Data is used solely for providing personalization services to your organization.

***

<Info>
  Contact us at [support@aampe.com](mailto:support@aampe.com) if you need assistance setting up your data pipeline.
</Info>

***

## Related Resources

* [Aampe Data Model](/developer-guide/data-ingest/data-model)
* [AWS S3: Customer-Owned Bucket](/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-customer-owned)


# Cloud Storage Aws S3 Customer Owned
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-customer-owned

Estimated setup time: 1 hour

Use this guide when your organization owns and manages the S3 bucket. Aampe will read event data from your bucket using one of several authentication methods.

***

## Getting Started

### Step 1: Create Your Bucket

Create an S3 bucket in your AWS account. Share the following with Aampe:

* **Bucket name** (e.g., `acme-events-bucket`)
* **Region** (e.g., `us-east-1`)

### Step 2: Choose an Authentication Method

Aampe supports three methods for accessing your bucket. Choose the one that best fits your security requirements:

| Method | Security Level | Best For |
| - | - | - |
| [Cross-Account IAM Role](#option-a-cross-account-iam-role-recommended) | Highest | Production environments, enterprise security requirements |
| [IAM User Access Keys](#option-b-iam-user-access-keys) | Moderate | Simple setups, quick proofs of concept |

***

## Option A: Cross-Account IAM Role (Recommended)

This is the AWS-recommended approach for third-party access. It uses temporary credentials and includes an External ID to prevent the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).

### How It Works

1. You create an IAM role in your AWS account
2. The role trusts Aampe's AWS account to assume it
3. Aampe assumes the role using temporary credentials
4. An External ID ensures only Aampe can assume the role on your behalf

### Setup Instructions

#### 1. Request Credentials from Aampe

Contact Aampe to receive:

* **Aampe AWS Account ID**
* **External ID** (unique to your organization)

> **Important:** The External ID is generated by Aampe and should not be shared or changed. This prevents other parties from assuming your role through Aampe.

#### 2. Create an IAM Policy

Create an IAM policy with read permissions for your bucket. Name it something like `AampeS3ReadAccess`.

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<YOUR_BUCKET_NAME>",
                "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
            ]
        }
    ]
}
```

Replace `<YOUR_BUCKET_NAME>` with your actual bucket name.

#### 3. Create an IAM Role with Cross-Account Trust

Create a new IAM role with the following trust policy:

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<AAMPE_AWS_ACCOUNT_ID>:root"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<EXTERNAL_ID_PROVIDED_BY_AAMPE>"
                }
            }
        }
    ]
}
```

Replace:

* `<AAMPE_AWS_ACCOUNT_ID>` with the Account ID provided by Aampe
* `<EXTERNAL_ID_PROVIDED_BY_AAMPE>` with the External ID provided by Aampe

Name this role something like `AampeS3AccessRole`.

#### 4. Attach the Policy to the Role

Attach the `AampeS3ReadAccess` policy (from step 2) to the `AampeS3AccessRole` (from step 3).

#### 5. Share the Role ARN with Aampe

Provide Aampe with the full role ARN:

```
arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:role/AampeS3AccessRole
```

### AWS Documentation

* [IAM Tutorial: Delegate access across AWS accounts using IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)
* [How to use External ID when granting access to third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html)

***

## Option B: IAM User Access Keys

This simpler approach grants an Aampe-managed IAM user direct access to your bucket via a bucket policy.

> **Note:** While easier to set up, this method uses long-lived credentials. AWS recommends using IAM roles (Option A) when possible. See [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html).

### How It Works

1. You create a bucket policy that grants access to an Aampe IAM user
2. Aampe provides the IAM user ARN to include in your policy
3. Aampe accesses your bucket using access keys for that user

### Setup Instructions

#### 1. Request the Aampe User ARN

Contact Aampe to receive the IAM user ARN that will access your bucket.

#### 2. Add a Bucket Policy

Apply the following bucket policy to grant Aampe read access:

```json theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AampeReadAccess",
            "Effect": "Allow",
            "Principal": {
                "AWS": "<AAMPE_USER_ARN>"
            },
            "Action": [
                "s3:GetObject",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::<YOUR_BUCKET_NAME>",
                "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
            ]
        }
    ]
}
```

Replace:

* `<AAMPE_USER_ARN>` with the ARN provided by Aampe
* `<YOUR_BUCKET_NAME>` with your bucket name

### AWS Documentation

* [Bucket policies for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html)
* [Actions, resources, and condition keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html)

***

## Step 3: Upload Your Data

Upload event data to your bucket in one of these formats:

* JSON or Newline Delimited JSON (ndJSON) - *Preferred*
* CSV
* Parquet

### File Naming Convention

Use a consistent naming pattern:

* **Daily files:** `events_YYYYMMDD.json` (e.g., `events_20240115.json`)
* **With partitions:** `/year=2024/month=01/day=15/events_20240115.json`

### Data Format

Your event data should follow the [Aampe Data Model](/developer-guide/data-ingest/data-model).

***

## Verification

Once configured, the Aampe team will confirm that we are successfully receiving your data.

***

## Troubleshooting

### Access Denied Errors

* Verify the bucket name in your policy matches exactly (case-sensitive)
* Ensure both bucket-level (`arn:aws:s3:::bucket`) and object-level (`arn:aws:s3:::bucket/*`) resources are included
* Check that the IAM role/user ARN matches what Aampe provided

### Role Cannot Be Assumed

* Verify the External ID matches exactly (for Option A)
* Check that the trust policy Principal matches Aampe's account/user
* Ensure the role has the policy attached (not just created)

***

<Info>
  If these options conflict with your IT policies or you need an alternative approach, contact us at [support@aampe.com](mailto:support@aampe.com). We are happy to work with your security team to find a solution.
</Info>

***

## Related Resources

* [Aampe Data Model](/developer-guide/data-ingest/data-model)
* [AWS S3: Aampe-Owned Bucket](/developer-guide/data-ingest/data-sources/cloud-storage-aws-s3-aampe-owned)


# Google Cloud Storage
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/cloud-storage-gcs

Estimated setup time: 30 minutes

## Getting Started

### Step 1: Create Your Bucket

Create a storage bucket in your cloud provider (Google Cloud Storage). Share the following with Aampe:

* Bucket name
* Region/location

### Step 2: Grant Access

The Aampe team will provide you with a service account email or identifier. Grant this account read access to your bucket.

#### Google Cloud Storage - Service Account Access

**Option 1: Command Line**

```
gsutil iam ch serviceAccount:<aampe_service_account>:roles/storage.objectViewer gs://<your_bucket_name>
```

**Option 2: IAM Policy JSON**

```
{
  "bindings": [
    {
      "role": "roles/storage.objectViewer",
      "members": [
        "serviceAccount:<aampe_service_account_email>"
      ]
    },
    {
      "role": "roles/storage.legacyBucketReader",
      "members": [
        "serviceAccount:<aampe_service_account_email>"
      ]
    }
  ]
}
```

**Option 3: Console**

1. Go to your bucket in GCS Console
2. Click "Permissions" → "Grant Access"
3. Add the Aampe service account with "Storage Object Viewer" role

#### Google Cloud Storage - Workload Identity Federation (Enhanced Security)

For organizations requiring Workload Identity Federation, Aampe will provide a subject identifier.

1. **Create a custom IAM role** with these permissions:
   * `storage.buckets.get`
   * `storage.objects.get`
   * `storage.objects.list`
2. **Set up Workload Identity Federation**:

```
# Create a Workload Identity Pool
gcloud iam workload-identity-pools create aampe-pool \
    --location="global" \
    --display-name="Aampe Integration Pool"

# Create a Workload Identity Provider
gcloud iam workload-identity-pools providers create-oidc aampe-provider \
    --location="global" \
    --workload-identity-pool="aampe-pool" \
    --issuer-uri="https://accounts.google.com" \
    --allowed-audiences="<audience_provided_by_aampe>" \
    --attribute-mapping="google.subject=assertion.sub"

# Grant access to the bucket
gcloud storage buckets add-iam-policy-binding gs://<your_bucket_name> \
    --member="principal://iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/aampe-pool/subject/<aampe_subject_identifier>" \
    --role="<your_custom_role>"
```

### Step 3: Upload Your Data

Upload event data daily in one of these formats:

* **JSON** or **Newline Delimited JSON (ndJSON)** - Preferred
* **CSV**
* **Parquet**

Use this file naming pattern:

* Daily: `events_YYYYMMDD.json` (e.g., `events_20240115.json`)
* With partitions: `/year=2024/month=01/day=15/events_20240115.json`

## Data Format

Your event data should include these required fields (see [Data Models](https://docs.aampe.com/docs/data-models) for the full schema):

##

Congrats. The Aampe team will confirm that we're successfully receiving your data.

***


# BigQuery (Google)
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/data-warehouse-bigquery

Estimated setup time: 30 minutes

There are 2 ways to send data to Aampe from BigQuery:

* Direct Read Access from Your BQ Dataset
* Push to Google Cloud Storage Bucket

### Option 1: Direct Read Access from Your BQ Dataset

Aampe will access your BQ with a dedicated service account.

To grant Aampe read-only access to your BQ dataset, you need to create an Aampe service account and grant the following permissions:

* `bigquery.datasets.get`
* `bigquery.readsessions.create`
* `bigquery.readsessions.getData`
* `bigquery.tables.get`
* `bigquery.tables.getData`
* `bigquery.tables.list`

#### Step-by-step Procedure

1. **Create the custom role:**
   * Go to [https://console.cloud.google.com/iam-admin/roles](https://console.cloud.google.com/iam-admin/roles)

     <img alt="1 Create Role Pn" />
   * Fill the form (title: Aampe Custom BQ Read Access)

     <img alt="2 Role Menu Pn" />
   * Add the following permissions:
     * `bigquery.datasets.get`
     * `bigquery.readsessions.create`
     * `bigquery.readsessions.getData`
     * `bigquery.tables.get`
     * `bigquery.tables.getData`
     * `bigquery.tables.list`
2. **Grant permissions:**
   * Go to [https://console.cloud.google.com/iam-admin/iam?project=](https://console.cloud.google.com/iam-admin/iam?project=)
   * Press **Grant access** button

     <img alt="Bigquery3 Grant Access Pn" />
   * Fill the form "add principal" with the Aampe service account that we will provide you (We will provide you the service account to use for integration via email)
   * Fill the form "assign role" with **Aampe Custom BQ Read Access**

     <img alt="4 Save Grant Pn" />

You need to provide us with the following details:

* Project ID
* Dataset ID
* Data location
* Table names (of all the tables that you would like to provide us data of)

### Option 2: Push to Google Cloud Storage Bucket

When the data size is very large we recommend that you push data to a cloud storage bucket. We will then copy this data from your GCS bucket to one set up by Aampe for ingestion to our system. If you prefer, you can directly push to a bucket created by Aampe.

#### Steps

1. Create a bucket on GCP.
2. Provide Aampe with access to that bucket (We will provide you the details of the account that you need to provide access to)
3. Set up export from BQ to the cloud storage bucket: [Export Data](https://cloud.google.com/bigquery/docs/exporting-data)
4. Automate the export for each day of event data

For reference on the data model, please refer to [Data Models](/developer-guide/data-ingest/data-model).


# Databricks
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/data-warehouse-databricks

Estimated setup time: 1 hour

## Prerequisites

* Databricks workspace with Unity Catalog enabled
* Metastore created and attached to your workspace
* Appropriate admin privileges to create service principals and grant permissions

## Integration Methods

### Option 1: Direct Read Access via Service Principal

This method allows Aampe to directly access your Unity Catalog tables using a dedicated service principal with OAuth authentication.

#### Required Permissions

The Aampe service principal needs the following Unity Catalog privileges:

* USE CATALOG - Access to view metadata in the catalog
* USE SCHEMA - Access to view metadata in schemas
* SELECT - Read access to tables and views
* BROWSE - Optional: View object metadata in Catalog Explorer

#### Step-by-step Procedure

1. Create the Service Principal

**Option A: Databricks-managed Service Principal**

1. Go to your Databricks account console
2. Navigate to **User management** > **Service principals**
3. Click **Add service principal**
4. Provide a name (e.g., aampe-integration-sp)
5. Click **Add**

**Option B: Azure Entra ID Service Principal (Azure Databricks only)**

1. Create an app registration in Azure Portal
2. Note the Application (client) ID
3. Add the service principal to your Databricks account
4. Generate OAuth Credentials
5. In the service principal's details page, go to the **Secrets** tab
6. Under **OAuth secrets**, click **Generate secret**
7. Set the secret's lifetime (maximum 730 days)
8. Copy and securely store:
   * **Client ID** (same as Application ID)
   * **OAuth Secret** (shown only once)
9. Click **Done**
10. Grant Unity Catalog Permissions

Run the following SQL commands in a Databricks notebook or SQL editor:

```
-- Grant catalog-level permissions
GRANT USE CATALOG ON CATALOG <catalog_name> TO <service_principal_id>;

-- Grant schema-level permissions
GRANT USE SCHEMA ON SCHEMA <catalog_name>.<schema_name> TO <service_principal_id>;

-- Grant table-level read permissions
GRANT SELECT ON TABLE <catalog_name>.<schema_name>.<table_name> TO <service_principal_id>;

-- Alternatively, grant SELECT on all tables in a schema
GRANT SELECT ON SCHEMA <catalog_name>.<schema_name> TO <service_principal_id>;
```

Replace:

* \<catalog\_name>: Your Unity Catalog name
* \<schema\_name>: Your schema/database name
* \<table\_name>: Specific table names (or use schema-level grant)
* \<service\_principal\_id>: The Application ID of your service principal

5. Provide Connection Details to Aampe

Share the following information with the Aampe team:

* **Workspace URL**: `https://<workspace-name>.cloud.databricks.com`
* **Client ID**: Your service principal's Application ID
* **OAuth Secret**: The generated secret (transfer securely)
* **Catalog Name**: Your Unity Catalog name
* **Schema Names**: List of schemas containing relevant tables
* **Table Names**: Specific tables to sync (if not syncing entire schemas)
* **Workspace ID**: Your Databricks workspace ID
* **Account ID**: Your Databricks account ID (for account-level access)

### Option 2: Push to Cloud Storage

For large-scale data transfers, you can export data to cloud storage that Aampe can access.

#### AWS S3 Setup

1. Create External Location

   ```
   -- Create storage credential
   CREATE STORAGE CREDENTIAL IF NOT EXISTS aampe_storage_cred
   WITH (
     AWS_IAM_ROLE = 'arn:aws:iam::<account-id>:role/<role-name>'
   );

   -- Create external location
   CREATE EXTERNAL LOCATION IF NOT EXISTS aampe_export_location
   URL 's3://<bucket-name>/aampe-export/'
   WITH (STORAGE CREDENTIAL aampe_storage_cred);
   ```
2. Grant Permissions

   ```
   -- Grant write access to the service principal
   GRANT CREATE EXTERNAL TABLE ON EXTERNAL LOCATION aampe_export_location 
   TO <service_principal_id>;

   GRANT WRITE FILES ON EXTERNAL LOCATION aampe_export_location 
   TO <service_principal_id>;
   ```
3. Set up Automated Export

Create a Databricks Job or Delta Live Tables pipeline to export data

## Data Models

Ensure your exported data conforms to the Aampe <u>Data Models</u> specification.


# AWS Redshift
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/data-warehouse-redshift

Estimated setup time: 30 minutes

# Redshift Integration

There are two recommended approaches for integrating Amazon Redshift with Aampe:

* Unload data into Amazon S3 from Redshift
* Provide direct access for Aampe user to your Redshift cluster (and tables) with event data

## Unloading Data into Amazon S3 from Redshift

### 1. Create IAM Role for Redshift

Create an IAM role that allows Redshift to access S3. This follows AWS security best practices by using roles instead of hardcoded credentials.

```sql theme={null}
-- First, create the IAM role in AWS Console or CLI with the following trust policy:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "redshift.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

Attach the following IAM policy to the role (replace `your-bucket-name` with the actual bucket):

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}
```

### 2. Attach IAM Role to Redshift Cluster

Associate the IAM role with your Redshift cluster:

```sql theme={null}
-- Get the role ARN and attach it to your cluster
-- This can be done via AWS Console or CLI
aws redshift modify-cluster --cluster-identifier your-cluster-name --iam-roles arn:aws:iam::account-id:role/RedshiftS3Role
```

### 3. Unload Data to S3

Use the UNLOAD command to export data from Redshift to S3. Redshift's UNLOAD command is optimized for parallel processing and handles large datasets efficiently.

```sql theme={null}
-- Example: Unload event data to S3 in Parquet format
UNLOAD ('SELECT * FROM events WHERE event_date >= current_date - 1')
TO 's3://your-bucket-name/events/year=2024/month=09/day=18/'
IAM_ROLE 'arn:aws:iam::account-id:role/RedshiftS3Role'
FORMAT AS PARQUET
PARTITION BY (event_date)
ALLOWOVERWRITE
PARALLEL ON;
```

**Key UNLOAD parameters for optimization:**

* `FORMAT AS PARQUET`: Efficient columnar format, recommended for analytics
* `PARTITION BY`: Organizes data for better query performance
* `PARALLEL ON`: Enables parallel processing (default, but explicit is better)
* `ALLOWOVERWRITE`: Overwrites existing files
* `MAXFILESIZE`: Controls individual file size (default 6.2GB)
* `MANIFEST`: Generates manifest file for data verification

**Alternative formats:**

```sql theme={null}
-- CSV format with header
UNLOAD ('SELECT * FROM events WHERE event_date >= current_date - 1')
TO 's3://your-bucket-name/events/csv/'
IAM_ROLE 'arn:aws:iam::account-id:role/RedshiftS3Role'
FORMAT AS CSV
HEADER
PARALLEL ON;

-- JSON format
UNLOAD ('SELECT * FROM events WHERE event_date >= current_date - 1')
TO 's3://your-bucket-name/events/json/'
IAM_ROLE 'arn:aws:iam::account-id:role/RedshiftS3Role'
FORMAT AS JSON
PARALLEL ON;
```

### 4. Automate the Unloading Process

**Option A: Using Redshift Scheduler (Recommended)**

Create a scheduled query to automate daily unloads:

```sql theme={null}
-- Create a scheduled query (available in Redshift Console)
-- or use the Redshift Data API with EventBridge
CREATE EVENT RULE daily_unload_events
SCHEDULE 'cron(0 2 * * ? *)' -- Run at 2 AM daily
DESCRIPTION 'Daily unload of events to S3'
STATE ENABLED;
```

**Option B: Using AWS Lambda + EventBridge**

Create a Lambda function that executes the UNLOAD command:

```python theme={null}
import boto3
import json

def lambda_handler(event, context):
    redshift_data = boto3.client('redshift-data')
    
    # Execute UNLOAD command
    response = redshift_data.execute_statement(
        ClusterIdentifier='your-cluster-name',
        Database='your-database',
        DbUser='your-db-user',
        Sql=f"""
        UNLOAD ('SELECT * FROM events WHERE event_date = current_date - 1')
        TO 's3://your-bucket-name/events/year={{{{ year }}}}/month={{{{ month }}}}/day={{{{ day }}}}/'
        IAM_ROLE 'arn:aws:iam::account-id:role/RedshiftS3Role'
        FORMAT AS PARQUET
        PARTITION BY (event_date)
        ALLOWOVERWRITE
        PARALLEL ON;
        """
    )
    
    return {
        'statusCode': 200,
        'body': json.dumps(f'Query submitted: {response["Id"]}')
    }
```

### 5. Monitoring and Optimization

**Monitor UNLOAD performance:**

```sql theme={null}
-- Check UNLOAD query performance
SELECT query, elapsed, aborted, substring(querytxt,1,60) as sql_text
FROM stl_query 
WHERE querytxt LIKE '%UNLOAD%' 
ORDER BY starttime DESC 
LIMIT 10;
```

**Best practices for optimization:**

* Use appropriate distribution keys on source tables
* Consider VACUUM and ANALYZE operations before UNLOAD
* Monitor S3 costs and implement lifecycle policies
* Use compression (GZIP, BZIP2) for cost optimization if network transfer is a concern

## Provide Direct Access for Aampe User to Your Redshift Cluster

This approach allows Aampe to directly query your Redshift cluster. Follow the principle of least privilege for security.

### Setup Steps:

#### 1. Create a Custom Database Role (if needed)

```sql theme={null}
-- Create a read-only role for Aampe
CREATE ROLE aampe_read_role;
```

#### 2. Create Database User

```sql theme={null}
-- Create user with password authentication
CREATE USER aampe_user PASSWORD 'secure_password_here';

-- Alternative: Create user without password for IAM authentication
CREATE USER aampe_user;
```

#### 3. Grant Role to User

```sql theme={null}
-- Grant the read role to the user
GRANT ROLE aampe_read_role TO aampe_user;
```

#### 4. Grant Table-Level Permissions

```sql theme={null}
-- Grant access to specific schemas and tables
-- Replace 'your_schema' and table names with your actual schema/tables

-- Grant schema usage
GRANT USAGE ON SCHEMA your_schema TO aampe_read_role;

-- Grant table select permissions
GRANT SELECT ON your_schema.events TO aampe_read_role;
GRANT SELECT ON your_schema.users TO aampe_read_role;
GRANT SELECT ON your_schema.sessions TO aampe_read_role;

-- Or grant access to all tables in schema (current and future)
GRANT SELECT ON ALL TABLES IN SCHEMA your_schema TO aampe_read_role;
ALTER DEFAULT PRIVILEGES IN SCHEMA your_schema GRANT SELECT ON TABLES TO aampe_read_role;
```

#### 5. Configure Network Security

**VPC Security Groups:** Ensure your Redshift cluster's security group allows connections from Aampe's IP addresses on port 5439.

**Subnet Groups:** If using private subnets, ensure proper routing and NAT gateway configuration.

### Connection Details Required

Provide Aampe with the following connection information:

* **Host/Endpoint**: `your-cluster-name.abc123.us-east-1.redshift.amazonaws.com`
* **Port**: `5439` (default Redshift port)
* **Database Name**: Your database name
* **Schema Name**: Schema containing event tables
* **Username**: `aampe_user`
* **Password**: The password you created
* **Table Names**: List of tables containing event data

## Data Models

Refer to the [Data Models](/developer-guide/data-ingest/data-model) documentation for the expected schema and data format requirements.


# Snowflake Integration
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/data-warehouse-snowflake

Estimated setup time: 1 hour

<Info>
  When importing from databases, many customers create separate tables/views for Aampe that are limited to only the data necessary for Aampe to function.
</Info>

## Connect Snowflake to Aampe (via Google Cloud Storage)

### 1. Create Snowflake Integration

Integrations are named, first-class Snowflake objects that avoid the need for passing explicit cloud provider credentials such as secret keys or access tokens; instead, integration objects reference a Cloud Storage service account. Aampe will provide you with the bucket link mentioned below.

```
CREATE STORAGE INTEGRATION gcs_int
TYPE = EXTERNAL_STAGE
STORAGE_PROVIDER = GCS
ENABLED = TRUE
STORAGE_ALLOWED_LOCATIONS = ('gcs-bucket-link');
```

### 2. Obtain GCP Service Account

A GCP Service account is created by Snowflake as part of Step 1:

```
DESC STORAGE INTEGRATION gcs_int;
```

In the output of the above command, the `STORAGE_GCP_SERVICE_ACCOUNT` property contains the GCP service account name. Example output:

```
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
| property                    | property_type | property_value                                                              | property_default |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------|
| ENABLED                     | Boolean       | true                                                                        | false            |
| STORAGE_ALLOWED_LOCATIONS   | List          | bucket-link-that-we-will-send-you                                          | []               |
| STORAGE_GCP_SERVICE_ACCOUNT | String        | service-account@project.iam.gserviceaccount.com                            |                  |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
```

We will take this service account and provide it permissions to add/modify data to the GCS bucket.

### 3. Create File Formats

A parquet file format can be created in Snowflake as follows to unload snowflake data in the parquet format. Any other format like CSV or JSON also can be created. Here is an example script to create parquet format:

```
USE DB_NAME;
USE SCHEMA_NAME;
CREATE OR REPLACE FILE FORMAT parquet_unload_file_format
TYPE = PARQUET
SNAPPY_COMPRESSION = TRUE
COMMENT = 'FILE FORMAT FOR UNLOADING AS PARQUET FILES';
```

More options and file types can be found [here](https://docs.snowflake.com/en/sql-reference/sql/create-file-format.html).

### 4. Create External Stage

In Snowflake, an EXTERNAL STAGE object references data files stored in a location outside of Snowflake.

```
USE DB_NAME;
USE SCHEMA SCHEMA_NAME;
CREATE OR REPLACE STAGE parquet_unload_gcs_stage
URL = 'gcs-bucket-link'
storage_integration = gcs_int
FILE_FORMAT = parquet_unload_file_format
COMMENT = 'GCS Stage for the Snowflake external Parquet export';
```

### 5. Unload Data

From Snowflake, use the COPY command in Snowflake to unload data from a Snowflake table into a GCS bucket. To retain the column names in the output file, use the `HEADER = TRUE` copy option.

```
COPY INTO @<EXTERNAL_STAGE_NAME>/<file_name_prefix>
FROM DB_NAME.SCHEMA_NAME.TABLE_NAME
HEADER = TRUE;
```

For example:

```
COPY INTO @parquet_unload_gcs_stage/region
FROM SF01.TEST01.REGION
HEADER=TRUE;
```

For the minimal fields we need, you can refer to [Data Models](/developer-guide/data-ingest/data-model).

There are various parameters for COPY command which can limit the partitions and provide optimizations: [https://docs.snowflake.com/en/sql-reference/sql/copy-into-location.html](https://docs.snowflake.com/en/sql-reference/sql/copy-into-location.html)

### 6. Automate the Unloading

What we recommend is to automate the COPY command that unloads each day's events (single partition) into the external stage by using Snowflake TASK for it to run at a schedule: [https://docs.snowflake.com/en/sql-reference/sql/create-task.html](https://docs.snowflake.com/en/sql-reference/sql/create-task.html)

An example of same would be:

```
CREATE TASK copy_to_gcs
SCHEDULE = 'USING CRON 0 10 * * * Europe/Rome'
COMMENT = 'Test Schedule' AS
COPY INTO @parquet_unload_gcs_stage/region
from SF01.TEST01.REGION
HEADER=TRUE;
```

If you use Airflow on your side for orchestration you can also use that to schedule this query at a regular interval.

Alternatively we can fetch directly from Snowflake

## Snowflake Direct Access Setup

Create a dedicated Aampe user with read-only access to your data warehouse. Once configured, we'll handle the ETL scheduling on our side.

### Step 1: Switch to Account Admin

Run this in your Snowflake worksheet:

```sql theme={null}
USE ROLE ACCOUNTADMIN;
```

### Step 2: Create Role and User

Create a read-only role for Aampe (skip if you have an existing read-only role you'd prefer to use):

```sql theme={null}
CREATE ROLE AAMPE_ROLE;

CREATE USER AAMPE_DEVELOPER
  PASSWORD             = 'aampe_developer'     
  EMAIL                = 'developer@aampe.com'
  MUST_CHANGE_PASSWORD = FALSE
  DEFAULT_ROLE         = AAMPE_ROLE
  DEFAULT_WAREHOUSE    = <YOUR_WAREHOUSE>;

GRANT ROLE AAMPE_ROLE TO USER AAMPE_DEVELOPER;
```

### Step 3: Grant Read Access

Grant the role access to your warehouse, database, and tables. Adjust the scope as needed:

```sql theme={null}
USE ROLE ACCOUNTADMIN;

-- Current objects
GRANT USAGE ON WAREHOUSE <MY_WH> TO ROLE AAMPE_ROLE;
GRANT USAGE ON DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
GRANT USAGE ON ALL SCHEMAS IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
GRANT SELECT ON ALL TABLES IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
GRANT SELECT ON ALL VIEWS IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;

-- Future objects (so new tables are automatically accessible)
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
GRANT SELECT ON FUTURE TABLES IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
GRANT SELECT ON FUTURE VIEWS IN DATABASE <MY_DB> TO ROLE AAMPE_ROLE;
```

### Step 4: Share Connection Details

Send us the following:

* **Account** (from your URL, e.g., `tzviibq-hr75240` from `https://tzviibq-hr75240.snowflakecomputing.com`)
* **Warehouse Name**
* **Database Name**
* **Schema Name**
* **Table Names** (tables containing your event data)

Once we receive these, we'll configure the connection and begin syncing data at regular intervals.

**References:**

* [https://docs.snowflake.com/en/user-guide/data-load-gcs-config.html](https://docs.snowflake.com/en/user-guide/data-load-gcs-config.html)
* [https://docs.snowflake.com/en/user-guide/data-unload-prepare.html](https://docs.snowflake.com/en/user-guide/data-unload-prepare.html)


# AWS Aurora
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/database-aws-aurora

Instruction to connect Aampe to your Aurora instance

**AWS Aurora Integration Steps**

1. In your Aurora DB Instance, create an Aampe user and password:

   <img alt="Screenshot 2025-10-31 at 10.57.58 AM.png" />
2. Navigate to the database where your data is stored:

   <img alt="Screenshot 2025-10-31 at 10.58.32 AM.png" title="Screenshot 2025-10-31 at 10.58.32 AM.png" />
3. Grant the Aampe user the following permissions:

   <img alt="Screenshot 2025-10-31 at 10.58.50 AM.png" title="Screenshot 2025-10-31 at 10.58.50 AM.png" />
4. Provide us with the following information:

   * `username (the username of the Aampe user you created)`
   * `password (the password for this user)`
   * `region (the region your Aurora DB Cluster is hosted in)`
   * `endpoint (found in Connectivity & security, see screenshot below)`
   * `port (found in Connectivity & security, see screenshot below)`
   * `database name (the database schema where your event/user data tables are located)`
   * `tables (the tables containing your event/user data)`

   <img alt="Screenshot 2025-10-31 at 10.59.15 AM.png" />
5. Finally, in Aurora add the IP addresses provided by Aampe to your DB Instance Security Group Inbound and Outbound rules. We will send you the IPs.


# AWS RDS
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/database-aws-rds

Estimated setup time: 1 hour

This guide provides instructions for granting Aampe access to your AWS RDS database for data synchronization.

Grant Aampe direct read access to your RDS instance for real-time data synchronization.

### Requirements

* AWS account with an existing RDS instance
* Admin access to your AWS account
* RDS instance endpoint and database name
* Network access configured (Security Groups/VPC)

### Setup Steps

#### 1. Create Database User for Aampe

Connect to your RDS instance and create a read-only user:

```
-- For MySQL/MariaDB
CREATE USER 'aampe_reader'@'%' IDENTIFIED BY 'STRONG_PASSWORD_HERE';

-- For PostgreSQL
CREATE USER aampe_reader WITH PASSWORD 'STRONG_PASSWORD_HERE';

-- For SQL Server
CREATE LOGIN aampe_reader WITH PASSWORD = 'STRONG_PASSWORD_HERE';
CREATE USER aampe_reader FOR LOGIN aampe_reader;
```

#### 2. Grant Read Permissions

```
-- For MySQL/MariaDB
GRANT SELECT ON your_database.* TO 'aampe_reader'@'%';
FLUSH PRIVILEGES;

-- For PostgreSQL
GRANT CONNECT ON DATABASE your_database TO aampe_reader;
GRANT USAGE ON SCHEMA public TO aampe_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO aampe_reader;
-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO aampe_reader;

-- For SQL Server
USE your_database;
ALTER ROLE db_datareader ADD MEMBER aampe_reader;
```

#### 3. Configure Network Access

Update your RDS Security Group to allow Aampe's IP addresses:

```
# Add ingress rule to your RDS security group
aws ec2 authorize-security-group-ingress \
  --group-id sg-YOUR_SECURITY_GROUP_ID \
  --protocol tcp \
  --port YOUR_DB_PORT \
  --cidr AAMPE_IP_RANGE/32 \
  --group-rule-description "Aampe data sync access"
```

**Note:** Your Aampe representative will provide the specific IP addresses or ranges to allowlist.

#### 4. Enable SSL/TLS (Recommended)

```
# Download RDS CA certificate
wget https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

# For MySQL, enforce SSL for the Aampe user
mysql> ALTER USER 'aampe_reader'@'%' REQUIRE SSL;
```

#### 5. Provide Information to Aampe

Share the following with your Aampe representative:

* **Endpoint:** `your-instance.region.rds.amazonaws.com`
* **Port:** (default: MySQL 3306, PostgreSQL 5432, SQL Server 1433)
* **Database name**
* **Username:** `aampe_reader`
* **Password:** (share securely)
* **SSL certificate:** (if using SSL)
* **List of tables to sync**


# Spanner (Google)
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/database-spanner

Estimated setup time: 1 hour

## Option 1: Direct Read Access

Grant Aampe direct read access to your Spanner instance for real-time data synchronization.

### Requirements

* Google Cloud project with Spanner instance
* Admin access to your GCP project
* Spanner instance ID and database name

### Setup Steps

#### 1. Create a Service Account for Aampe

```
# Create service account
gcloud iam service-accounts create aampe-spanner-reader \
--display-name="Aampe Spanner Reader" \
--description="Service account for Aampe to read Spanner data"

# Get the service account email
gcloud iam service-accounts list --filter="displayName:Aampe Spanner Reader"
```

#### 2. Grant Spanner Access

```
# Grant database reader role
gcloud spanner databases add-iam-policy-binding YOUR_DATABASE_NAME \
--instance=YOUR_INSTANCE_ID \
--member="serviceAccount:aampe-spanner-reader@YOUR_PROJECT.iam.gserviceaccount.com" \
--role="roles/spanner.databaseReader"
```

#### 3. Create and Download Service Account Key

```
# Create key
gcloud iam service-accounts keys create aampe-spanner-key.json \
--iam-account=aampe-spanner-reader@YOUR_PROJECT.iam.gserviceaccount.com

# The key file will be downloaded to your current directory
```

#### 4. Provide Information to Aampe

Share the following with your Aampe representative:

* Service account key file (aampe-spanner-key.json)
* Project ID
* Spanner instance ID
* Database name
* List of tables to sync

## Option 2: BigQuery Federation (Recommended)

If you prefer not to grant direct Spanner access, you can set up BigQuery federation and grant access to BigQuery instead.

### Prerequisites

* BigQuery API enabled in your project
* Existing Spanner instance with data

### Setup Steps

#### 1. Create External Connection in BigQuery

```
-- In BigQuery Console
-- Navigate to "Add Data" > "External data source"
-- Select "Cloud Spanner" as source type
-- Configure:
-- Connection ID: aampe-spanner-connection
-- Location: [Match your Spanner region]
-- Spanner instance: YOUR_INSTANCE_ID
-- Spanner database: YOUR_DATABASE_NAME
```

#### 2. Create Views for Aampe Access

```
-- Create a dataset for Aampe views
CREATE SCHEMA IF NOT EXISTS `your_project.aampe_views`
OPTIONS(
description="Views for Aampe data access",
location="us-central1"
);

-- Create view for customer data
CREATE OR REPLACE VIEW `your_project.aampe_views.customers` AS
SELECT * FROM EXTERNAL_QUERY(
'projects/YOUR_PROJECT/locations/YOUR_LOCATION/connections/aampe-spanner-connection',
'''
SELECT
customer_id,
email,
created_at,
-- Include only fields needed by Aampe
FROM Customers
'''
);
```

#### 3. Grant BigQuery Access to Aampe

```
# Grant access to the views dataset
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:AAMPE_SERVICE_ACCOUNT" \
--role="roles/bigquery.dataViewer" \
--condition="expression=resource.name.startsWith('projects/YOUR_PROJECT/datasets/aampe_views'),title=Aampe Views Access"
```

#### 4. Share Connection Details

Provide Aampe with:

* Project ID
* Dataset name (aampe\_views)
* List of available views

## Option 3: Cross-Project Access for Dataflow

If Aampe will be running Dataflow jobs to extract your data, grant the necessary permissions for cross-project access.

### Prerequisites

* Aampe will provide you with a service account email that will run the Dataflow jobs

### Setup Steps

#### 1. Enable Required APIs

```
# Enable APIs that Aampe's Dataflow jobs will need
gcloud services enable spanner.googleapis.com --project=YOUR_PROJECT
```

#### 2. Grant Spanner Access

Grant Aampe's service account permission to read your Spanner data:

```
# Grant database reader role to Aampe's service account
gcloud spanner databases add-iam-policy-binding YOUR_DATABASE_NAME \
--instance=YOUR_INSTANCE_ID \
--member="serviceAccount:AAMPE_PROVIDED_SERVICE_ACCOUNT" \
--role="roles/spanner.databaseReader"

# If you want to limit access to specific tables, create a custom role
gcloud iam roles create aampeSpannerReader \
--project=YOUR_PROJECT \
--title="Aampe Spanner Reader" \
--description="Read access to specific Spanner tables for Aampe" \
--permissions="spanner.databases.select,spanner.sessions.create,spanner.sessions.get,spanner.sessions.delete"
```

#### 3. Network Configuration (if using VPC)

If your Spanner instance is in a VPC-enabled configuration:

```
# Option A: Add Aampe's project to your VPC Service Controls perimeter
gcloud access-context-manager perimeters update YOUR_PERIMETER \
--add-resources="projects/AAMPE_PROJECT_NUMBER"

# Option B: Create ingress rule for Aampe
gcloud access-context-manager perimeters update YOUR_PERIMETER \
--add-ingress-policies=ingress.yaml
```

**Example ingress.yaml:**

```
- ingressFrom:
    sources:
    - resource: projects/AAMPE_PROJECT_NUMBER
    identityType: ANY_IDENTITY
  ingressTo:
    operations:
    - serviceName: spanner.googleapis.com
      methodSelectors:
      - method: "*"
    resources:
    - projects/YOUR_PROJECT_NUMBER
```

Share the following details:

* Project ID
* Spanner instance ID
* Database name
* List of tables to sync
* Any network restrictions or VPC configurations

## Option 4: Real-time Streams

For real-time event streaming, set up Spanner change streams to publish to a Pub/Sub topic that Aampe can subscribe to / you can push to Aampe endpoints.

### Prerequisites

* Pub/Sub API enabled
* Spanner database with change streams support

### Setup Steps

#### 1. Create Change Streams

```
-- In Spanner
CREATE CHANGE STREAM aampe_customer_changes
FOR Customers(customer_id, email, status, updated_at)
OPTIONS (
retention_period = '7d',
value_capture_type = 'NEW_AND_OLD_VALUES'
);
```

#### 2. Create Pub/Sub Topic

```
# Create topic
gcloud pubsub topics create aampe-spanner-changes

# Grant Aampe subscription permissions
gcloud pubsub topics add-iam-policy-binding aampe-spanner-changes \
--member="serviceAccount:AAMPE_SERVICE_ACCOUNT" \
--role="roles/pubsub.subscriber"
```

#### 3. Set Up Change Stream Export

Use the Dataflow template to export changes:

```
gcloud dataflow jobs run aampe-change-stream-export \
--gcs-location gs://dataflow-templates/latest/Spanner_Change_Streams_to_PubSub \
--region YOUR_REGION \
--parameters \
spannerInstanceId=YOUR_INSTANCE,\
spannerDatabase=YOUR_DATABASE,\
spannerChangeStreamName=aampe_customer_changes,\
pubsubTopic=projects/YOUR_PROJECT/topics/aampe-spanner-changes
```

#### 4. Configure Dead Letter Queue (Optional)

```
# Create dead letter topic
gcloud pubsub topics create aampe-spanner-changes-dlq

# Create subscription with dead letter policy
gcloud pubsub subscriptions create aampe-changes-sub \
--topic=aampe-spanner-changes \
--dead-letter-topic=aampe-spanner-changes-dlq \
--max-delivery-attempts=5
```

## Performance Considerations

* Ensure indexes exist on frequently queried columns (customer\_id, created\_at)
* Consider partitioning large tables by date
* Monitor Spanner CPU utilization during sync operations

## Next Steps

Once configuration is complete:

* Notify your Aampe representative
* We'll verify the connection and begin initial data sync
* Monitor the first sync for any performance impacts
* Set up alerts for failed syncs (if using change streams)

***


# Firebase
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/firebase

Estimated setup time: 40 minutes

The Firebase data integration first sets up a Firebase to BigQuery export and then follows the steps to integrate Aampe with BigQuery as [shown here](/developer-guide/data-ingest/data-warehouse-bigquery).

## Export Firebase Event Data to BigQuery

1. Go to the **Integrations** page in the Firebase console.
2. In the **BigQuery** card, click **Link**.
3. After having read the details on the first page, click **Next**.
4. Toggle **Google Analytics** (this will enable exporting your app's click stream data).
5. Select the GCP region where you wish this data to be stored.
6. Toggle **Cloud Messaging** (this will enable exporting your push event data).
7. Select the GCP region where you wish this data to be stored.

This guide is based on: [https://firebase.google.com/docs/projects/bigquery-export](https://firebase.google.com/docs/projects/bigquery-export)

Now that you've set up the Firebase to BigQuery export, you can proceed to set up the BigQuery integration with Aampe.


# Mixpanel
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/mixpanel

Estimated setup time: 15 minutes

## Requirements

* Your Mixpanel's Project ID and Data Residency
* Service account credentials (Username & Secret)

Aampe will periodically pull from Mixpanel's [RAW data export API](https://developer.mixpanel.com/reference/raw-data-export-api).

## Getting the Project ID and Data Residency

1. Login to your Mixpanel account
2. Click on the **Settings** gearwheel placed at the top-right corner of your screen.
3. Select your organization under **ORGANIZATION SETTINGS**.

   <img alt="1 Organization Setting Pn" />
4. Navigate to **Projects**

   <img alt="2 Project Setting Pn" />
5. Choose the project with the data you wish Aampe to ingest.
6. You will find your **Project ID** and **Data Residency** in the table.

   <img alt="3 Project Id Pn" />

## Creating a Service Account

1. Log into your Mixpanel account
2. Click on the **Settings** gearwheel placed at the top-right corner of your screen.
3. Select your organization under **ORGANIZATION SETTINGS**

   <img alt="4 Service Account Pn" />
4. Navigate to **Service Accounts**
5. Click on **+ Add Service Account** at the top-right corner.

   <img alt="4b Service Account New Pn" />
6. Choose a **NAME** for your service account. For example: `aampe-data-export`
7. Select the **PROJECT(S)** with the data you wish Aampe to ingest.
8. Keep the **ORGANIZATION ROLE** as Member and **PROJECT ROLE** as Consumer.

   <img alt="5 Sa Role Pn" />
9. Click on **Create**
10. The service account Username and Secret will appear.

    <img alt="6 Secrets Sa Pn" />
11. Store the username and secret and then we will use these to query the Mixpanel API.
12. Navigate to **System Settings > Integrations > Data Import**

    <img alt="7 Aampe Mixpanel Pn" />
13. Select **Mixpanel** and add your credentials.

    <img alt="8 Aampe Menu Pn" />

***


# Segment
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/segment

Estimated setup time: 15 minutes

There are 3 ways to set up Aampe as a segment destination:

* Configure Aampe (Actions) Destination - Preferred
* Configure Aampe Destination
* Google Cloud Storage Destination

## Configure Aampe (Actions) Destination - Preferred

The newer actions based destination allows you to send track, page, screen and identify events. It also allows you to use region of choice for data residency.

1. Login to your Segment account at [https://app.segment.com/](https://app.segment.com/)
2. Select **Destinations** under Connections on the left side panel
3. Click on **Add Destination**
4. Enter **Aampe (Actions)** in the Filter Destinations searchbox.
5. On the Settings page you will see various options:
   * Give the name of the destination: "Aampe-Actions"
   * Your API Key:

     <Info>
       Note that you will need the Aampe API key that you can fetch from:

       1. Go to [https://compose.aampe.com/system-setup/integrations/events](https://compose.aampe.com/system-setup/integrations/events)
       2. Login using your org credentials
       3. Select **Connect** next to Aampe endpoint
       4. Copy the API key
     </Info>
6. Paste in the Aampe api key
7. Select your **data residency** (your preferred data region)
8. Change the mappings as needed depending on your data (Optional)

You should be all set sending data to Aampe.

## Configure Aampe Destination

1. Login to your Segment account at [https://app.segment.com/](https://app.segment.com/)
2. Select **Destinations** under Connections on the left side panel
3. Click on **Add Destination**
4. Enter **Aampe** in the Filter Destinations searchbox.
5. Click on the **Configure Aampe** button, select the data source for your app events, then click on **Next**.
6. Enter a destination name of your choice and click on **Save**. We recommend naming it "Aampe App Events"
7. Login to [Aampe Composer](https://compose.aampe.com/configure/integrations) in another browser tab, then go to **System Settings > Integrations**
8. Select **Segment**, and then copy the Segment API key from here.
9. Paste this key into the **API Key** field under Connection Settings on the Segment website (this is where we left off at Step 6.)

## Configure Google Cloud Storage Destination

**Requirements:**

* A Google Cloud bucket name. For example: `aampe-staging-data-xxx`
* A credentials file. For example: `xxxxxxxx-4e120-14a6f2ac3c25.json`

Aampe will provide both of these to you for setup.

1. Go to Segment's **Connection > Destinations** section
2. Click on **Add Destination**
3. Search for **Google Cloud Storage** in the catalog that appears
4. Click on the **Google Cloud Storage** destination
5. Click on **Configure Google Cloud Storage**.
6. Select the source you wish to share with Aampe and then click on **Confirm Source**. Source will be your data source housing the event data
7. You will then be redirected to a screen where you will provide the destination bucket details (provided by Aampe):
   * **Bucket:** the name of the bucket where the data will flow
   * **GCS Private Key File:** the content of the JSON with the access credentials to that bucket
8. After having input both details, you need to click on the toggle that enables this destination and the integration is completed

***


# SFTP
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/sftp

Estimated setup time: 1 day

If you don't push your event data into a 3rd party service, or have a pipeline for pushing to FTP, we also support that.

## The General Steps to Get This Working Are:

1. Aampe provides you with SFTP credentials.
2. You transfer event data daily, usually in JSON, ndJSON, CSV or parquet formats (we're happy to support more formats if needed).
3. The reference data schema is provided at [Data Models](/developer-guide/data-ingest/data-model)

***


# Aampe Streaming API
Source: https://kb.aampe.com/developer-guide/data-ingest/data-sources/streaming-aampe-api

Estimated setup time: 1 hour

The Aampe Events API endpoint allows you to post real-time event data to Aampe's system. This endpoint is designed for streaming live user interactions and activities as they occur within your application.

## Authentication

To use this API, you'll need an API key for authentication. [**You can find it by going to System Setup > Integrations > API keys and copying the Ingest API Key.**](/api-guide/api-keys)

## Endpoint Details

* **URL:** [https://ingestion.api.aampe.com/v1/events](https://ingestion.api.aampe.com/v1/events)
* **Method:** POST
* **Content-Type:** application/json

## Request Parameters

### Required Parameters

| Parameter | Type | Description |
| :- | :- | :- |
| contact\_id | string | Unique identifier for the user triggering the event. Must be at least 1 character long. |
| event\_name | string | Name of the event that occurred. Must be at least 1 character long. |
| timestamp | string | Unix timestamp when the event occurred. |

### Optional Parameters

| Parameter | Type | Description |
| :- | :- | :- |
| event\_id | string | Optional unique identifier for the event. |
| metadata | string | Optional JSON object containing additional event information. |

## Example Request

```
{
  "contact_id": "user123",
  "event_name": "button_click",
  "timestamp": 1638360000,
  "event_id": "evt_123456",
  "metadata": {
    "button_location": "header",
    "page": "home",
    "user_type": "premium"
  }
}
```

## Response Codes

| Code | Description |
| :- | :- |
| 202 | Event successfully received and accepted for processing |
| 422 | Validation error - request parameters are invalid |

## Error Response Example

```
{
  "detail": [
    {
      "loc": ["body", "contact_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Further Details

Find detailed developer documentation [here](/api-guide/api-guide).

***


# Event Properties
Source: https://kb.aampe.com/developer-guide/data-ingest/event-properties

Learn how to structure and implement event properties for Aampe

Event properties capture user interactions and activities within your application. This documentation outlines how to structure and use event properties effectively.

## Core Event Structure

Each event in the system follows this data model:

| Property | Type | Required | Description |
| - | - | - | - |
| contact\_id | String | Yes | A unique user identifier |
| timestamp | Timestamp | Yes | When the event happened in UTC |
| event\_name | String | Yes | Name corresponding to the triggered event |
| event\_instance\_id | String | No | Unique identifier for this specific event instance |
| metadata | JSON | No | Additional contextual data about the event |

## Common Event Types

### Navigation Events

Events that track how users move through your application:

* `page_viewed`
  * Metadata:
    * `page_name`: Name of the page (e.g., "homepage", "product\_detail")
    * `page_url`: Full URL of the page
    * `referrer_url`: Where the user came from
    * `session_id`: Current session identifier
* `feature_accessed`
  * Metadata:
    * `feature_name`: Name of accessed feature (e.g., "search", "filters")
    * `feature_location`: Where in the app the feature appears

### Transaction Events

Events that track commerce and financial activities:

* `product_viewed`
  * Metadata:
    * `product_id`: Unique product identifier
    * `product_name`: Name of the product
    * `product_category`: Category of the product
    * `product_price`: Current price
    * `currency`: Currency code (e.g., "USD")
* `product_added_to_cart`
  * Metadata:
    * `product_id`: Product identifier
    * `quantity`: Number of items added
    * `variant_id`: Product variant (if applicable)
    * `cart_id`: Current cart identifier
    * `cart_value`: New total cart value
* `checkout_started`
  * Metadata:
    * `cart_id`: Cart identifier
    * `cart_value`: Total value
    * `item_count`: Number of items
    * `coupon_code`: Applied discount code (if any)
* `order_completed`
  * Metadata:
    * `order_id`: Unique order identifier
    * `order_value`: Total value of order
    * `payment_method`: Method used (e.g., "credit\_card", "paypal")
    * `shipping_method`: Chosen shipping option
    * `products`: Array of purchased product IDs
    * `quantities`: Array of quantities (corresponding to products)

### Messaging Events

Events that track communication and notification activities:

* `message_sent`
  * Metadata:
    * `message_id`: Unique identifier for the message
    * `message_type`: Type of message (e.g., "text", "email", "push")
    * `recipient_id`: ID of the recipient
    * `template_id`: If using a template, the template identifier
    * `campaign_id`: Associated marketing campaign (if applicable)
* `message_delivered`
  * Metadata:
    * `message_id`: Message identifier
    * `delivery_timestamp`: When message was delivered
    * `delivery_status`: Status (e.g., "delivered", "failed")
* `message_opened`
  * Metadata:
    * `message_id`: Message identifier
    * `open_timestamp`: When message was opened
    * `device_type`: Device used to open (e.g., "mobile", "desktop")
* `message_clicked`
  * Metadata:
    * `message_id`: Message identifier
    * `link_id`: Identifier for the specific link
    * `link_url`: Target URL
    * `click_timestamp`: When click occurred

### Engagement Events

Events that track how users interact with content:

* `content_viewed`
  * Metadata:
    * `content_id`: Content identifier
    * `content_type`: Type of content (e.g., "article", "video")
    * `category`: Content category
    * `duration`: Time spent viewing (seconds)
* `video_played`
  * Metadata:
    * `video_id`: Video identifier
    * `video_title`: Video title
    * `duration`: Length of video in seconds
    * `play_position`: Starting position in seconds
    * `quality`: Selected video quality

### Account Events

Events tracking user account activities:

* `user_registered`
  * Metadata:
    * `registration_method`: How they signed up (e.g., "email", "google")
    * `referral_source`: Where they came from
    * `initial_plan`: Selected plan (if applicable)
* `user_logged_in`
  * Metadata:
    * `login_method`: Authentication method used
    * `device_type`: Type of device used
    * `app_version`: Application version

## Industry-Specific Events

### E-commerce Events

* `product_searched`
  * Metadata:
    * `search_term`: User's search query
    * `filter_applied`: Any filters used
    * `results_count`: Number of results
    * `category_context`: Category being searched
* `wishlist_updated`
  * Metadata:
    * `product_id`: Product identifier
    * `action`: "added" or "removed"
    * `wishlist_count`: New total count
* `review_submitted`
  * Metadata:
    * `product_id`: Product identifier
    * `rating`: Numerical rating (e.g., 1-5)
    * `review_length`: Character count of review
    * `has_media`: Contains photos/videos (boolean)

### Gaming Events

* `game_started`
  * Metadata:
    * `game_mode`: Selected mode
    * `map_id`: Game environment
    * `character_id`: Selected character/class
    * `difficulty`: Game difficulty
* `level_completed`
  * Metadata:
    * `level_id`: Level identifier
    * `score`: Achieved score
    * `time_taken`: Completion time in seconds
    * `attempts`: Number of attempts
    * `stars_earned`: Achievement rating
* `in_app_purchase`
  * Metadata:
    * `item_id`: Purchased item identifier
    * `item_type`: Type of virtual item
    * `price`: Cost in real currency
    * `currency`: Currency code
    * `purchase_location`: Where in game purchase was made

### Food Delivery Events

* `restaurant_searched`
  * Metadata:
    * `search_term`: Search keywords
    * `cuisine_filter`: Any cuisine filters applied
    * `location`: Search location
    * `results_count`: Number of results
* `menu_item_viewed`
  * Metadata:
    * `restaurant_id`: Restaurant identifier
    * `item_id`: Menu item identifier
    * `item_category`: Food category
    * `item_price`: Price
    * `dietary_tags`: Array of applicable dietary tags
* `delivery_status_changed`
  * Metadata:
    * `order_id`: Order identifier
    * `new_status`: Current status (e.g., "preparing", "out\_for\_delivery")
    * `estimated_arrival`: Updated ETA
    * `driver_id`: Delivery person identifier


# Data sync and rate limits
Source: https://kb.aampe.com/developer-guide/data-ingest/rate-limits

Aampe Data Sync & Rate Limits

## Messaging Operations

Expected delays and rate limits for sending messages

### Processing Times

* Messages scheduled through the system require up to 30 minutes for processing and dispatch. Any message has to be scheduled at least 30 minutes into the future
* No internal rate limits apply to message volumes from Aampe's infrastructure
* External delivery tool limits must be observed

**High Volume Handling** For high-volume messaging scenarios, we support message batching configuration to optimize delivery tool integration.

## Data Processing Windows

Expected delays with new data being available in Aampe Composer for messages and Audience segmentation.

**User Attribute Updates** New user attributes require up to 24 hours from initial ingestion to become available in the Aampe composer for audience segmentation purposes. Example: New custom fields like **loyalty\_tier** or **last\_purchase\_date**

<Info>
  Actual processing times may be shorter depending on system load

  All timeframes represent maximum processing windows

  If your use case requires faster processing times feel free to contact us
</Info>


# User Events sample data
Source: https://kb.aampe.com/developer-guide/data-ingest/user-events-sample-data

A set of dummy events of several industries which help understand the Aampe data model

## Industry-Specific Event Samples

This guide provides comprehensive event examples for different industries, showing how to structure your events using the Aampe API/data dump. Each sample includes complete JSON payloads that you can adapt for your specific use case.

## E-commerce & Retail

### Product Discovery Journey

**Product Search Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_456789",
    "event_name": "product_searched",
    "timestamp": 1672531200,
    "event_id": "search_001",
    "metadata": {
      "search_term": "wireless headphones",
      "category": "electronics",
      "filters_applied": ["brand:sony", "price:50-200"],
      "results_count": 24,
      "search_location": "header_search",
      "session_id": "sess_abc123"
    }
  }
  ```
</CodeGroup>

**Product View Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_456789",
    "event_name": "product_viewed",
    "timestamp": 1672531260,
    "event_id": "view_001",
    "metadata": {
      "product_id": "prod_WH001",
      "product_name": "Sony WH-1000XM4 Wireless Headphones",
      "product_category": "Electronics > Audio > Headphones",
      "product_price": 299.99,
      "currency": "USD",
      "brand": "Sony",
      "in_stock": true,
      "product_rating": 4.5,
      "total_reviews": 1247,
      "referrer_source": "search_results"
    }
  }
  ```
</CodeGroup>

### Shopping Cart Journey

**Add to Cart Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_456789",
    "event_name": "product_added_to_cart",
    "timestamp": 1672531320,
    "event_id": "cart_add_001",
    "metadata": {
      "product_id": "prod_WH001",
      "quantity": 1,
      "variant_id": "color_black",
      "cart_id": "cart_xyz789",
      "unit_price": 299.99,
      "cart_value": 299.99,
      "cart_item_count": 1,
      "add_source": "product_page",
      "discount_applied": false
    }
  }
  ```
</CodeGroup>

**Checkout Started Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_456789",
    "event_name": "checkout_started",
    "timestamp": 1672531500,
    "event_id": "checkout_001",
    "metadata": {
      "cart_id": "cart_xyz789",
      "cart_value": 299.99,
      "item_count": 1,
      "shipping_method": "standard",
      "payment_method_selected": "credit_card",
      "coupon_code": "WELCOME10",
      "discount_amount": 29.99,
      "final_amount": 269.99,
      "currency": "USD"
    }
  }
  ```
</CodeGroup>

**Purchase Completed Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_456789",
    "event_name": "order_completed",
    "timestamp": 1672531800,
    "event_id": "order_001",
    "metadata": {
      "order_id": "ORD_2023_001",
      "order_value": 269.99,
      "payment_method": "visa_ending_1234",
      "shipping_method": "standard_delivery",
      "products": ["prod_WH001"],
      "quantities": [1],
      "shipping_address": "New York, NY",
      "estimated_delivery": "2023-01-03",
      "is_first_purchase": false,
      "order_source": "web"
    }
  }
  ```
</CodeGroup>

## SaaS & Software

### User Onboarding Flow

**Account Registration Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_789012",
    "event_name": "user_registered",
    "timestamp": 1672532000,
    "event_id": "reg_001",
    "metadata": {
      "registration_method": "email",
      "email_domain": "company.com",
      "referral_source": "google_ads",
      "utm_campaign": "winter_promotion",
      "selected_plan": "starter",
      "team_size": "1-10",
      "industry": "marketing",
      "use_case": "email_campaigns",
      "trial_days": 14
    }
  }
  ```
</CodeGroup>

**Feature Adoption Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_789012",
    "event_name": "feature_first_used",
    "timestamp": 1672532400,
    "event_id": "feature_001",
    "metadata": {
      "feature_name": "email_builder",
      "feature_category": "core",
      "time_to_adoption": 3600,
      "user_tenure_days": 1,
      "session_id": "sess_def456",
      "guided_tour_completed": true,
      "help_docs_accessed": ["getting_started", "email_templates"]
    }
  }
  ```
</CodeGroup>

### Engagement & Usage

**Project Created Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_789012",
    "event_name": "project_created",
    "timestamp": 1672532800,
    "event_id": "proj_001",
    "metadata": {
      "project_id": "proj_ABC123",
      "project_name": "Q1 Newsletter Campaign",
      "project_type": "email_campaign",
      "template_used": "newsletter_modern",
      "team_members_invited": 2,
      "estimated_send_volume": 5000,
      "creation_source": "dashboard"
    }
  }
  ```
</CodeGroup>

**Subscription Upgraded Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_789012",
    "event_name": "subscription_upgraded",
    "timestamp": 1672533200,
    "event_id": "sub_upgrade_001",
    "metadata": {
      "previous_plan": "starter",
      "new_plan": "professional",
      "upgrade_reason": "usage_limit_reached",
      "annual_billing": true,
      "upgrade_value": 588.00,
      "features_unlocked": ["advanced_analytics", "a_b_testing", "priority_support"],
      "trial_days_remaining": 7
    }
  }
  ```
</CodeGroup>

## Media & Entertainment

### Content Consumption

**Video Started Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_345678",
    "event_name": "video_started",
    "timestamp": 1672534000,
    "event_id": "video_start_001",
    "metadata": {
      "video_id": "vid_DEF789",
      "video_title": "Advanced React Patterns",
      "video_duration": 2400,
      "video_category": "Technology",
      "series_id": "series_react_mastery",
      "episode_number": 5,
      "video_quality": "1080p",
      "device_type": "desktop",
      "player_version": "v2.1.0",
      "autoplay": false
    }
  }
  ```
</CodeGroup>

**Content Engagement Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_345678",
    "event_name": "video_progress",
    "timestamp": 1672534600,
    "event_id": "video_progress_001",
    "metadata": {
      "video_id": "vid_DEF789",
      "progress_percentage": 25,
      "watch_time": 600,
      "playback_speed": 1.0,
      "quality_changes": 0,
      "paused_count": 2,
      "seek_count": 1,
      "engagement_score": 0.85
    }
  }
  ```
</CodeGroup>

**Subscription Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_345678",
    "event_name": "content_creator_followed",
    "timestamp": 1672535000,
    "event_id": "follow_001",
    "metadata": {
      "creator_id": "creator_tech_guru",
      "creator_name": "Tech Guru",
      "creator_category": "Technology",
      "follower_count": 125000,
      "follow_source": "video_page",
      "notification_enabled": true,
      "user_following_count": 47
    }
  }
  ```
</CodeGroup>

## Food & Beverage Delivery

### Restaurant Discovery

**Restaurant Search Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_901234",
    "event_name": "restaurant_searched",
    "timestamp": 1672535400,
    "event_id": "rest_search_001",
    "metadata": {
      "search_term": "italian pizza",
      "location": "Manhattan, NY",
      "delivery_time_filter": "30_minutes",
      "price_range_filter": "$$",
      "cuisine_filters": ["italian"],
      "dietary_filters": ["vegetarian_options"],
      "results_count": 18,
      "sort_by": "delivery_time"
    }
  }
  ```
</CodeGroup>

**Menu Browsing Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_901234",
    "event_name": "menu_item_viewed",
    "timestamp": 1672535600,
    "event_id": "menu_view_001",
    "metadata": {
      "restaurant_id": "rest_mario_pizza",
      "restaurant_name": "Mario's Authentic Pizza",
      "item_id": "item_margherita_large",
      "item_name": "Large Margherita Pizza",
      "item_category": "Pizza",
      "item_price": 18.99,
      "item_description": "Fresh mozzarella, basil, tomato sauce",
      "dietary_tags": ["vegetarian"],
      "prep_time": 20,
      "popularity_rank": 2
    }
  }
  ```
</CodeGroup>

### Order & Delivery Journey

**Order Placed Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_901234",
    "event_name": "order_placed",
    "timestamp": 1672536000,
    "event_id": "order_food_001",
    "metadata": {
      "order_id": "ORD_FOOD_001",
      "restaurant_id": "rest_mario_pizza",
      "order_value": 28.47,
      "delivery_fee": 2.99,
      "service_fee": 1.99,
      "tip_amount": 4.50,
      "total_amount": 28.47,
      "items": [
        {
          "item_id": "item_margherita_large",
          "quantity": 1,
          "unit_price": 18.99,
          "customizations": ["extra_cheese"]
        }
      ],
      "delivery_address": "123 Main St, Apt 4B",
      "estimated_delivery": 35,
      "payment_method": "credit_card"
    }
  }
  ```
</CodeGroup>

**Delivery Tracking Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_901234",
    "event_name": "delivery_status_updated",
    "timestamp": 1672536800,
    "event_id": "delivery_update_001",
    "metadata": {
      "order_id": "ORD_FOOD_001",
      "status": "out_for_delivery",
      "previous_status": "preparing",
      "estimated_arrival": 1672537200,
      "driver_id": "driver_john_d",
      "driver_name": "John D.",
      "driver_rating": 4.8,
      "delivery_vehicle": "bicycle",
      "live_tracking_enabled": true
    }
  }
  ```
</CodeGroup>

## Gaming & Entertainment

### Game Session Events

**Game Session Started Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_567890",
    "event_name": "game_session_started",
    "timestamp": 1672537200,
    "event_id": "game_start_001",
    "metadata": {
      "game_id": "adventure_quest_mobile",
      "game_version": "v1.2.3",
      "player_level": 15,
      "character_class": "warrior",
      "game_mode": "story_campaign",
      "chapter_id": "chapter_3",
      "device_type": "mobile",
      "platform": "ios",
      "session_id": "game_sess_xyz123"
    }
  }
  ```
</CodeGroup>

**Achievement Unlocked Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_567890",
    "event_name": "achievement_unlocked",
    "timestamp": 1672537800,
    "event_id": "achievement_001",
    "metadata": {
      "achievement_id": "first_boss_defeated",
      "achievement_name": "Dragon Slayer",
      "achievement_category": "combat",
      "achievement_rarity": "rare",
      "points_earned": 100,
      "reward_type": "gold",
      "reward_amount": 500,
      "player_level": 15,
      "completion_percentage": 0.25
    }
  }
  ```
</CodeGroup>

**In-App Purchase Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_567890",
    "event_name": "in_app_purchase_completed",
    "timestamp": 1672538400,
    "event_id": "iap_001",
    "metadata": {
      "product_id": "gold_pack_large",
      "product_name": "Large Gold Pack",
      "product_type": "consumable",
      "price_usd": 9.99,
      "local_price": 9.99,
      "currency": "USD",
      "store": "app_store",
      "purchase_location": "shop_main",
      "player_level": 15,
      "gold_amount": 10000,
      "bonus_percentage": 20
    }
  }
  ```
</CodeGroup>

## Healthcare & Fitness

### Fitness Tracking

**Workout Started Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_111222",
    "event_name": "workout_started",
    "timestamp": 1672539000,
    "event_id": "workout_001",
    "metadata": {
      "workout_id": "workout_hiit_001",
      "workout_name": "30-Min HIIT Blast",
      "workout_type": "HIIT",
      "workout_category": "cardio",
      "instructor_id": "trainer_sarah_j",
      "estimated_duration": 1800,
      "difficulty_level": "intermediate",
      "equipment_needed": ["dumbbells", "mat"],
      "calories_target": 300,
      "device_type": "mobile"
    }
  }
  ```
</CodeGroup>

**Health Metric Logged Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_111222",
    "event_name": "health_metric_logged",
    "timestamp": 1672540800,
    "event_id": "health_log_001",
    "metadata": {
      "metric_type": "weight",
      "metric_value": 165.5,
      "metric_unit": "lbs",
      "measurement_date": "2023-01-01",
      "data_source": "manual_entry",
      "goal_progress": 0.75,
      "trend_direction": "decreasing",
      "notes": "Morning weigh-in after workout"
    }
  }
  ```
</CodeGroup>

## Financial Services

### Account Activity

**Transaction Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_333444",
    "event_name": "transaction_completed",
    "timestamp": 1672541400,
    "event_id": "txn_001",
    "metadata": {
      "transaction_id": "TXN_2023_001",
      "transaction_type": "transfer",
      "amount": 250.00,
      "currency": "USD",
      "from_account": "checking_001",
      "to_account": "savings_001",
      "category": "savings",
      "method": "mobile_app",
      "fee_amount": 0.00,
      "balance_after": 1750.00,
      "merchant_name": null,
      "is_recurring": false
    }
  }
  ```
</CodeGroup>

**Investment Activity Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_333444",
    "event_name": "investment_order_placed",
    "timestamp": 1672542000,
    "event_id": "invest_001",
    "metadata": {
      "order_id": "INV_ORD_001",
      "order_type": "buy",
      "security_symbol": "AAPL",
      "security_name": "Apple Inc.",
      "quantity": 10,
      "order_value": 1500.00,
      "order_method": "market_order",
      "account_type": "individual_taxable",
      "portfolio_percentage": 0.15,
      "investment_goal": "growth"
    }
  }
  ```
</CodeGroup>

## Education & Learning

### Course Engagement

**Lesson Started Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_555666",
    "event_name": "lesson_started",
    "timestamp": 1672542600,
    "event_id": "lesson_001",
    "metadata": {
      "course_id": "course_javascript_fundamentals",
      "course_name": "JavaScript Fundamentals",
      "lesson_id": "lesson_variables_functions",
      "lesson_name": "Variables and Functions",
      "lesson_number": 3,
      "lesson_type": "video",
      "estimated_duration": 900,
      "difficulty_level": "beginner",
      "prerequisites_completed": true,
      "course_progress": 0.20
    }
  }
  ```
</CodeGroup>

**Assessment Completed Event**

<CodeGroup>
  ```json json theme={null}
  {
    "contact_id": "user_555666",
    "event_name": "assessment_completed",
    "timestamp": 1672543500,
    "event_id": "assessment_001",
    "metadata": {
      "assessment_id": "quiz_js_basics",
      "assessment_type": "quiz",
      "score": 85,
      "max_score": 100,
      "passing_score": 70,
      "passed": true,
      "questions_total": 20,
      "questions_correct": 17,
      "time_taken": 600,
      "attempts": 1,
      "lesson_id": "lesson_variables_functions"
    }
  }
  ```
</CodeGroup>

These samples provide a foundation for implementing comprehensive event tracking across different industries.


# User Attributes
Source: https://kb.aampe.com/developer-guide/data-ingest/user-properties

Learn how to structure and implement user attributes for Aampe

User properties are attributes and characteristics associated with individual users in your application. They help Aampe

1. understand user behavior and associate patterns with other users
2. segment your audience
3. personalize experiences and messaging copy.

This documentation outlines common user properties and their usage. This is just a comprehensive list of all possible user properties. You can share whatever data is available in your system and is applicable as per your use-cases.

## Core User Properties

### Identification Properties

* `user_id`: Unique identifier for the user (e.g., "usr\_12345")
* `anonymous_id`: Temporary identifier for users before they sign up (e.g., "anon\_789xyz")
* `notification_token`: Notification token of the user for push

### Profile Information

* `full_name`: Complete name (e.g., "John Doe")
* `username`: Chosen username (e.g., "johndoe123")
* `language`: Preferred language (e.g., "en-US")
* `timezone`: User's timezone (e.g., "America/New\_York")

### Demographics

* `gender`: User's gender (e.g., "female", "male", "non-binary")
* `country`: Country of residence (e.g., "United States")
* `city`: City of residence (e.g., "San Francisco")

## Account Properties

### Subscription Data

* `plan_name`: Current subscription plan (e.g., "premium", "basic", "enterprise")
* `plan_price`: Price of current plan (e.g., 99.99)
* `billing_interval`: Billing frequency (e.g., "monthly", "annual")
* `trial_end_date`: When free trial expires (e.g., "2024-02-15")
* `subscription_status`: Current status (e.g., "active", "canceled", "past\_due")

### Account Status

* `account_type`: Type of account (e.g., "individual", "business")
* `account_status`: Current standing (e.g., "active", "suspended", "deleted")
* `created_at`: Account creation date (e.g., "2023-01-15T10:30:00Z")
* `last_login_at`: Most recent login timestamp
* `is_verified`: Email verification status (e.g., true/false)

## Behavioral Properties

### Engagement Metrics

* `login_count`: Number of times logged in (e.g., 42)
* `last_active_at`: Last activity timestamp
* `total_sessions`: Total number of sessions
* `average_session_duration`: Average time per session (in minutes)

### Transaction Data

* `lifetime_value`: Total revenue from user (e.g., 599.99)
* `total_purchases`: Number of completed purchases
* `last_purchase_date`: Date of most recent purchase
* `average_order_value`: Average spending per order
* `payment_method`: Preferred payment method (e.g., "credit\_card", "paypal")

## Industry-Specific Properties

### E-commerce Properties

* `cart_value`: Current shopping cart total (e.g., 129.99)
* `abandoned_cart_count`: Number of abandoned carts (e.g., 3)
* `favorite_categories`: Array of preferred shopping categories (e.g., \["electronics", "fashion"])
* `last_viewed_products`: Array of recently viewed product IDs
* `shipping_addresses`: Array of saved delivery addresses
* `preferred_payment_methods`: Array of saved payment methods
* `wishlist_count`: Number of items in wishlist
* `return_rate`: Percentage of returned items (e.g., 2.5)
* `average_order_frequency`: Days between purchases (e.g., 45)
* `loyalty_points`: Current reward points balance (e.g., 500)
* `vip_tier`: Loyalty program level (e.g., "gold", "platinum")
* `lifetime_value`: (users total lifetime value)
* `currency`: (users transaction currency)

### Gaming Properties

* `player_level`: Current game level (e.g., 42)
* `total_playtime`: Time spent in game (in hours)
* `current_rank`: Competitive ranking (e.g., "diamond")
* `achievement_count`: Number of completed achievements
* `preferred_game_modes`: Array of favorite modes (e.g., \["battle\_royale", "team\_deathmatch"])
* `in_game_purchases`: Total spent on virtual items
* `active_character`: Current character/class being used
* `win_rate`: Percentage of games won
* `last_match_played`: Timestamp of last game session
* `inventory_items`: Array of owned virtual items
* `friend_count`: Number of in-game friends
* `preferred_server`: Default game server region

### Food Delivery Properties

* `dietary_preferences`: Array of dietary requirements (e.g., \["vegetarian", "gluten-free"])
* `favorite_cuisines`: Array of preferred cuisine types (e.g., \["italian", "thai"])
* `average_order_size`: Typical number of items per order
* `delivery_address_count`: Number of saved addresses
* `order_frequency`: How often they order (e.g., "weekly")
* `favorite_restaurants`: Array of frequently ordered restaurant IDs
* `last_cuisine_ordered`: Type of food in last order
* `delivery_instructions`: Special delivery notes
* `meal_preferences`: Preferred meal types (e.g., \["lunch", "dinner"])
* `group_order_frequency`: How often they place group orders
* `review_count`: Number of restaurant reviews submitted
* `average_rating`: Average rating given to restaurants

## Custom Properties

### Marketing Data

* `acquisition_source`: How user found you (e.g., "google\_ads", "referral")
* `acquisition_campaign`: Specific campaign (e.g., "summer\_2024")
* `email_subscription`: Newsletter status (e.g., true/false)
* `marketing_preferences`: JSON object with communication preferences

## Example JSON Representation

<CodeGroup>
  ```Text json theme={null}
  {  
     "user_id":"usr_5f3a9c2e",  
     "first_name":"Sarah",  
     "last_name":"Parker",  
     "account_type":"business",  
     "plan_name":"enterprise",  
     "created_at":"2023-12-01T08:30:00Z",  
     "last_login_at":"2024-01-26T15:45:22Z",  
     "company_name":"TechCorp Solutions",  
     "role":"Product Manager",  
     "country":"United States",  
     "timezone":"America/Los_Angeles",  
     "lifetime_value":2499.99,  
     "login_count":157,  
     "is_verified":true,  
     "subscription_status":"active",  
     "trial_end_date":"2024-02-15",  
     "marketing_preferences":{  
        "email":true,  
        "sms":false  
     },  
     "feature_usage":{  
        "dashboard":42,  
        "reports":15  
     },  
     "acquisition_source":"google_ads",  
     "last_purchase_date":"2024-01-15",  
     "plan_price":299.99,
     "company_size":"100-500",
     "language":"en-US",
     "avatar_url":"https://assets.company.com/avatars/sp.jpg"  
  }
  ```
</CodeGroup>


# Developer Guide
Source: https://kb.aampe.com/developer-guide/developer-guide

Explore our integration guides and examples

<CardGroup>
  <Card title="Set Up SSO" icon="lock" href="/developer-guide/sso/setting-up-sso">
    Aampe supports all the common SSO platforms.
  </Card>

  <Card title="Send Data to Aampe" icon="database" href="/developer-guide/data-ingest/data-integrations">
    Find integration guides and data modelling suggestions.
  </Card>

  <Card title="Connect Messaging Partners" icon="message" href="/developer-guide/message-providers/message-providers">
    Aampe works through your existing stack for email, push, and SMS.
  </Card>

  <Card title="Embed Aampe in an App or Website" icon="tablet" href="/developer-guide/surfaces/surfaces-embed">
    Personalize the text or layout elements in your app or website.
  </Card>

  <Card title="Integrate a Product Recommender System" icon="star" href="/developer-guide/cms-integration/recommender-systems">
    Embed product recommendations into Aampe messages.
  </Card>

  <Card title="Get Aampe Data" icon="brain" href="/developer-guide/aampe-data/data-share-overview">
    Bring Aampe user-profile and decision data into your data warehouse.
  </Card>
</CardGroup>

### Featured Pages

* [What kind of data do we send to Aampe?](/developer-guide/data-ingest/data-integrations)
* [What data does Aampe share with us?](/developer-guide/aampe-data/data-share-overview)


# Integrations
Source: https://kb.aampe.com/developer-guide/integrations

What kind of integration would you like to set up today? 

<CardGroup>
  <Card title="Send Data to Aampe" icon="database" href="/developer-guide/data-ingest/data-integrations">
    What data should we send? What should it look like? Batch or streaming?
  </Card>

  <Card title="Connect Messaging Partners" icon="message" href="/developer-guide/message-providers/message-providers">
    Connect to 20 popular messaging partners (Braze, CleverTap, etc.) or set up a custom integration.
  </Card>
</CardGroup>


# Adobe Campaign Classic Integration
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/adobe-campaign-classic

Connect Aampe to Adobe Campaign Classic Message Center for Email and Push notifications

Estimated setup time: 30-45 minutes

<Note>
  This guide is for **Adobe Campaign Classic (ACC)** using the Message Center module. For Adobe Campaign Standard (ACS), see [Adobe Campaign Integration](/developer-guide/message-providers/message-pages/adobe-campaign-standard).
</Note>

## Connection Requirements

Aampe connects to ACC Message Center via the SOAP API (PushEvent method).

### Required from Customer

| Requirement | Description |
| - | - |
| Message Center URL | Execution instance URL (e.g., `https://mc.customer.campaign.adobe.com`) |
| API User Credentials | Username and password for Message Center access |
| Whitelisted IPs | Aampe IPs must be added to trusted IP addresses |
| Unsubscribe Endpoint URL | Your unsubscribe endpoint that supports One-Click List-Unsubscribe |

<Info>
  Contact your Aampe representative to receive the list of IP addresses that need to be whitelisted.
</Info>

### Locate Your Message Center URL

1. Log in to Adobe Campaign Classic console
2. Navigate to **Administration** → **Platform** → **External accounts**
3. Find the **Message Center execution instance** account
4. Copy the **Server** URL

### Unsubscribe Endpoint Requirements

Your unsubscribe endpoint must:

* Accept POST requests (for One-Click List-Unsubscribe from Gmail/Yahoo)
* Accept a user identifier parameter that Aampe will populate per message
* Return HTTP 200 on successful unsubscribe

Provide Aampe with:

* **Base URL:** e.g., `https://yourcompany.com/unsubscribe`
* **Parameter name:** e.g., `uid`, `token`, or `email`

Aampe will construct the full URL per message: `https://yourcompany.com/unsubscribe?uid={user_identifier}`

## Email Channel Setup

### Step 1: Create Event Type

1. Navigate to **Administration** → **Platform** → **Enumerations**
2. Find **Event type (eventType)** enumeration
3. Click **Add** to create a new value:
   * **Name:** `aampe_email`
   * **Label:** `Aampe Email`

### Step 2: Create Message Template

1. Navigate to **Message Center** → **Transactional message templates**
2. Right-click and select **New**
3. Select **Email delivery** as the template type
4. Configure template properties:
   * **Label:** `Aampe Marketing Email`
   * **Internal name:** `aampe_email`
   * **Event type:** Select `aampe_email` from dropdown

### Step 3: Configure Sender Details

In the template's **From** section, configure sender to use Aampe payload:

| Field | Value |
| - | - |
| From email | `<%= rtEvent.ctx.fromEmail %>` |
| From name | `<%= rtEvent.ctx.fromName %>` |

### Step 4: Configure Email Content

Aampe sends complete HTML content in the API payload. Configure your template as a passthrough:

**Subject Line:**

```
<%= rtEvent.ctx.subject %>
```

**HTML Content (Source tab):**

```html theme={null}
<%= rtEvent.ctx.body %>
```

<Warning>
  Do not add any additional HTML structure. Aampe provides the complete email content including all styling and layout.
</Warning>

### Step 5: Configure SMTP Headers for Unsubscribe

This step is required for email deliverability compliance (Gmail/Yahoo One-Click Unsubscribe).

1. Open template properties (click **Properties** button)
2. Go to **SMTP** tab
3. In **Additional SMTP headers**, add:

```
List-Unsubscribe: <<%= rtEvent.ctx.unsubscribeUrl %>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

### Step 6: Publish Template

1. Click **Publish** in the template toolbar
2. Select target execution instance(s)
3. Confirm publication

<Check>
  Your email template is now ready. Aampe will send events to trigger personalized emails.
</Check>

***

## Push Notification Channel Setup

### Step 1: Create Event Type for Push

1. Navigate to **Administration** → **Platform** → **Enumerations**
2. Find **Event type (eventType)** enumeration
3. Click **Add** to create a new value:
   * **Name:** `aampe_push`
   * **Label:** `Aampe Push`

### Step 2: Verify Mobile App Channel

<Note>
  Push notifications require the Mobile App Channel package to be installed on your ACC instance. Contact your Adobe administrator if not available.
</Note>

Verify your mobile app is configured:

1. Navigate to **Administration** → **Channels** → **Mobile app**
2. Confirm your iOS/Android apps are registered

### Step 3: Create Push Message Template

1. Navigate to **Message Center** → **Transactional message templates**
2. Right-click and select **New**
3. Select **Mobile delivery (Push notification)** as the template type
4. Configure template properties:
   * **Label:** `Aampe Push Notification`
   * **Internal name:** `aampe_push`
   * **Event type:** Select `aampe_push` from dropdown

### Step 4: Configure Push Content

Configure push content fields to use Aampe payload:

| Field | Value |
| - | - |
| Title | `<%= rtEvent.ctx.title %>` |
| Body | `<%= rtEvent.ctx.body %>` |
| Deep link / URL | `<%= rtEvent.ctx.link %>` |
| Image URL (iOS/Android) | `<%= rtEvent.ctx.imageUrl %>` |

<Tabs>
  <Tab title="iOS">
    In iOS-specific settings:

    * **Alert title:** `<%= rtEvent.ctx.title %>`
    * **Alert body:** `<%= rtEvent.ctx.body %>`
    * **Media URL:** `<%= rtEvent.ctx.imageUrl %>`
  </Tab>

  <Tab title="Android">
    In Android-specific settings:

    * **Title:** `<%= rtEvent.ctx.title %>`
    * **Message:** `<%= rtEvent.ctx.body %>`
    * **Image URL:** `<%= rtEvent.ctx.imageUrl %>`
  </Tab>
</Tabs>

### Step 5: Publish Template

1. Click **Publish** in the template toolbar
2. Select target execution instance(s)
3. Confirm publication

<Check>
  Your push notification template is now ready.
</Check>

## Field Reference

### Email Payload Fields

Aampe sends these fields in the `ctx` element:

| Field | Type | Description |
| - | - | - |
| `fromEmail` | String | Sender email address |
| `fromName` | String | Sender display name |
| `subject` | String | Email subject line |
| `body` | String | Complete HTML email content |
| `unsubscribeUrl` | String | Full unsubscribe URL with user identifier |

### Push Payload Fields

| Field | Type | Description |
| - | - | - |
| `title` | String | Push notification title |
| `body` | String | Push notification body text |
| `link` | String | Deep link or URL to open |
| `imageUrl` | String | Rich media image URL |

## Validation Checklist

Before going live, verify with your Aampe representative:

* **API Connectivity** - Aampe can successfully authenticate to your Message Center instance
* **Test Email** - Send a test email and verify sender name/email, content rendering, subject line, unsubscribe header presence (check raw email headers), and link tracking
* **Test Push** - Send a test push notification and verify title/body text, deep link opens the correct screen, and image loads (if using rich push)
* **Test Unsubscribe** - Click the unsubscribe link and verify your endpoint receives the request and the user is successfully unsubscribed in your system

## Official Documentation

For more details on Adobe Campaign Classic Message Center:

* [Event description (PushEvent API)](https://experienceleague.adobe.com/en/docs/campaign-classic/using/transactional-messaging/processing/event-description)
* [Design transactional message templates](https://experienceleague.adobe.com/en/docs/campaign-classic/using/transactional-messaging/message-templates/creating-the-message-template)
* [Transactional messaging architecture](https://experienceleague.adobe.com/en/docs/campaign-classic/using/transactional-messaging/configure-transactional-messaging/transactional-messaging-architecture)
* [ACC Technical recommendations (SMTP headers)](https://experienceleague.adobe.com/en/docs/deliverability-learn/deliverability-best-practice-guide/additional-resources/campaign/acc-technical-recommendations)


# Adobe Campaign Standard Integration
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/adobe-campaign-standard

Connect Aampe to Adobe Campaign Standard for Email and Push notifications

Estimated setup time: 30-45 minutes

<Note>
  This guide is for **Adobe Campaign Standard (ACS)**. For Adobe Campaign Classic (ACC), see [Adobe Campaign Classic Integration](/developer-guide/message-providers/message-pages/adobe-campaign-classic).
</Note>

## Connection Requirements

Aampe connects to ACS via the REST API using OAuth Server-to-Server authentication.

### Required from Customer

| Requirement | Description |
| - | - |
| Adobe Developer Console Access | Admin access to create API credentials |
| Client ID | From Adobe Developer Console |
| Client Secret | From Adobe Developer Console |
| Organization ID | Your Adobe Organization ID |
| Unsubscribe Endpoint URL | Your unsubscribe endpoint that supports One-Click List-Unsubscribe |

### Create API Credentials

1. Go to [Adobe Developer Console](https://developer.adobe.com/console/)
2. Create a new project or select an existing one
3. Click **Add API** and select **Adobe Campaign Standard API**
4. Select **OAuth Server-to-Server** authentication
5. Save your credentials:
   * Client ID
   * Client Secret
   * Organization ID

### OAuth Configuration

| Parameter | Value |
| - | - |
| Token URL | `https://ims-na1.adobelogin.com/ims/token/v3` |
| Scope | `urn:adobecloud:campaign` |

### Unsubscribe Endpoint Requirements

Your unsubscribe endpoint must:

* Accept POST requests (for One-Click List-Unsubscribe from Gmail/Yahoo)
* Accept a user identifier parameter that Aampe will populate per message
* Return HTTP 200 on successful unsubscribe

Provide Aampe with:

* **Base URL:** e.g., `https://yourcompany.com/unsubscribe`
* **Parameter name:** e.g., `uid`, `token`, or `email`

Aampe will construct the full URL per message: `https://yourcompany.com/unsubscribe?uid={user_identifier}`

## Email Channel Setup

### Step 1: Create Event Configuration

1. Click Adobe logo → **Marketing plans** → **Transactional messages** → **Event configuration**
2. Click **Create**

### Step 2: Configure Event Properties

| Field | Value |
| - | - |
| Label | `Aampe Email` |
| ID | `aampeEmail` |
| Type | Transactional event |
| Targeting dimension | Real-time event |
| Channel | Email |

### Step 3: Add Custom Fields

In the **Fields** section, add these exact field names:

| Field Name | Type |
| - | - |
| `aampeFromEmail` | Text |
| `aampeFromName` | Text |
| `aampeSubject` | Text |
| `aampeBody` | Text |
| `aampeUnsubscribeUrl` | Text |

### Step 4: Publish Event Configuration

Click **Save** then **Publish**

### Step 5: Configure Email Template

After publishing, ACS creates a transactional message template. Open it to configure:

**Sender Details:**

| Field | Value |
| - | - |
| From email | `$(ctx.aampeFromEmail)` |
| From name | `$(ctx.aampeFromName)` |

**Subject Line:**

```
$(ctx.aampeSubject)
```

**Email Content (HTML source):**

```html theme={null}
$(ctx.aampeBody)
```

<Warning>
  Do not add any additional HTML structure. Aampe provides the complete email content including all styling and layout.
</Warning>

### Step 6: Configure SMTP Headers for Unsubscribe

This step is required for email deliverability compliance (Gmail/Yahoo One-Click Unsubscribe).

In the email template properties, add SMTP headers:

```
List-Unsubscribe: <$(ctx.aampeUnsubscribeUrl)>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
```

### Step 7: Publish Template

Click **Publish** to activate the transactional message.

<Check>
  Your email template is now ready. Aampe will trigger personalized emails via the API.
</Check>

***

## Push Notification Channel Setup

### Step 1: Create Event Configuration

1. Click Adobe logo → **Marketing plans** → **Transactional messages** → **Event configuration**
2. Click **Create**

### Step 2: Configure Event Properties

| Field | Value |
| - | - |
| Label | `Aampe Push Notification` |
| ID | `aampePush` |
| Type | Transactional event |
| Targeting dimension | Real-time event |
| Channel | Mobile (Push notification) |

### Step 3: Add Custom Fields

In the **Fields** section, add these exact field names:

| Field Name | Type |
| - | - |
| `aampeTitle` | Text |
| `aampeBody` | Text |
| `aampeLink` | Text |
| `aampeImg` | Text |

### Step 4: Publish Event Configuration

Click **Save** then **Publish**

### Step 5: Configure Push Template

After publishing, ACS creates a transactional message template. Open it to configure:

**Push Content:**

| Field | Value |
| - | - |
| Title | `$(ctx.aampeTitle)` |
| Body | `$(ctx.aampeBody)` |
| Deep link | `$(ctx.aampeLink)` |
| Media URL | `$(ctx.aampeImg)` |

### Step 6: Publish Template

Click **Publish** to activate the transactional message.

<Check>
  Your push notification template is now ready.
</Check>

***

## Field Reference

### Email Payload Fields

Aampe sends these fields in the event context:

| Field | Type | Description |
| - | - | - |
| `aampeFromEmail` | String | Sender email address |
| `aampeFromName` | String | Sender display name |
| `aampeSubject` | String | Email subject line |
| `aampeBody` | String | Complete HTML email content |
| `aampeUnsubscribeUrl` | String | Full unsubscribe URL with user identifier |

### Push Payload Fields

| Field | Type | Description |
| - | - | - |
| `aampeTitle` | String | Push notification title |
| `aampeBody` | String | Push notification body text |
| `aampeLink` | String | Deep link or URL to open |
| `aampeImg` | String | Rich media image URL |

***

## Validation Checklist

Before going live, verify with your Aampe representative:

* **API Connectivity** - Aampe can successfully authenticate with your ACS instance using OAuth credentials
* **Test Email** - Send a test email and verify sender name/email, content rendering, subject line, unsubscribe header presence (check raw email headers), and link tracking
* **Test Push** - Send a test push notification and verify title/body text, deep link opens the correct screen, and image loads (if using rich push)
* **Test Unsubscribe** - Click the unsubscribe link and verify your endpoint receives the request and the user is successfully unsubscribed in your system

***

## Official Documentation

For more details on Adobe Campaign Standard:

* [Transactional messaging](https://experienceleague.adobe.com/en/docs/campaign-standard/using/communication-channels/transactional-messaging/getting-started-with-transactional-msg)
* [Event configuration](https://experienceleague.adobe.com/en/docs/campaign-standard/using/communication-channels/transactional-messaging/event-configuration)
* [Transactional message templates](https://experienceleague.adobe.com/en/docs/campaign-standard/using/communication-channels/transactional-messaging/transactional-template)
* [REST API documentation](https://experienceleague.adobe.com/en/docs/campaign-standard/using/working-with-apis/about-campaign-standard-apis/about-campaign-standard-apis)


# Airship
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/airship

Estimated setup time: 15 minutes

## Requirements

* Your Airship project's App Key
* An API Access Token

Aampe will call the [Airship API](https://docs.airship.com/api/ua/#operation-api-push-post) on your behalf.

## Generating an API Token

1. Once logged in to Airship, select the project that you are integrating with Aampe.
2. Select **Settings** from the navigation bar at the top of the screen.

   <img alt="Settings Bar Pn" />
3. Scroll down to **Project configuration** until you find the **Tokens** section.

   <img alt="Tokens Section Pn" />
4. Click on the **Manage** button.
5. In the Tokens screen that opens, click on **Create token** at the top right corner.

   <img alt="Create Token Pn" />
6. Choose a name for this token. For example: `aampe-push-token`
7. Select **All Access** under Role.

   <img alt="All Access Pn" />
8. Click on **Create token**.
9. Copy both the App Key and Access Token.

   <img alt="Copy Token Pn" />

## Configure Your Airship Push Integration on Aampe

1. Go to [https://compose.aampe.com](https://compose.aampe.com) and login using your Aampe credentials
2. Navigate to **Configure > Push Provider**
3. Toggle the Airship integration
4. Fill in the App Key and Access Token where indicated
5. Press **Activate**

Congrats! Aampe is now all set up to send push notifications via Airship!

***


# Apple Push Notification service (APNs)
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/apns

Estimated setup time: 1 hour

## Requirements

* An encryption key (.p8 file) and its key ID
* Your team ID and bundle ID/APNs topic
* APNs user device tokens

## Setup

Aampe will essentially establish a [token-based connection to APNs](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_token-based_connection_to_apns) and use that to trigger notifications on your behalf.

## Generating Key

1. Login to your Apple developer account.
2. In [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources), click **Keys** in the sidebar, then click the add button (+) on the top left.
3. Under **Key Name**, enter a unique name for the key.
4. Select the checkbox next to the services you want to enable, then click **Continue**.
   * If the Media Services checkbox is disabled, you need to register a media identifier first.
   * If you register more than one media identifier, click **Configure** next to the checkbox.
   * On the next page, choose the media identifier you want to use from the pop-up menu, then click **Continue**.
5. Review the key configuration, then click **Confirm**.
6. Click **Download** to generate and download the key. This is the key you will share with Aampe.
7. Click **Done**.

## APNs User Device Tokens

For Aampe to be able to trigger push notifications for your users, it needs to have a device token for each user. You can share those directly using a daily dump to an S3/GCP bucket.

If you are already sharing user properties data with Aampe, the APNs device token for each user can simply be added as a column to the shared attribute table. See [Properties](https://aampe-docs.readme.io/docs/data-models#user-properties).

If you are not sharing attribute data with Aampe then the easiest way to share APNs device tokens is by setting up a daily job that dumps a file with the tokens to a storage bucket. Aampe will take care of ingesting those tokens and always taking the latest value for each user in case of token updates.

### Data Format

| Name | Data Type | Description |
| :- | :- | :- |
| contact\_id | String | A unique user identifier |
| notification\_token | String | APNs device token |

***


# AWS SNS Integration
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/aws-sns

Estimated setup time: 1 hour

## Requirements

* A pair of Access Key ID and Secret Access Key with SNS Publish credentials
* The message format that you use

Aampe will call the [AWS SNS Publish API](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) on your behalf.

Configuring SNS for Aampe includes two steps:

* Create an SNS Publish Policy
* Create an IAM User for Aampe

## Create an SNS Publish Policy

1. In your AWS console, go to the **Identity and Access Management (IAM)** service.
2. Select **Policies** in the navigation menu.
3. Click on **Create Policy**
4. Click on **Choose a service**

   <img alt="Create Policy Pn" title="Create Policy Pn" />
5. Select **SNS**
6. In the **Actions** field, type **Publish** then select the Publish action that appears

   <img alt="Publish Policy Pn" title="Publish Policy Pn" />
7. Click on **Resources**, keep the **Specific** radio button selected and tick the **Any in this account** checkbox
8. Click **Next: Tags** and then **Next: Review**
9. Choose a name for your policy, such as `SNSPublish`
10. Click on **Create Policy**

## Create an IAM User for Aampe

1. In your AWS console, go to the **Identity and Access Management (IAM)** service.
2. Select **Users** in the navigation menu.
3. Click on **Add users**
4. Choose a username, such as `aampe-sns`
5. Tick the **Access key - Programmatic access** checkbox

   <img alt="Programmatic Access Pn" title="Programmatic Access Pn" />
6. Click on **Next: Permissions**
7. Click on the **Attach existing policies directly** button

   <img alt="Attach Existing Policy Pn" title="Attach Existing Policy Pn" />
8. In the **Search** text field, type the name of the policy you created in the previous step and select it when it appears in the list under Policy name.

   <img alt="Attach Existing Policy With Name Pn" title="Attach Existing Policy With Name Pn" />
9. Click on **Next: Tags** and **Next: Review**
10. Review your choices and click on **Create user**
11. You will then be led to a success screen, from which you can copy your **Access key ID** and **Secret access key**

    <img alt="Copy Key Pn" />


# Braze
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/braze

Estimated setup time: 30 minutes

## Requirements

* An API Key for your app group.
* Braze App Id
* The Braze [dashboard URL](https://www.braze.com/docs/api/basics/#api-definitions) that you use (dashboard-01 to 08 or [dashboard-01.braze.eu](http://dashboard-01.braze.eu))

**Note:** App Id setup is required only for email channel.

Aampe will call the [Braze API for sending messages](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_messages/) on your behalf.

## Create an API Key

1. From the Braze dashboard go to **Settings > API Keys**
2. On this page you will find the **Rest API Keys** table
3. Click on **+ Create New API Key**

   <img title="Rest Api Pn" alt="Rest Api Pn" />

   <img title="Rest Api Pn" alt="Rest Api Pn" />
4. Choose a name for your new key, such as `aampe-personalization`. You'll see a list of checkboxes.\
   \
   📘 **Note 2:** If required, contact your Aampe customer success manager or onboarding representative for the IP access range to enable IP whitelisting on your API allow list.

   <img title="Checkboxes Pn" alt="Checkboxes Pn" />

   <img title="Checkboxes Pn" alt="Checkboxes Pn" />
5. Tick the checkboxes to add following permissions:

| Braze Permission | Braze REST API endpoint | |
| :- | :- | - |
| users.export.ids | [<u>GET /users/export/ids</u>](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_identifier/#prerequisites) | For exporting current users |
| users.export.segment | [<u>GET /users/export/segment</u>](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_segment/#prerequisites) | For exporting current user attributes |
| users.export.global\_control\_group | [<u>POST/users/export/global\_control\_group</u>](https://www.braze.com/docs/api/endpoints/export/user_data/post_users_global_control_group) | For exporting global control group membership |
| sends.id.create | [<u>POST /sends/id/create</u>](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_create_send_ids/#prerequisites) | For creating IDs for message performance tracking |
| messages.send | [<u>POST /messages/send</u>](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_messages) | Trigger an API Campaign in Braze. |
| campaigns.trigger.send | [<u>POST /campaigns/trigger/send</u>](https://www.braze.com/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns) | Trigger a send for a campaign that is configured for API-triggered delivery. |
| campaigns.trigger.schedule.create | [<u>POST /campaigns/trigger/schedule/create</u>](https://www.braze.com/docs/api/endpoints/messaging/schedule_messages/post_schedule_triggered_campaigns/#prerequisites) | Trigger a send for a campaign that is configured for scheduled API-triggered delivery. |
| campaigns.list | [<u>GET /campaigns/list</u>](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaigns) | Retrieve the list of all the campaigns configured in Braze and their associated metadata. |
| campaigns.data\_series | [<u>GET /campaigns/data\_series</u>](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaign_analytics) | Retrieve the analytics data of a specific Braze campaign. |
| campaigns.details | [<u>GET /campaigns/details</u>](https://www.braze.com/docs/api/endpoints/export/campaigns/get_campaign_details) | Retrieve the details of a specific Braze campaign. |
| segments.list | [<u>GET /segments/list</u>](https://www.braze.com/docs/api/endpoints/export/segments/get_segment) | Retrieve the list of all the segments configured in Braze and their associated metadata. |
| segments.data\_series | [<u>GET /segments/data\_series</u>](https://www.braze.com/docs/api/endpoints/export/segments/get_segment_analytics) | Retrieve the size of the Braze segment. |
| segments.details | [<u>GET /segments/details</u>](https://www.braze.com/docs/api/endpoints/export/segments/get_segment_details) | Retrieve the details of a specific Braze segment. |
| email.unsubscribe | | For retrieving email unsubscribe information |
| email.hard\_bounces | [<u>GET /email/hard\_bounce</u>](https://www.braze.com/docs/api/endpoints/email/get_list_hard_bounces#query-or-list-hard-bounced-emails) | To retrieve email bounce information |
| [templates.info](http://templates.info) | [<u>GET /templates/email/info</u>](https://www.braze.com/docs/api/endpoints/templates/email_templates/get_see_email_template_information) | Retrieve the details of a specific Braze HTML email template. |
| templates.list | [<u>GET /templates/email/list</u>](https://www.braze.com/docs/api/endpoints/templates/email_templates/get_list_email_templates) | Retrieve the list of all the Braze HTML email templates configured in Braze and their subject line and HTML content. |
| subscription.status.get | [<u>GET /subscription/user/status</u>](https://www.braze.com/docs/api/endpoints/subscription_groups/get_list_user_subscription_groups) | To get subscription status |
| subscription.groups.get | [<u>GET/ subscription.groups.get</u>](https://www.braze.com/docs/api/endpoints/subscription_groups/get_list_user_subscription_groups/#prequisites) | To get subscription groups |

6. Finalize the key creation.
7. You can then view the newly created key by clicking on the gear icon at the right
8. Copy the API key value.
9. Login into the [Aampe](https://compose.aampe.com/auth/login) composer using your Aampe credentials.
10. Enter **System setup -> Integrations -> Braze**. Activate Braze

    <img alt="Aampe Composer Pn" title="Aampe Composer Pn" />
11. Enter the API key and dashboard URL copied from the earlier steps. Your connection is now ready to deliver messages

## App Id Setup

1. To find your app\_id go to your Braze account and navigate to **Settings > API and Identifiers > App Identifiers**
2. Copy your app\_id and navigate back to Aampe Braze integration page select the email channel and add your app\_id

   <Frame>
     <img title="Braze Api Key Creation" alt="Braze Api Key Creation" />

     <img title="Braze Api Key Creation" alt="Braze Api Key Creation" />
   </Frame>

📘 **Note:** App Id is not required if you do not intend to use the email channel through Braze.

## API Campaign Setup

Setting up an API Campaign in Braze allows you to send transactional messages by generating a campaign\_id for use in your API calls. This process involves creating the campaign in the Braze dashboard and then using the campaign\_id in your API requests to send messages. Here's a step-by-step guide to setting up an API Campaign:

### Access the Braze Dashboard:

1. Log in to your Braze account. Navigate to the **Messaging** section and select **Campaigns**.
2. **Create a New Campaign:** Click on **Create Campaign**. Choose **API Campaigns** as the campaign type.

   <img title="Api Campaigns Pn" alt="Api Campaigns Pn" />

   <img title="Api Campaigns Pn" alt="Api Campaigns Pn" />

### Configure the Campaign:

1. **Name the Campaign:** Provide a descriptive title to easily identify the campaign later.
2. **Add Message:** Click on **Select Message**. Select the message types (channels) you intend to use (e.g., Email, SMS, Push Notifications). This action will generate a campaign\_id and a message variation ID for each channel.

   <img alt="Save Api Campaign Pn" />

   <img alt="Save Api Campaign Pn" />
3. **Optional - Add Conversion Events:** If you wish to track specific user actions as conversions, you can add a conversion event to the campaign.

### In the Campaign Limits:

* **User re-eligible for messages:** Check this box and select 0 minutes as we would like Aampe agents to be re-eligible based on user's best time.
* Select **Don't Count this towards intelligent Frequency limits** as we don't want Aampe to be affected by Braze limits

### Save the Campaign:

1. After configuring the necessary settings, click on **Save Campaign**.

### **Configure in Aampe:**

1. **Campaign ID:** After saving your campaign, retrieve the campaign\_id and add to the Braze Integration Settings in Composer.
2. **Variation IDs:** If you added messages to your campaign for each channel, note down the variation\_id for each and send it to your onboarding representative at Aampe.

   <Frame>
     <img alt="Braze Variation Id" />
   </Frame>

**You are all set with Braze!**


# CleverTap
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/clevertap

Estimated setup time: 10 minutes

## Requirements

<Info>
  To perform the following steps, you need a CleverTap admin account for your project.
</Info>

## Step 1: Create a User for Aampe

1. Login to your CleverTap dashboard as an admin user
2. Go to **Settings** at the bottom left corner of the screen

   <img alt="Admin Menu Pn" title="Admin Menu Pn" />
3. Select **Users**

   <img alt="Settings Menu Pn" title="Settings Menu Pn" />
4. Click on **+Users**

   <img alt="Add Users Pn" title="Add Users Pn" />
5. Enter `developer+<your_business_name>@aampe.com` in the Email address textbox
6. Check the **Creator** role from the dropdown list and click **Apply**
7. Click on **Invite**

   <img alt="Invite User Pn" title="Invite User Pn" />

## Step 2: Generate a User-Passcode for Aampe

1. Login to your CleverTap dashboard as an admin user
2. Go to **Settings** at the bottom left corner of the screen

   <img alt="Admin Menu Pn" title="Admin Menu Pn" />
3. Select **Users**

   <img alt="Settings Menu Pn" title="Settings Menu Pn" />
4. Type `aampe` in the search box to find the user you previously created for Aampe
5. Press the 3 dot icon at the right side of the table once the Aampe user is found

   <img alt="Fine New User Pn" title="Fine New User Pn" />
6. Select **Grant Passcode**

   <img alt="Grant Passcode Pn" title="Grant Passcode Pn" />
7. Select **Forever** and click on **Grant**

   <img alt="Grant Passcode Forever Pn" title="Grant Passcode Forever Pn" />

**Note:** The granted passcode can always be revoked by pressing the 3 dot icon and selecting **Revoke Passcode**.

## Step 3: Configure Your CleverTap Push Integration on Aampe

1. Go to [https://compose.aampe.com](https://compose.aampe.com/) and login using your Aampe credentials
2. Navigate to **System setup > Integrations**
3. The **Messaging Provider** tab will open

   <img alt="Aampe Composer Provider Menu Pn" />
4. Click on **CleverTap**

   <img alt="Aampe Clevertap Page Pn" />
5. To get the account ID: Go to **Settings** (in Clevertap) and then **Project**. Copy the **Project ID**

   <img alt="Clevertap Project Id Pn" />
6. For the passcode input the user passcode you just generated for Aampe in the above steps.
7. Press **Activate**

**CleverTap - Aampe is all set up!**

***


# Custom API
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/custom-api

Aampe guidelines for all the one-of-a-kind message providers

## Custom Email Provider

Connect Aampe to your own email infrastructure when you need full control over delivery or when using an email provider not yet supported by [Aampe's native integrations](/developer-guide/message-providers/message-providers).

## Requirements

Aampe will need the following in order to deliver messages on your behalf:

* A publicly accessible HTTP endpoint that accepts POST requests
* An authentication method (API key, Bearer token, or custom header)
* The ability to process JSON payloads and return JSON responses

## API Contract

Your endpoint should implement the following contract for Aampe to successfully deliver email messages.

### Request Format

Aampe sends a `POST` request with the following headers:

```text theme={null}
POST https://your-endpoint.com/send-email
Content-Type: application/json
Authorization: <your-auth-method>
```

### Payload Structure (Minimal)

```text theme={null}
{
  "to": "recipient@example.com",
  "from": "Sender Name <sender@example.com>",
  "content": {
    "subject": "Your email subject",
    "body": "<p>HTML email content</p>"
  },
  "metadata": {
    "message_id": "uuid-string"
  }
}
```

### Field Reference

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `to` | string | Yes | Recipient email address |
| `from` | string | Yes | Sender name and email address |
| `content.subject` | string | Yes | Email subject line |
| `content.body` | string | Yes | Email body in HTML format |
| `metadata` | object | No | Additional data for tracking or debugging |
| `metadata.message_id` | string | No | Unique identifier for the message |

> **Note:** The `body` field contains HTML content. Plain text fallback support is optional on your end.

### Response Format

Your endpoint should return JSON responses with appropriate HTTP status codes.

**Success (200 OK):**

```text theme={null}
{
  "status": "accepted",
  "provider_message_id": "your-internal-id"
}
```

**Error (4xx/5xx):**

```text theme={null}
{
  "status": "error",
  "message": "Description of what went wrong"
}
```

## Example Implementation

Here's a sample cURL request showing a common payload format:

```text theme={null}
curl -X POST https://api.your-provider.com/send-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "john.doe@example.com",
    "from": "Acme Support <support@acme.com>",
    "content": {
      "subject": "Order Confirmation",
      "body": "<p>Hi John,<br/>Your order has been confirmed.</p>"
    },
    "metadata": {
      "message_id": "b3b1c2e4-8f12-4c9a-9a0d-acde12345678"
    }
  }'
```

## Troubleshooting

**Connection test fails**

* Verify your endpoint is publicly accessible (not behind a firewall or VPN)
* Check that your authentication credentials are correct
* Ensure your endpoint returns valid JSON responses

**Messages not delivering**

* Confirm your endpoint returns a `200 OK` status for successful requests
* Check your endpoint logs for incoming requests from Aampe
* Verify the `provider_message_id` is being returned in successful responses

**Need help?** Contact your Aampe representative or email [support@aampe.com](mailto:support@aampe.com) for assistance with your custom integration.


# Customer.io
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/customerio

Estimated setup time: 15 minutes

## Requirements

* API Key created for Aampe
* Your Region of setup for [Customer.io](http://Customer.io)

## Steps

Aampe will call the [Customer.io](http://Customer.io)[ API](https://customer.io/docs/api/app/#operation/sendPush) on your behalf.

### Create API Key for Aampe

1. Once logged in to [Customer.io](http://Customer.io) account, navigate to **Settings Icon > Account Settings**

   <img alt="Account Settings Pn" />
2. Select **API Credentials** from the menu bar.

   <img alt="2 Api Credentials Pn" />
3. Click on the 2nd tab i.e **Add API keys > Create App API Key**

   <img alt="3 Api Keys Pn" />
4. Give it the name you like (e.g `aampe_push_access`) and select your prod workspace and then hit **Create App API Key**

   <img alt="4 Create Api Key Pn" />
5. Copy the API Key shown on the prompt - you won't be able to access it again.

### Configure Your [Customer.io](http://Customer.io) Push Integration on Aampe

1. Go to [https://compose.aampe.com](https://compose.aampe.com) and login using your Aampe credentials
2. Navigate to **System setup > Integrations**
3. The **Messaging Provider** tab will open

   <img alt="5 Integration Menu Pn" />
4. Click on [**Customer.io**](http://Customer.io)
5. Input the API Key, Region in the respective textboxes

   * If you want to check your region you can go to **Settings -> Privacy and Data Settings** and check the **Data Center Region**

   <img alt="6 Aampe Customerio Page Pn" />
6. Click on **Connect**

### Step 2: Create Campaign for Aampe

1. Go to **Transactional** in the navigation bar

   <img alt="7 Campaign Pn" />
2. On Transactional, select **Create a Message**
3. Feed in the title and description for Aampe message and click on **Add Content**

   <img alt="8 Create Message Pn" />
4. Select **Push** or **Email** as appropriate. No need to add content -> Click on **Save & Continue**

   <img alt="9 Add Content Pn" />
5. Keep the default settings and launch the message
6. On the Transactional messages dashboard you will get an ID for the new message you created. Send the ID to Aampe.

   <img alt="10 Campaign Id Pn" />

Congrats! You're all set with integrating Aampe and Customer.io.

***


# Emarsys Integration
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/emarsys

Estimated setup time: 30 minutes

## Requirements

* An API user name and secret
* A dedicated push campaign with personalization tokens and an external event

Aampe will first guide you through the creation of a dedicated transaction externally triggered push campaign. It will then message your users by calling the Emarsys [External Event trigger API](https://dev.emarsys.com/docs/emarsys-api/61b720d3c0be6-trigger-an-external-event) on your behalf.

## Set Up API Permissions

### Create an API User and Secret

<Info>
  The following steps need to be performed by an Emarsys account owner.
</Info>

1. Login to the Emarsys application
2. Go to **Admin > Security Settings**
3. Press on **Create API user**

   <img alt="1 Admin Pn" title="1 Admin Pn" />
4. Copy the resulting User name and Secret (note that the secret will no longer be available for copying once you leave this screen)

   <img alt="2 Api Key Pn" title="2 Api Key Pn" />

### Set Up API Permissions for the Newly Created User

1. Go to **Management > Security Settings > API Users**
2. Click on the edit button (in the form of a pencil)
3. You will reach a menu with toggles with all the possible Emarsys API permissions

   <img alt="3 Api Permissions Pn" title="3 Api Permissions Pn" />
4. Find and toggle the `externalevent.trigger` permission
5. Click on **Edit** at the bottom of the page to apply the permission modifications

## Create a Dedicated Campaign for Aampe

A 4-step procedure to create a transaction push campaign that Aampe can use to personalize your notifications.

### Step 1: Create Personalization Tokens

1. Go to **Content > Personalization**
2. Click on **Create Token**
3. Select **External Data** in the Choose Personalization Capability window

   <img alt="4 Campaign Selection Pn" title="4 Campaign Selection Pn" />
4. Enter "Aampe Title" under Name and "Aampe" under Category. Create "Aampe" category by clicking **Create Category**

   <img alt="5 Category Pn" title="5 Category Pn" />
5. Click on **New** in the JSON object section
6. Enter "aampe" under Name
7. Copy/paste the following JSON snippet into the code editor:

   ```json theme={null}
   {
       "aampe": {
           "title": "Push notification title",
           "body": "Push notification body"
       }
   }
   ```
8. Press on **Modify**
9. Select `event.aampe.title` in the Field section
10. Click **Save**
11. Click on **Create Token** again selecting **External Data** in the Choose Personalization Capability window
12. This time, enter "Aampe Body" under Name and "Aampe" Category for this token.
13. Select the "aampe" JSON object that you just created
14. Select `event.aampe.body` in the Field section
15. Click **Save**

### Step 2: Create Push Campaign

1. Go to **Channels > Mobile Engage**
2. Select the **Push Messages** tab
3. Click **Create Push campaign**
4. In the campaign wizard, enter "Aampe" in Message name, select your mobile app and set Recipient Source to "Automation Center"

   <img alt="6 Push Campaign Pn" />
5. Drag the Aampe Title and Aampe Body personalization tokens respectively to the title and body sections of the notification in the preview pane.
6. Click **Ready to Launch**

### Step 3: Set Up an External Event

1. Go to **Management > External Events**
2. Click on **Create External Event**
3. Enter "Aampe push trigger" under External event name
4. Click on **Create**
5. Copy the external event ID number, it will be needed later when setting up the integration in the Aampe composer

### Step 4: Create an Interactions Program

1. Go to **Automation > Automation**
2. Click on **Create Program**
3. Select **Behavior-focused journeys (Interactions)**
4. Select **External event** as the trigger

   <img alt="7 Trigger Pn" title="7 Trigger Pn" />
5. Double click on the External event node
6. Select the external event created in Step 3
7. Click **OK**
8. Click on the **Decision** node to add it to the program
9. Double click on the new Decision node that you just added
10. Add the segment with all of your users
11. Click **OK**
12. Click on the **Mobile Engagement push message** channel to add it to the program
13. Double click on the Mobile Engagement push message node
14. Select the "Aampe" push campaign that you created in Step 2 using the dropdown menu
15. Click **OK**
16. Click **Activate**

## Set Up the Integration in the Aampe Composer

1. Go to [https://compose.aampe.com](https://compose.aampe.com) and login using your Aampe credentials
2. Navigate to **Configure > Push Provider**
3. Open the Emarsys integration
4. Input your API User name, Secret, and External Event ID you generated during this setup tutorial

Congrats! You have successfully integrated Aampe and Emarsys.


# Firebase Cloud Messaging
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/firebase-cloud

Estimated setup time: 1 hour

## Requirements

* Your Firebase project ID
* Service account JSON credentials

Aampe will essentially call the Firebase [Cloud Messaging API](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send) on your behalf.

Setting up Firebase Cloud Messages involves four steps:

1. Enable the Cloud Messaging API
2. Create a custom role for message creation
3. Create a service account
4. Generate a key

<Info>
  All the next steps assume that you start from your Google Cloud Platform console with your Firebase project selected.
</Info>

## Enable the Cloud Messaging API

1. Type "Firebase Cloud Messaging API" in the Search products and resources textbox.
2. Choose **Firebase Cloud Messaging API** from the list.

   <img alt="1 Cloud Message Api Pn" />
3. Click on the blue **Enable** button.

   <img alt="2 Enable Pn" />

## Create a Custom Role for Message Creation

A custom Role must be created in the system to allow Aampe to trigger notifications using the API because the default roles do not provide granular enough permissions.

1. Type "Roles" in the Search products and resources textbox and select the **Roles (IAM and Admin)** option. This will take you to the Roles page.

   <img alt="3 Iam Pn" />
2. Click on **+ CREATE ROLE**
3. Fill in the role Title, Description and ID according to your conventions.

   <img alt="4 Create Role Pn" />
4. Click on **+ADD PERMISSIONS**
5. In the window that opens, search for `cloudmessaging.messages.create` using the textbox to the right of the Filter and select the cloudmessaging.messages.create entry that appears.

   <img alt="5 Add Permissions Pn" />
6. Tick the `cloudmessaging.messages.create` permission and click on **ADD**

   <img alt="6 Add Permissions Create Pn" />
7. Once added, click on **CREATE** to complete the role creation.

   <img alt="7 Save Permissions Pn" />

## Create a Service Account

1. Type "Service accounts" in the Search products and resources textbox.
2. Choose **Service accounts (IAM and admin)** from the list. This will take you to the service account page.

   <img alt="8 Service Account Pn" />
3. Click on **+ CREATE SERVICE ACCOUNT**

   <img alt="9 Service Account Form Pn" />
4. Fill in the Service account name, ID and description according to your conventions.

   <img alt="10 Service Account Filled Out Pn" />
5. Click on **CREATE AND CONTINUE**
6. On the Grant this service account access to the project screen, click on the **Select a role** dropdown.
7. Under **Quick access > Custom**, select the custom role you created in the previous step.

   <img alt="11 Select Custom Pn" />
8. Click on **+ ADD ANOTHER ROLE** and then on the **Select a role** dropdown.
9. Type "Firebase Cloud Messaging Admin" in the box near the Filter.
10. Select the suggested **Firebase Cloud Messaging Admin** role.

    <img alt="12 Messaging Admin Role Pn" />
11. Click on **DONE** to complete the service account creation.

    <img alt="13 Done Pn" />

## Generate a Key

<Info>
  This step assumes that you created a service account and assigned the "Firebase Cloud Messaging Admin" and custom message creation roles to it.
</Info>

1. In your "Service accounts" page, find the service account you created for Aampe and click on the three dots in the Actions column and select **Manage keys**

   <img alt="14 Generate Key Pn" />
2. Click on **ADD KEY** and select **Create new key**

   <img alt="15 Copy Key Pn" />
3. Select the **JSON** Key type and click on **CREATE**

   <img alt="16 Json Key Pn" />
4. Your browser will download a `.json` file with the key needed by Aampe.

Congrats! Keep your json key secure and let your Aampe technical counterparts know it is ready. They will take it from here.

***


# Iterable
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/iterable

Estimated setup time: 10 minutes

## Requirements

* An API Key

Aampe will message your users by calling Iterable's [Push target API](https://api.iterable.com/api/docs#push_target) on your behalf.

## Create an API Key

1. Sign in to your Iterable project as an org admin (or as a member that has the Third-Party Integrations, API Keys and Webhooks permission).
2. Go to **Integrations > API Keys**.
3. Click **New API Key**.
4. In the Create API Key window, enter a name for the key. Prefixing your key name with "Aampe" will be helpful for identifying it in the future.
5. Select **Server-side** as the key type.
6. Click **Create**.
7. Copy your new API Key.

## Save API Key in Aampe

1. Log into Aampe. Go to the **Integrations** page. Find the **Messaging provider** tab and click on **Iterable**.

   <img alt="Aampe Iterable Pn" />

***


# Leanplum
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/leanplum

Estimated setup time: 15 minutes

## Requirements

* Your App ID
* Your Production API Key
* (Optional) Your Data Export API Key

Aampe will call the [Leanplum API](https://docs.leanplum.com/reference/post_api-action-sendmessage) on your behalf.

## Get Your App ID and API Keys

1. Once logged in to Leanplum, navigate to **Development > App Settings**

   <img alt="1 Admin Menu Pn" />
2. Select **API Keys** from the left navigation bar.
3. Copy the App ID, Production and Data Export keys.

   <img alt="2 Apikey Pn" />

## Configure Your Leanplum Push Integration on Aampe

1. Go to [https://compose.aampe.com](https://compose.aampe.com) and login using your Aampe credentials
2. Navigate to **System setup > Integrations**
3. The **Messaging Provider** tab will open

   <img alt="3 Aampe Menu Pn" />
4. Toggle the **Activate** knob on the Leanplum row
5. Input the App ID, Production and Data Export keys into their respective textboxes

   <img alt="4 Leanplum Aampe Pn" />
6. Click on **Connect**

🎉 **You're all set!**

***


# MailChimp
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/mailchimp

Estimated setup time: 15 minutes

## Prerequisites

* Active Mailchimp account with Standard or Premium plan
* Mandrill (Transactional Email) add-on enabled
* Verified sending domain

## Required Credentials

* API Key

## How to Get Your API Key:

1. Log in to your Mailchimp account
2. Navigate to **Account & Billing → Extras → Transactional Email**
3. Click **Launch App** to access Mandrill
4. Go to **Settings → SMTP & API Info**
5. Click **+ New API Key**
6. Provide a description and copy the generated key

***


# Mandrill
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/mandrill

Estimated setup time: 15 minutes

## Prerequisites

* Active Mailchimp account with Standard or Premium plan
* Mandrill (Transactional Email) add-on enabled
* Verified sending domain

## Required Credentials

* API Key

## How to Get Your API Key:

1. Log in to your Mailchimp account
2. Navigate to **Account & Billing → Extras → Transactional Email**
3. Click **Launch App** to access Mandrill
4. Go to **Settings → SMTP & API Info**
5. Click **+ New API Key**
6. Provide a description and copy the generated key


# MoEngage
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/moengage

Estimated setup time: 15 minutes

## Requirements

* Your API ID and API SECRET
* What you use as `targetUserAttributes`
* \[Optional] The way you've implemented notification actions (deeplinking, navigation, etc.)

Aampe will essentially call the [MoEngage Push API](https://docs.moengage.com/docs/push-api-v2) on your behalf.


# Netcore
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/netcore

Estimated setup time: 10 minutes

## Requirements

* API Key

## Steps

1. Login to the CEE panel
2. Go to **Assess > API Triggers**
3. Copy the API key


# OneSignal
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/onesignal

Estimated setup time: 15 minutes

## Requirements

* Your OneSignal App ID
* Your Rest API Key

Aampe will call the [OneSignal API](https://documentation.onesignal.com/reference/rest-api-overview) on your behalf.

## Getting Your App ID and API Key

1. Once logged in to OneSignal, select the application you want to integrate with Aampe

   <img alt="1 Adminmenu Pn" />
2. Select **Settings** from the navigation bar at the top of the screen.

   <img alt="2 Settings Pn" />
3. Select **Keys & IDs** from the sub-navigation bar that opens.
4. Copy the **OneSignal App ID** and **Rest API Key**.

### Copy Your Keys Into Aampe

1. Navigate to **System Settings > Integrations** on Aampe and select OneSignal

   <img alt="3 Aampe Integration Menu Pn" />
2. Add your credentials to the respective fields

   <img alt="4 Aampe Onesignal Pn" />


# Sendgrid (Twilio)
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/sendgrid

Estimated setup time: 15 minutes

## Creating an API Key

1. Navigate to **Settings** on the left navigation bar, and then select **API Keys**.
2. Click **Create API Key**.
3. Give your API key a name. For example: Aampe.
4. Select **Full Access**. For more information, see SendGrid API key permissions.
5. Click **Create & View**.
6. Copy your API key.


# Salesforce Marketing Cloud (SFMC)
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/sfmc

Estimated setup time: 30 minutes

## Requirements

**All channels**

* `client_id`
* `client_secret`
* Instance subdomain (e.g. `mc563885gzs27c5t9-63k636ttgm`)

**Email channel (additional)**

* `definition_key` — created during email setup below

Aampe calls the [SFMC](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/integration-s2s-client-credentials.html) server-to-server REST API on your behalf using OAuth 2.0 client credentials. Tokens are fetched and cached automatically — you only need to supply the client ID and secret.

<Note>
  The access token SFMC issues expires after 20 minutes. Aampe handles token refresh automatically — do not share access tokens directly.
</Note>

***

## Step 1 — Create an Installed Package

1. Log in to SFMC and open **Setup** (gear icon, top right).
2. Under **Platform Tools**, expand **Apps** and select **Installed Packages**.
3. Click **New** and name the package `aampe-integration`.
4. Under **Components**, click **Add Component** and select **API Integration**.
5. Select **Server-to-Server** as the integration type.
6. Grant the following permissions:

| Scope | Permission | Required for |
| - | - | - |
| Email | Read, Write, Send | Email sends |
| Push | Read, Write, Send | Push sends |
| Channels | Read, Write | Channel access |
| Automations | Read, Write, Execute | Tracking Extract jobs (email only) |

7. Click **Save**.
8. Copy the **Client ID**, **Client Secret**, and **REST Base URI** from the package summary page. These are the credentials you will enter in Aampe.

Your REST Base URI will be in the format `https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com` — only the subdomain portion is required.

***

## Step 2 — Push channel setup

No additional SFMC configuration is required beyond the Installed Package above. Enter the following into your Aampe integration settings:

* `client_id`
* `client_secret`
* `subdomain`
* `message_id` — the SFMC push message ID Aampe should send against

***

## Step 3 — Email channel setup

Email requires three one-time setup steps in SFMC.

### 3a — Create the shell template in Content Builder

Aampe generates the full HTML email body per user and passes it at send time. The Content Builder template acts as a thin delivery wrapper — Aampe owns all content and styling.

1. In SFMC, go to **Content Builder** and click **Create** > **Email** > **HTML Paste**.
2. Name it `aampe-email-shell`.
3. Set the subject line to:
   ```
   %%=AttributeValue("subject")=%%
   ```
4. Set the body to:
   ```html theme={null}
   <!DOCTYPE html>
   <html>
   <head></head>
   <body>
   %%=TreatAsContent(AttributeValue("msg_body"))=%%
   <!-- Add your standard unsubscribe footer here -->
   </body>
   </html>
   ```
5. Replace the comment with your organisation's unsubscribe footer. The built-in SFMC profile centre link can be used:
   ```
   <a href="%%profile_center_url%%" alias="Unsubscribe">Unsubscribe</a>
   ```
6. Save the template.

<Note>
  `TreatAsContent()` evaluates the passed HTML as live content. Aampe automatically escapes `%%` sequences in message bodies to prevent unintended AMPscript evaluation.
</Note>

### 3b — Create a send definition

1. Create a send definition referencing the shell template from step 3a. See [createSendDefinition](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_transactional_messaging_email/createSendDefinition.html).
2. Ensure `options.tracking` has `opens` and `clicks` set to `true` — these are required for Aampe's reward signal.
3. Copy the **Definition Key** and enter it into your Aampe integration settings.

<Note>
  One send definition is sufficient for all Aampe email sends — you do not need one per campaign or segment.
</Note>

### 3c — Configure Tracking Extracts for event data

Aampe reads delivery events (sent, opens, clicks, bounces, unsubscribes) via daily Automation Studio Tracking Extracts.

1. In **Automation Studio**, create a new Automation.
2. Add a **Tracking Extract** activity for each event type: Sent, Opens, Clicks, Bounces, Unsubscribes.
3. Set the output destination to S3 or SFTP.
4. Schedule the automation to run daily.

The `messageKey` field in the extract output is the join key between SFMC tracking rows and Aampe send records — ensure it is included in the extract schema. See [Tracking Extract reference](https://help.salesforce.com/s/articleView?id=sf.mc_as_tracking_extract.htm\&type=5).

***

**You are all set with SFMC!**


# Twilio
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/twilio

Estimated setup time: 15 minutes

## Requirements

* Twilio Account SID
* Twilio Auth Token

## Get Your Twilio Account SID & Auth Token

1. Navigate to [https://www.twilio.com/console/projects/summary](https://www.twilio.com/console/projects/summary)
2. Click the account your app is connected to.

   <img alt="1 App Menu Pn" />
3. On the account page scroll down to **Account Info** section to get your account SID and Authentication Token

   <img alt="2 Account Pn" title="2 Account Pn" />

## Add Twilio Account SID & Auth Token to Aampe

1. Log into the Aampe Composer. Navigate to **Integrations** and find the **Message provider** menu. Click on **Twilio**.

<img alt="3 Aampe Menu Pn" />

2. Insert the Twilio keys into the relevant fields.

   <img alt="4 Aampe Twilio Pn" />

Congrats on setting up Twilio for message delivery with Aampe.


# WebEngage
Source: https://kb.aampe.com/developer-guide/message-providers/message-pages/webengage

Estimated setup time: 15 minutes

## Requirements

* Your WebEngage License Code
* Your REST API Key
* Your Dashboard URL ([dashboard.webengage.com](http://dashboard.webengage.com) or [dashboard.in.webengage.com](http://dashboard.in.webengage.com))

Aampe will call the [WebEngage Transaction Campaign API](https://docs.webengage.com/docs/sending-transactional-campaigns) on your behalf.

## Getting Your License Code and API Key

<Info>
  For the following steps, please use an admin account that has the Account Management and Update Data permissions.
</Info>

1. On the WebEngage dashboard click on **Data Platform > Integrations** on the side nav. Open the **Rest API** menu.

   <img alt="1 Main Menu Pn" />
2. Copy your **LICENSE CODE** & **API KEY**

   <img alt="2 Apikey Pn" />

## Add Keys to Aampe

1. Select **WebEngage** in **System Settings > Integrations**

   <img alt="3 Aampe Menu Pn" />
2. Add your credentials to the respective fields.

   <img alt="4 Aampe Webengage Pn" />


# Message Delivery Partners
Source: https://kb.aampe.com/developer-guide/message-providers/message-providers

Aampe supports the following message delivery partners for each of the following channels

## Channel Support Matrix

| Partner | Push | SMS | Email | Notes |
| :- | :- | :- | :- | :- |
| [**<u>Adobe Campaign Standard</u>**](/developer-guide/message-providers/message-pages/adobe-campaign-standard) | ✓ | ✓ | ✓ | Full marketing automation platform with all channels |
| [**<u>Adobe Campaign Classic</u>**](/developer-guide/message-providers/message-pages/adobe-campaign-classic) | ✓ | ✓ | ✓ | Full marketing automation platform with all channels |
| [**Airship**](/developer-guide/message-providers/message-pages/airship) | ✓ | ✓ | ✓ | Full omnichannel platform with push, SMS, and email capabilities |
| [**Apple Push Notification service**](/developer-guide/message-providers/message-pages/apns) | ✓ | - | - | Apple Push Notification service - iOS push notifications only |
| [**AWS SNS**](/developer-guide/message-providers/message-pages/aws-sns) | ✓ | ✓ | ✓ | Amazon Simple Notification Service supports all three channels |
| [**Braze**](/developer-guide/message-providers/message-pages/braze) | ✓ | ✓ | ✓ | Customer engagement platform with push, SMS, email, and in-app |
| [**Clevertap**](/developer-guide/message-providers/message-pages/clevertap) | ✓ | ✓ | ✓ | Full-stack engagement platform supporting all channels |
| [**Customer.io**](/developer-guide/message-providers/message-pages/customerio) | ✓ | ✓ | ✓ | Multi-channel automation supporting push, SMS, email, and in-app |
| [**Emarsys**](/developer-guide/message-providers/message-pages/emarsys) | ✓ | ✓ | ✓ | Omnichannel customer engagement platform |
| [**Firebase Cloud Messaging**](/developer-guide/message-providers/message-pages/firebase-cloud) | ✓ | - | - | Google's push notification service for Android, iOS, and web |
| [**Iterable**](/developer-guide/message-providers/message-pages/iterable) | ✓ | ✓ | ✓ | Cross-channel platform with push, SMS, email, and web push |
| [**Leanplum**](/developer-guide/message-providers/message-pages/leanplum) | ✓ | ✓ | ✓ | Mobile engagement platform with multi-channel messaging |
| [**Mailchimp**](/developer-guide/message-providers/message-pages/mailchimp) | - | ✓ | ✓ | Primarily email marketing with SMS capabilities |
| [**MoEngage**](/developer-guide/message-providers/message-pages/moengage) | ✓ | ✓ | ✓ | Customer engagement platform with all channels |
| [**NetCore**](/developer-guide/message-providers/message-pages/netcore) | ✓ | ✓ | ✓ | Full-stack martech platform |
| [**OneSignal**](/developer-guide/message-providers/message-pages/onesignal) | ✓ | ✓ | ✓ | Push notification service expanded to SMS and email |
| [**Salesforce Marketing Cloud (SFMC)**](/developer-guide/message-providers/message-pages/sfmc) | ✓ | ✓ | ✓ | Enterprise platform with Mobile Studio, Email Studio, and SMS |
| [**Twilio**](/developer-guide/message-providers/message-pages/twilio) | - | ✓ | ✓\*\* | SMS primary focus, email via SendGrid acquisition |
| [**WebEngage**](/developer-guide/message-providers/message-pages/webengage) | ✓ | ✓ | ✓ | Full-stack retention platform |
| [**Custom API**](/developer-guide/message-providers/message-pages/custom-api) | \* | \* | \* | Depends on implementation - can support any/all channels |

### Legend

* **✓** : Service is provided
* **-** : Service is not provided
* **\*** : Varies based on implementation
* **\*\*** : Email through SendGrid (Twilio-owned)


# Setting up Single Sign-On (SSO)
Source: https://kb.aampe.com/developer-guide/sso/setting-up-sso



Aampe supports the following providers for both authentication (SAML) and user provisioning (SCIM):

* [Google](/developer-guide/sso/sso_google)
* [JumpCloud](/developer-guide/sso/sso_jumpcloud)
* [Microsoft Entra ID (formerly Azure AD)](/developer-guide/sso/sso_microsoft_entra_id)
* [Okta](/developer-guide/sso/sso_okta)
* [OneLogin](/developer-guide/sso/sso_onelogin)

Additional authentication-only options include:

* [Auth0](/developer-guide/sso/sso_auth0)
* [OpenID Connect Provider](/developer-guide/sso/sso_openid_connect)
* [PingOne](/developer-guide/sso/sso_pingone)
* [Rippling](/developer-guide/sso/sso_rippling)

For additional support in setting up or configuring SSO, please contact Aampe Customer Support.


# Auth0 SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_auth0

Here we will show you how to set up your own custom SAML application for Auth0 SAML

## Create application

1. From your Auth0 dashboard, click **Applications** from the left navigation menu.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)

   <img alt="Sso Auth0 1 Pn" />
3. If you haven't created a SAML application, click the **Create Application** button to create a new application.
4. Give your application a **Name** and click **Create**.

   <img alt="Sso Auth0 2 Pn" />

## Configure application

1. Click the tab **Addons** and enable **SAML2 WEB APP** add-on.

   <img alt="Sso Auth0 3 Pn" />
2. Enter your **Application Callback URL** on the next screen and click **Enable**.

   Replace the values with the ones you have received from Aampe.

   <img alt="Sso Auth0 4 Pn" />
3. Click the tab **Usage** and download the **Identity Provider Metadata**.

   <img alt="Sso Auth0 5 Pn" />

## Attribute mapping

No additional attribute mapping is required for Auth0 SAML to work with Aampe.

## Next steps

You've successfully configured your custom SAML application for Auth0 SAML. At this stage, you can assign users to your application and start using it.


# Google SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_google

In this section, we will show you how to set up your own custom SAML application for Google SAML

## Create application

1. From your Google Admin console, click **Apps** from the sidebar then click **Web and mobile apps** from the list.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
3. If you haven't created a SAML application, click **Add custom SAML app** from the menu.

   <img alt="Sso Google 1 Pn" />
4. Give your application an **App name** and click **Continue**.

   <img alt="Sso Google 2 Pn" />

## Configure application

1. From the next screen, click **DOWNLOAD METADATA** to download the metadata XML file, then click **Continue**.

   <img alt="Sso Google 3 Pn" />
2. Enter the following values in the **Service provider details** section:

   * **ACS URL**
   * **Entity ID**

   Replace the values with the ones you have received from Aampe and click **Continue** to save the configuration.

   <img alt="Sso Google 4 Pn" />

## Attribute mapping

1. Under the **Attributes** section, you have to configure the following attributes:

| App attributes | Google directory attributes |
| :- | :- |
| Primary email | |
| `firstName` | `First name` |
| `lastName` | `Last name` |

See the screenshot below.

2. After you have configured the attributes, click **Finish** to save the configuration.

   <img alt="Sso Google 5 Pn" />
3. From the next screen, click **User access** to configure the application to allow users to log in.

   <img alt="Sso Google 6 Pn" />
4. Check the **ON for everyone** checkbox and click **Save**.

   <img alt="Sso Google 7 Pn" />

## Next steps

You've successfully configured your custom SAML application for Google SAML. At this stage, you can assign users to your application and start using it.


# JumpCloud SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_jumpcloud

Here we will show you how to set up your own custom SAML application for JumpCloud SAML

## Create application

1. From your JumpCloud Admin console, click **SSO** from the left navigation menu.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
3. If you haven't created a SAML application, click **plus icon** and then **Custom SAML App** to create a new application

   <img alt="Sso Jumpcloud 1 Pn" />
4. Give your application a **Display Label**.

   <img alt="Sso Jumpcloud 2 Pn" />

## Configure application

1. Next click on the **SSO** tab and enter the following values:

   * **IdP Entity ID**
   * **SP Entity ID**
   * **ACS URL**

   Replace the values with the ones you have received from Aampe.

   <img alt="Sso Jumpcloud 3 Pn" />

## Attribute mapping

Under the **Attributes** section, you have to configure the following attributes:

See the screenshot below.

| Service Provider Attribute Name | JumpCloud Attribute Name |
| :- | :- |
| `firstName` | `firstname` |
| `lastName` | `lastname` |

Make sure you have checked the **Declare Redirect Endpoint** checkbox.

Finally, click **Activate** to save the application configuration.

<img alt="Sso Jumpcloud 4 Pn" />

Now go back to the SAML app you just created, click the tab **SSO**, and click the button **Export Metadata** to download the metadata XML file.

<img alt="Sso Jumpcloud 5 Pn" />

## Next steps

You've successfully configured your custom SAML application for JumpCloud. At this stage, you can assign users to your application and start using it.


# Microsoft Entra ID (formerly Azure AD) SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_microsoft_entra_id

Here we show you how to set up your own custom SAML application for Microsoft Entra ID SAML

## Create application

From your Azure Admin console, click **Enterprise applications** from the left navigation menu.

<img alt="Sso Microsoft Entraid1 Pn" />

If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application).

If you haven't created a SAML application, click **New application** from the top to create a new application.

<img alt="Sso Microsoft Entraid2 Pn" />

From the next screen, click **Create your own application**. Give your application a **Name** and click **Create**.

<img alt="Sso 3 Pn" />

## Configure application

Select **Single Sign On** from the **Manage** section of your app and then **SAML**.

<img alt="Sso 4 Pn" />

Click **Edit** on the **Basic SAML Configuration** section.

<img alt="Sso Microsoft Etraid5 Pn" />

Enter the following values in the **Basic SAML Configuration** section on the next screen:

* **Identifier (Entity ID)**
* **Reply URL (Assertion Consumer Service URL)**

Replace the values with the ones you have received from Aampe.

Click **Save** to save your changes.

<img alt="Sso 6 Pn" />

## Attribute mapping

Click **Edit** on the **Attributes & Claims** section.

<img alt="Sso 7 Pn" />

You have to configure the following attributes under the **Attributes & Claims** section:

| Name | Value |
| :- | :- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | `user.givenname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `user.surname` |

See the screenshot below.

<img alt="Sso 8 Pn" />

Go to the **SAML Signing Certificate** section and download the **Federation Metadata XML**.

<img alt="Sso 9 Pn" />

## Next steps

You've successfully configured your custom SAML application for Microsoft Entra ID SAML. At this stage, you can assign users to your application and start using it.


# Okta SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_okta

Here we will show you how to set up your own custom SAML application for Okta SAML

## Create application

1. From your Okta account, click **Applications** from the left navigation menu.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
3. If you haven't created a SAML application, click the **Create App Integration** button to create a new application.

   <img alt="Sso Okta 1 Pn" />
4. Choose **SAML 2.0** from the next screen and click **Next**.

   <img alt="Sso Okta 2 Pn" />
5. Give your application an **App Name** and click **Next**.

   <img alt="Sso Okta 3 Pn" />

## Configure application

1. Enter the following values in the **SAML Settings** section on the next screen:

   * **Single sign on URL**
   * **Audience URI (SP Entity ID)**
   * Select **EmailAddress** from the **Name ID format** dropdown.

   Replace the values with the ones you have received from Aampe.

   <img alt="Sso Okta 4 Pn" />

## Attribute mapping

1. Under the **Attribute Statements** section, you have to configure the following attributes:

| Name | Value |
| :- | :- |
| `id` | `user.id` |
| `user.email` | |
| `firstName` | `user.firstName` |
| `lastName` | `user.lastName` |

See the screenshot below.

<img alt="Sso Okta 5 Pn" />

2. On the next screen select **I'm an Okta customer adding an internal app** and click **Finish**.

   <img alt="Sso Okta 6 Pn" />
3. From your application, click **Sign On** tab and go to the section **SAML Signing Certificates**
4. Click the **Actions** dropdown for the correct certificate and click **View IdP metadata**. A separate window will open with the metadata XML file, you can copy it to your clipboard.

   <img alt="Sso Okta 7 Pn" />

## Next steps

You've successfully configured your custom SAML application for Okta SAML. At this stage, you can assign users to your application and start using it.


# OneLogin SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_onelogin

Here we will show you how to set up your own custom SAML application for OneLogin SAML

## Create application

1. From your OneLogin account, click **Applications** from the top navigation menu.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
3. If you haven't created a SAML application, click the **Add App** button to create a new application.

   <img alt="Sso Onelogin 0 Pn" />
4. Search for **SAML Test Connector** in the Find Applications section. Select **SAML Custom Connector (Advanced)** from the search results.

   <img alt="Sso Onelogin 1 Pn" />
5. Give your application a **Display Name** and click **Save**.

   <img alt="Sso Onelogin 2 Pn" />

## Configure application

1. From your application, click the **Configuration** tab on the left to configure the application.
2. You have to enter the following values in the **Application details** section:

   * **Audience (Entity ID)**
   * **ACS (Consumer) URL Validator**
   * **ACS (Consumer) URL**
   * Select the **Service Provider** from the SAML initiator dropdown.

     <img alt="Sso Onelogin 4 Pn" />

   Replace the values with the ones you have received from Aampe.
3. Click **Save** to save the configuration.

   <img alt="Sso Onelogin 3 Pn" />
4. Click the dropdown menu **More Actions** from the top right corner and click **SAML Metadata** to download the metadata XML file.

   <img alt="Sso Onelogin 5 Pn" />

## Attribute mapping

1. From your application, click the **Parameters** tab on the left.
2. You have to configure the following attributes:

| SAML Custom Connector Field | Value |
| :- | :- |
| `id` | `UUID` |
| `firstName` | `First Name` |
| `lastName` | `Last Name` |

See the screenshot below.

<img alt="Sso Onelogin 6 Pn" />

See the below screenshot to see how to map the id attribute to UUID.

3. Enter `id` in the **Field name** input and check the **Include in SAML assertion** checkbox. Click **Save** to continue.

   <img alt="Sso Onelogin 7 Pn" />
4. On the next screen, select **UUID** from the **Value** dropdown and click **Save**.

   <img alt="Sso Onelogin 8 Pn" />
5. Do the same for the other attributes (email, firstName, lastName).

## Next steps

You've successfully configured your custom SAML application for OneLogin SAML. At this stage, you can assign users to your application and start using it.


# Open ID Connect (OIDC)
Source: https://kb.aampe.com/developer-guide/sso/sso_openid_connect

Here we outline how to set up SSO via OIDC

To allow apps or clients to login using an OIDC Identity Provider, we must register an application with the IdP. The process might slightly vary from one IdP to another (refer to your IdP documentation), but there are a few things in common.

* **Callback URL**: This will be the URL where Aampe receives the OIDC Authorization response. Make sure to set the full HTTPS URL obtained by concatenating Aampe endpoint with [oidcPath](https://www.ory.sh/docs/polis/deploy/env-variables#oidcpath) env. The default value set for `oidcPath` in Aampe service is `/api/oauth/oidc`.
* **Client/Application ID**: The OIDC Identity Provider normally will generate a unique identifier for the registered App. Make a note of this to be used later when creating the SSO connection with Aampe.
* **Client Secret**: Along with the Client ID, the IdP also generates a client secret which is used to authenticate the client while issuing tokens. Make a note of this to be used later when creating the SSO connection with Aampe.

Since Aampe acts as a proxy between the app and the OIDC Identity Provider, here the application/client is Aampe.


# PingOne SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_pingone

Here we will show you how to set up your own custom SAML application for PingOne SAML

## Create application

1. From your PingOne account, click **Connections > Applications** from left navigation menu.
2. If your application is already created, choose it from the list and move to the section [Configure Application](#configure-application)
3. If you haven't created a SAML application, click **plus button** to create a new application.

   <img alt="Sso Pingone 1 Pn" />
4. Give your application an **Application Name**, choose **SAML Application** from the **Application Type** and click **Configure**.

## Configure application

<img alt="Sso Pingone 2 Pn" />

1. From the next screen, you have to enter the following values in the **SAML Configuration** section:

   * **ACS URLs**
   * **Entity ID**

   Replace the values with the ones you have received from Aampe.
2. Click **Save** to save the configuration.

   <img alt="Sso Pingone 3 Pn" />
3. Click the **Configuration** tab from the top and click **Download Metadata** to download the metadata XML file.

   <img alt="Sso Pingone 4 Pn" />

## Attribute mapping

1. Click the **Attribute Mappings** tab from the top and you have to configure the following attributes:

| SAML App | PingOne |
| :- | :- |
| `id` | `User ID` |
| `Email Address` | |
| `firstName` | `Given Name` |
| `lastName` | `Family Name` |

See the screenshot below.

<img alt="Sso Pingone 5 Pn" />

2. Make sure you have enabled your app so that it can be used by the users. You can do this by clicking the **Toggle button** next to your app.

   <img alt="Sso Pingone 6 Pn" />

## Next steps

You've successfully configured your custom SAML application for PingOne SAML. At this stage, you can assign users to your application and start using it.


# Rippling SAML SSO
Source: https://kb.aampe.com/developer-guide/sso/sso_rippling

Here we will show you how to set up your own custom SAML application for Rippling SAML

## Create application

1. You'll need to create a new Custom App from your Rippling account if the app is not already in the Rippling app directory.
2. Go to **IT Management > Custom App** from the left navigation menu.

   <img alt="Sso Rippling 1 Pn" title="Sso Rippling 1 Pn" />
3. Click **Create New App** button to create a new application.
4. From the next screen, fill in the following fields:
   * **App Name**
   * **Select Categories**
   * **Upload Logo**
   * **What type of app would you like to create?** - Make sure you select **Single Sign-On (SAML)** from the list.

     <img alt="Sso Rippling 2 Pn" />

## Configure application

1. Copy the **IdP Metadata URL** or **IdP Metadata XML** from the next screen. You'll need this value to configure your SAML connection.

   <img alt="Sso Rippling 3 Pn" />
2. You'll need to enter the **ACS URL** and **Entity ID**. You'll get these values from Aampe.

   <img alt="Sso Rippling 4 Pn" />
3. Make sure that **Service Provider Entity ID** matches the **SAML Audience (SP Entity ID)** value from Aampe.
4. From the **Settings** tab of custom app you just created. Go to **Advanced SAML Settings** section and check the box for **Disable InResponseTo field in assertions for IdP initiated SSO**.

   This is because Rippling sends dummy values for the InResponseTo field and Aampe will try to validate the InResponseTo field if it is present.

   <img alt="Sso Rippling 5 Pn" />

## Next steps

You've successfully configured your custom SAML application for Rippling SAML. At this stage, you can assign users to your application and start using it.


# Deploy a Surface into an App or Website
Source: https://kb.aampe.com/developer-guide/surfaces/surfaces-embed

To go live with Surfaces, just call the Surfaces API from within your application.

## How Do I Deploy Surfaces in My App or Website?

There are two common ways that Aampe customers deploy Surfaces

* Direct Integration
* Embedded into third-party experiences (e.g. popups via Braze)

### Direct Integration

Suppose you have the following text and image elements at the top of your layout.

<img alt="Surfaces Demo Fitness1 Pn" title="Surfaces Demo Fitness1 Pn" />

\
The subtitle was the winner from an A/B test last year, but you also know that some customers identify with other aspects of your business. You would love to give each customer the words that inspire them to use your product.

You have already set up the Surface in Aampe, along with several subtitles that speak to various reasons users have for using your product (click [here](/user-guide/using-aampe/product-surfaces/surfaces-composer) to revisit how to set up a Surface in Aampe). \
\
To insert Aampe-generated subtitles when a page loads, make use of code similar to the following.

```javascript theme={null}
// remember this is for logged-in experiences and we know the user
const contact_id = 'user_12345';
const surface_id = 'eb1efacd-cccf-492d-94ae-4fc68515cdee';

const defaultValues = {
  subtitle: 'Welcome back!'
};

// call the Aampe API to get subtitle (or any field in the Surface)
fetch(`https://asia-southeast1.content.api.aampe.com/v1/surface/content?surface_id=${surface_id}&contact_id=${contact_id}`, {
  headers: { 'Authorization': `X-API-KEY ${<api key here>}` }
})
  .then(res => res.json())
  .then(data => {
    const alt = data?.[0]?.alternates?.[0] || {};
    const subtitle = alt.subtitle || defaultValues.subtitle;

	// Set page elements to values provided by Aampe
    document.getElementById('top-subtitle').innerText = subtitle;
  })
  .catch(() => {
    // Fallback in case of error
    document.getElementById('top-subtitle').innerText = defaultValues.subtitle;
  });
```

You’ll need three things to call your Surfaces API:

* proper authorization - an API key
* `surface_id`- available within the Aampe composer for each surface
* `contact_id` - the unique person identifier used by Aampe

In this example, the API results will populate the subtitle. You can follow the same pattern to personalize other elements such as colors, image URLs, or layout.

### **Third-Party Integration**

Suppose you wanted to populate the same subtitle, but instead of the landing page we're updating an in-app popup.

You follow the same steps of (1) calling the Aampe API and (2) returning the parsed results to whatever tool renders the screen.

```html theme={null}
{{connected_content
  method: "GET",
  url: "https://api.aampe.com/v1/surface_content",
  headers: {
    "Authorization": "Bearer your_api_key_here"
  },
  params: {
    "user_id": "{{${user_id}}}",
    "surface_id": "eb1efacd-cccf-492d-94ae-4fc68515cdee"
  },
  fallback: "Smarter workouts, better results"
}}
{{#if content.[0].subtitle}}
  {{content.[0].subtitle}}
{{else}}
  "Smarter workouts, better results"
{{/if}}
```

## API Documentation

See [here](https://docs.aampe.com/reference/get_surface_content_v1_surface_content_get) for the full Surfaces API documentation.


# Surface Integration Details
Source: https://kb.aampe.com/developer-guide/surfaces/surfaces-embed-advanced

Multi-region deployments, fallbacks, latency, and more

## Surfaces API Overview

The Surfaces API is a low-latency solution for retrieving personalized content to display in your application. This is typically an app or website, but could be any application. \
\
When you make a request to the Surfaces API for one of your users, the API will respond with the recommended content to display to that user for each specified surface.

* If you'd like a refresher on the Surfaces product, [read our User Guide overview](/user-guide/using-aampe/quickstart/quickstart-surfaces).
* For instructions on calling the Surfaces API, [see our API documentation](https://kb.aampe.com/api-reference/surface).

## App Integration

The Surfaces API integrates into your application in one of two ways:

* Real time
* Pre-fetched and cached

There are some tradeoffs to consider when deciding how to integrate.

### Real Time

* **How it works:** your application calls the Surfaces API whenever a page loads with Aampe-generated content

<img alt="Realtime Flow Diagram Pn" />

* **Advantages:** simple to implement, and you only make calls only when needed
* **Disadvantages:** potentially higher latency from calling out to an external service

  <Info>
    A common technique used when implementing this approach is to display a spinner or a [skeleton screen](https://www.nngroup.com/articles/skeleton-screens/) while the data is loading.
  </Info>

### Periodically Cached

* **How it works:** your application calls the Surfaces API and caches the results, then pulls content from the cache whenever a page loads with Aampe-generated content

<img alt="Prefetch Flow Diagram Pn" />

* **Advantages:** no latency risk, can implement retries and other backups
* **Disadvantages:** some extra work to maintain a fresh cache of content

### Real Time vs Cached

| | Cached | Real Time |
| :- | :- | :- |
| Call Type | Background call, on app open | Blocking call, on component rendering |
| Batching | Get content for several surfaces at once | One or more surfaces at a time |
| Timeout | Longer timeout options | Shorter timeout |
| Retrying | Time to retry in case of network issues | Not recommended |
| Fallback | Static content in case of failed retries, timeouts, or API returning 404 | Static content in case of failed retries, timeouts, or API returning 404 |
| Control | App controls if, what, when to render | App or Aampe can control if, what, when to render |
| Tracking | App is responsible for propagating a unique id to tracking event metadata | Aampe can approximate tracking without extra instrumentation |

## Surface API Latency

### Latency SLA

The Surfaces API comes with a Service Level Agreement of P95 round trip latency of \<=150ms for requests originating from within the same region as the API.

### Reducing Latency

We recommend the following steps to reduce latency within your app when interacting with the Surfaces API

* Pre-fetch surface content, when possible
* Include multiple surface IDs when calling the Surface API
* Enforce strict timeouts such that the page will load with default content in the rare cases where the API takes longer than expected to respond
* Call the Surfaces API from within the same geographic region as the service calling the API.

### Multi Region Deployments

To minimize latency, we recommend locating your Surfaces API deployment in the same geographic region as the service from which you will be calling the API.

For instance, if your application backend runs in the `us-east1` region, we can locate your Surfaces API deployment within the same region. Differences between cloud provider regions may impact our ability to directly match your region, but we will locate it as close as possible.

When calling the Surfaces API, you will include the region identifier in the URL. For example, if you are using the `asia-southeast1` region, you will make calls to `https://content.asia-southeast1.api.aampe.com`.

<Info>
  Work with your customer success manager to ensure your Surfaces API deployment is located in the correct region.
</Info>

### Fallback Content

In cases where the Surfaces API does not have any content to show a user for a specific Surface (e.g. if the user isn't eligible for any of the content defined on that Surface), it's important to define fallback content, so you still have something to show the user.

Fallback content should be defined within your application. If no content is available for a given `contact_id` and `surface_id`, the API will return a 404 response.

## Configuration Options

The Surfaces API response contains a `control` key which includes values you can use to govern how frequently specific Surface content is displayed in your application.

```json theme={null}
"control": {
  "min_gap_days": 3,
  "max_displays_per_day": 1,
  "display_every_x_times": 5,
}
```

* `min_gap_days:`minimum number of days between surface content views
* `max_displays_per_day:` maximum number of personalized surface displays per day
* `display_every_x_times:`a rule to show personalized surface content every X page loads (otherwise, the surface loads with fallback content).


# Frequently Asked Questions (FAQs)
Source: https://kb.aampe.com/help/faqs



<Columns>
  <Card title="Creating Content" icon="pen" href="/developer-guide/data-ingest/data-integrations">
    How many messages is enough? Can I share content across channels?
  </Card>

  <Card title="Sending Data to Aampe" icon="right" href="/developer-guide/data-ingest/data-integrations#data-integration-faqs">
    What data should we send? How often? In what format? Batch or streaming?
  </Card>

  <Card title="Label Weights" icon="weight" href="/user-guide/managing-agents-strategically/label-weights#label-weight-faqs">
    Do label weights change agent behavior permanently? Is +50 enough?
  </Card>

  <Card title="Getting Data From Aampe" icon="left" href="/developer-guide/aampe-data/data-share-overview#data-share-faqs">
    What data can Aampe share back? How often does the data update?
  </Card>

  <Card title="Aampe Surface Creator (Figma Plugin)" icon="paintbrush" href="/user-guide/using-aampe/tools/figma-plugin#aampe-surface-creator-figma-faqs">
    How does the plugin work? Do I need a special Figma license?
  </Card>

  <Card title="Data Security" icon="lock" href="/developer-guide/data-ingest/data-ingest-help/data-security-and-privacy">
    Does Aampe need PII? What does Aampe do to stay compliant with privacy laws?
  </Card>

  <Card title="How Agents Learn" icon="trophy" href="/user-guide/welcome-to-aampe/how-does-aampe-work/agents#agent-faqs">
    What is an agent's reward function? How can we help agents learn more quickly?
  </Card>

  <Card title="LLMs" icon="robot" href="/help/aampt#aampt-faqs">
    Can I get an LLM to write my content for me? Is an Aampe agent an LLM?
  </Card>

  <Card title="Surfaces" icon="code" href="/user-guide/using-aampe/quickstart/quickstart-surfaces#surfaces-faqs">
    What frameworks are compatible with Aampe? What fallbacks exist?
  </Card>

  <Card title="Experiments" icon="flask" href="/user-guide/how-do-i-know/experiments/experiment-overview#experiment-faqs">
    Can I run an AB test using Aampe? How do I create a randomized holdout group?
  </Card>
</Columns>


# Aampe Glossary
Source: https://kb.aampe.com/help/glossary

Lots of funny new words when working with agentic infrastructure

**Agent**\
An AI entity assigned to each user, learning preferences through interactions and optimizing messaging in real time.

**Agentic Infrastructure**\
The system of agents, content, and labels that enables true 1:1 personalization at scale.

**Agentic Learning**\
Continuous adaptation through trial, feedback, and reinforcement, balancing exploration and exploitation.

**Alternates**\
Variant options for a single message component (e.g., three different CTAs) that agents mix and match.

**Components**\
Building blocks of a message (Greeting, Value Proposition, Offering, Incentive, CTA, Tone, Other).

**Content as Infrastructure**\
Approach where messages are not campaigns but a reusable, labeled library that fuels learning.

**Content Coverage Map**\
A structured inventory mapping product features and workflows to Topics, showing where content exists and where gaps remain.

**Contextual Bandit**\
A machine learning framework where agents select actions (e.g., messages) based on user context, balancing personalization with learning.

**Evergreen Content**\
Always-on messages (e.g., feature education, FAQs) that form the bulk of agent learning.

**Exploration vs. Exploitation**\
The balance agents strike between testing new content and using proven, high-performing variants.

**Inner Voice Statement**\
User-centered phrasing of a value proposition (e.g., “I want to feel in control of my finances”).

**Labels**\
Semantic tags (e.g., “Convenience,” “Urgency”) applied to alternates, enabling agents to reason and compare systematically.

**Message Group**\
A set of related messages made by combining alternates and labels, tested together for personalization.

**Offering**\
The specific product, feature, or benefit highlighted in a message.

**Reinforcement Learning (RL)**\
Learning approach where agents adjust strategies based on observed user behavior and outcomes.

**Reward Function**\
The feedback mechanism agents use to determine whether a message or action led to a desirable outcome.

**Surfaces**\
Channels or placements where messages appear (push, email, SMS, in-app, web).

**TACIR (Target Agent-Customer Interaction Rate)**\
The ideal frequency of interactions per week between agents and users, used as a diagnostic for content sufficiency.

**Thompson Sampling**\
A probabilistic method agents use to select actions, balancing exploration of new options with exploitation of known successes.

**Three-Fold Agentic Content Strategy**\
Framework dividing content into Evergreen (60%), Triggered (30%), and Tactical (10%) categories.

**Topic**\
A high-level communication category (e.g., “Welcome,” “Churn Rescue”) that bundles offerings, audiences, and contexts.

**Triggered Content**\
Event-based messages delivered in response to user actions (e.g., cart abandonment, subscription pause).

**Value Proposition**\
The core reason users should care about an offering, often tied to human values (e.g., Control, Trust).


# Aampe Documentation
Source: https://kb.aampe.com/index

Explore our knowledge base to learn how to set up, use, and manage Aampe successfully

<Columns>
  <Card title="User Guide" icon="user" href="/user-guide/user-guide">
    Aampe like a pro! Quickstart guides for new users. Advanced topics for the Aampe pros.
  </Card>

  <Card title="Developer Guide" icon="database" href="/developer-guide/developer-guide">
    You'll have Aampe set up in no time! SSO, data management, security FAQs, and more.
  </Card>

  <Card title="API Guide" icon="link" href="/api-guide/api-guide">
    Detailed API documentation for data ingestion, surfaces, and more.
  </Card>

  <Card title="Help" icon="hand" href="/help/faqs">
    Not sure where to go? We'll help you find your way.
  </Card>
</Columns>


# Aampe App Library
Source: https://kb.aampe.com/tools/aampe-app-library

The place to try out new Aampe features before they are generally

## What is the Aampe App Library?

We have a lot of grand ideas at Aampe. We can't build them all at once in the Aampe composer, but we can stand up prototypes and gather some early feedback.

The tools you'll find at [apps.aampe.com ](https://apps.aampe.com/)make use of externally available Aampe APIs, but are otherwise standalone apps. If you wanted, you could build these kinds of apps yourself.

## What kind of apps are available?

Check back often, as we are adding (and removing) apps frequently based on user feedback. The following apps are currently available at [apps.aampe.com](https://apps.aampe.com/):

### **Aampe Email Variable Config**

Paste your email HTML and Aamplify it by carving out the fields required to add agentic copy.

* Upload your HTML
* Highlight the elements you want to personalize
* Download the results or copy/paste back into the Aampe composer

<img alt="Aampe Email Template Config" />

### **Aampe Surface Creator**

Connect your Aampe account to Figma to quickly turn your creative assets into Aampe-ready content

Read more about the [Aampe Surface Creator](/tools/figma-plugin).

### **Surface Template Builder**

Define a new Surface templates and test the JSON with a live API. This is great for developers who want to experiment with a live Surfaces API.

* Give your new surface a name and description
* Add elements to the surface template
* Test the Surfaces API and examine the results

<img alt="Surface Template Builder" />

### **Relay**

Harness the power of LLMs to generate content at scale while preserving all the conventions required for labels, learning, and clean measurement.

* Upload API keys for Aampe and your LLM of choice
* Fill out two forms
  * One is about your company: What is your brand voice? What does your company do?  What components and labels do you want to use?
  * The next is about your content: What kind of messages do you want to make? How do you want to frame your offerings and calls to action?
* Preview the results and send the content director to the Aampe composer

<img alt="Relay" />


# AamPT
Source: https://kb.aampe.com/tools/aampt

Your always-ready Aampe LLM

## Introducing AamPT

<iframe title="YouTube video player" />

<Warning>
  * As with any LLM, AamPT can make mistakes — please verify important outputs.
  * AamPT runs on OpenAI infrastructure. Aampe sets up the custom GPT upon request. Review your company's LLM policy before use.
</Warning>

Say hello to **AamPT**, [Aampe's Custom GPT for content creation](https://chatgpt.com/g/g-6a7937e7c0e881918d90045112bc4f1c-aampt-by-moengage).

AamPT is an LLM that has Aampe's documentation and resources uploaded into it's knowledge bank along with specialized instructions to provide the best help possible to Aampe customers. It works like any other LLM, but is specialized to provide improved results for Aampe related tasks.

## What Can AamPT Do?

AamPT can do anything you might normally ask an LLM to do, but for Aampe-specific tasks.

* Answering questions and understanding definitions
* Brainstorming on content format, verbiage, and labels
* Creating datasets
* Writing code to integrate your data sources or messaging tools

## Some Useful Prompts

Here are some sample prompts to use, when you want to ask AamPT to..

### 1. Write a message for you (Simple)

Use this when you're not sure about the message structure, but just have a general idea of the message you want to write. Specify the channel you want to write for, and the objective of the message. aamPT will first suggest message structures and then generate content.

Note: aamPT might make up labels unless you specify the ones you want, or if you're already using a customized version of aamPT designed specifically for your product.

Prompt:

> Write a push notification about Booking a Taxi. The purpose of the message is to get users to book a taxi ride on this app.

### 2. Write a message for you (Detailed)

Use this when you know exactly what you want. Specify the channel, objective of the message, message structure and labels to use (either reference a document with all your labels, or add it into the prompt).

Prompt:

> Write a push notification about Booking a Taxi. The purpose of the message is to get users to book a taxi ride on this app.<br />Message Structure:<br />Header: \[Value Proposition]<br />Body: \[Offering] x \[Call to action]<br /><br />Value Proposition Labels: Convenience, Speed, Affordability, Luxury<br />Call to action Labels: Direct, Friendly, Urgent<br />Offering Labels: Pick Up, Drop Off, In-Ride Features<br /><br />Give me 3 alternates per label in each component.

### 3. Think of message structures

Use this when you're not sure how to use or order your components in your message. aamPT can give you some ideas. Specify the channel you're using and its sections.

Prompt:

> Suggest some message structures for an email about Booking a Taxi. My email template has the following parts:<br />Subject Line (70 chars)<br />Pre-header (40 chars)<br />Title (40 chars)<br />Subtitle (80 chars)<br />Body (750 chars)<br />Button (25 chars)<br />I'd prefer to keep the Pre-header and Subtitle as Static text. Only the Body may contain multiple components. Identify any message-level components & labels (if applicable). Do not use message-level components within the email content.

### 4. Think of value propositions

Use this to help you ideate value proposition labels for your product or app.

Prompt:

> Please do the inner values exercise for the \[Insert Name] app, and derive a list of Value Proposition labels in the context of that app.

***

[*If you need help with sample prompts for any other use cases, reach out to mohana@aampe.com*](mailto:mohana@aampe.com)

## Aampt FAQs

<Accordion title="My company does not allow ChatGPT. Can I use AamPT?" icon="sparkles">
  No. AamPT is an OpenAI product. If you cannot use ChatGPT at work, you should not use AamPT. If there is another LLM that satisfies your AI/LLM policy, we can help you create an LLM assistant for Aampe-related tasks.
</Accordion>

<Accordion title="Does AamPT use Aampe's OpenAI account or mine?" icon="sparkles">
  Aampe has an OpenAI business account for provisioning custom GPTs. If you have a similar account, we are happy to help you set up an AamPT using your account.
</Accordion>

<Accordion title="Are AamPTs public?" icon="sparkles">
  Generally no. AamPTs are private GPTs made for specific customers. There is [one generic AamPT](https://chatgpt.com/g/g-67da7b93da0c819197628ee0862fed03-aampt) with no customer information. 
</Accordion>

<Accordion title="Does OpenAI use AamPT conversations for model training?" icon="sparkles">
  Aampe uses a **business account** for AamPT, which means that any information entered is *not* used to train the underlying OpenAI models. Please see [OpenAI's documentation](https://help.openai.com/en/articles/5722486-how-your-data-is-used-to-improve-model-performance) for questions on data retention and model training.
</Accordion>


# Aampe Surface Creator
Source: https://kb.aampe.com/tools/figma-plugin

Connect Aampe with all your creative assets in Figma

If your team uses Figma, the [Aampe Surface Creator](https://www.figma.com/community/plugin/1520139378515460963/aampe-surface-creator) plugin can help you quickly extract page components and prepare them for integration.

<iframe title="YouTube video player" />

Within Figma, select `Actions >  Plugins & Widgets` and find the **Aampe Surface Creator.**

After opening the Aampe Surface Creator, you'll be prompted to sign in to your Aampe account. Sign in and follow the Surface Creator prompts.

* Select your Frame
* Choose which Frame elements you wish to include in your Surface

<img alt="Surfaces Demo Figma1 Pn" title="Surfaces Demo Figma1 Pn" />

* After selecting your components and assigning types and names, you can export the list to Aampe in a single click (**Add to Aampe**).

  <img alt="Surfaces Demo Figma2 Pn" title="Surfaces Demo Figma2 Pn" />

  This will generate a template in Aampe with all the necessary fields, ready for your specific messages and all their variants.

## Aampe Surface Creator (Figma) FAQs

<Accordion title="Can I see my Aampe content within Figma?" icon="sparkles">
  ~~Currently, the Aampe Surface Creator sends only creates a surfaces template within Aampe. It does not pull Aampe content into Figma.~~

  Yes! The Aampe Surface Creator can now push Figma elements into an Aampe template, and also pull content from Aampe to see how it different variants render. 
</Accordion>

<Accordion title="Can we use the Aampe Surface Creator plugin for email templates?" icon="sparkles">
  At the moment, the Aampe Surface Creator only creates templates for surfaces. 
</Accordion>

<Accordion title="Do I need a paid tier of Figma to use the Aampe Surface Creator?" icon="sparkles">
  No. You can use the Aampe Surface Creator on [Figma's free tier](https://www.figma.com/pricing/). 
</Accordion>


# Power Analysis Calculator
Source: https://kb.aampe.com/tools/power-analysis-calculator

How big does this holdout group need to be? 

<iframe title="Power Analysis Calculator" />


# Release Notes
Source: https://kb.aampe.com/updates/release-notes

Stay up to date with important changes.

<Icon icon="square-rss" /> [RSS feed](https://kb.aampe.com/updates/release-notes/rss.xml)

<Update label="March 2026">
  ### Simplified home screen and recommended actions

  * Our home page in the composer has a new look! Simpler. Cleaner. More actionable.

  ### Data Share: new table for aampe-generated user events

  * This new table includes details for message opens, clicks, unsubscribes, etc.
  * This is *not* the full customer event feed, only events that originate in response to Aampe content. These events are visible in the composer and contain the prefix `aampe_`
  * See the [table description](/developer-guide/aampe-data/data_share_tables) for additional details.
</Update>

<Update label="February 2026">
  ### Message frequency overrides

  * More customers can now override the frequency limits set within their message delivery tools (e.g., Braze or CleverTap).
  * Learn more about the available options for [configuring message frequency](/user-guide/using-aampe/admin/frequency-limits).

  ### Simplified menu for Event Types

  * We reduced the number of Event Types to three simple buckets: positive, negative, and irrelevant.
  * Read on to learn more about [Event Types](/user-guide/using-aampe/admin/event-types) and how they work.

  ### Data Share: new table for message attempts

  * This new table includes details for every attempted message, enabling users to monitor delivery success rates for each message formula.
  * See the [table description](/developer-guide/aampe-data/data_share_tables) for additional details.
</Update>

<Update label="January 2026">
  ### **Aampe surface creator**

  * Users can now pull content from Aampe into Figma in addition to pushing Figma elements into an Aampe template. Figma users can see how their creative assets look under all the different ways Aampe could potentially serve them.

  ### Composer cleanup

  * Removed Sequences and other dated elements
  * Removed old docs embedded in our integration section
  * Added the user role and company logo alongside the user name (bottom left)

  ### [apps.aampe.com](http://apps.aampe.com)

  A new collection of standalone apps to help Aampe customers create and improve their content. Current apps include...

  * **Aampe Email Variable Config**:  Paste your email HTML and make it agentic ready by generating the fields required to add agentic copy.
  * **Aampe Surface Creator**: Connect your Aampe account to Figma to quickly turn your creative assets into Aampe-ready content
  * **Surface Template Builder**: Define new Surface templates and test the JSON with a live API.
  * **Relay**: Harness the power of LLMs to generate content at scale while preserving all the conventions required for labels, learning, and clean measurement.

  [Continue reading](/tools/aampe-app-library) for a brief overview of each app.

  ### Topic management

  Stay organized by grouping your content under [Topics](/user-guide/managing-agents-strategically/topics). Topics are a great way to organize content by team, objective, or any other heuristic.
</Update>

<Update label="December 2025">
  ### Test messages

  * Updated frontend experience for sending test messages
  * Learn how to send test messages with [our updated experience](/user-guide/using-aampe/messages-by-channel/push/send-test-message)

  ### API key management

  * Updated frontend experience for [API keys](/api-guide/api-keys)

  ### Backend improvements for real-time decisioning

  * Better support for real-time, context-aware decisions based on user events
</Update>

<Update label="November 2025">
  ### Event management

  * Updated navigation. Renamed `System setup/Funnel events` to `System setup/Event management`
  * Revamped the concept of "Event rewards" to "Event types" based on early customer feedback. Simpler menu and additional options for negative events.
  * Read more about [Event types](/user-guide/using-aampe/admin/event-types)

  ### Content coverage

  * Updated visuals under `Monitoring > Label management > Content coverage` to avoid color saturation with high alternate counts
  * Read more about [Content coverage](/user-guide/managing-agents-strategically/content-coverage)

  ### Labels via datasets

  * Datasets did not previously allow [labels](/user-guide/welcome-to-aampe/how-does-aampe-work/labels) to accompany message content.
  * Read more about [datasets](/user-guide/using-aampe/tips-and-tricks/datasets#advanced-dataset-features)
</Update>

<Update label="October 2025">
  ### Platform hardening

  * Internal monitoring for customers on the next-gen streaming backend

  ### Roles and permissions

  * [New Role - Editor](/user-guide/using-aampe/admin/users-and-roles)
    * Limits editing permissions to specific users
    * Read more about Aampe's [roles and permissions](/user-guide/using-aampe/admin/users-and-roles)
</Update>

<Update label="September 2025">
  ### Label weights

  * Increase or decrease the weights for specific labels to influence how often agents use them relative to other labels
  * Read more about [label weights and how to use them](/user-guide/managing-agents-strategically/label-weights)

  ### Email templates

  * Previously, email templates could not be cloned

  ### Support for email messages via CleverTap

  * Now Aampe integrates with CleverTap for both push notifications and email
  * See our guide for [integrating with CleverTap](/developer-guide/message-providers/message-pages/clevertap)

  ### Support for messages via WhatsApp

  * Send Aampe messages via WhatsApp the [same way you would use Aampe with SMS](/user-guide/using-aampe/messages-by-channel/sms/create-sms)
</Update>

<Update label="August 2025">
  ### Managing multiple languages

  * Many Aampe customers send messages in multiple languages
  * See [an example of configuring multiple languages in Aampe](/user-guide/using-aampe/admin/languages)

  ### Messages via Twilio

  * Aampe integrates with Twilio for SMS delivery
  * See our guide for [integrating Aampe with Twilio](/developer-guide/message-providers/message-pages/twilio)
</Update>


# Analytics Overview
Source: https://kb.aampe.com/user-guide/how-do-i-know/analytics/analytics-overview

Measure and optimize your content strategy

## Our Analytics

We have two main methods of delivering insights.

## Just the Raw Data, Please

There are two types of datasets available from Aampe.

* **User data:** Agents learn things about your users that are potentially useful as inputs in other models. Does a user respond to one offering vs another? What value propositions does each user align with best?
* **Event data:** Agents make decisions using several statistical heuristics. We save the inputs and outputs of the decision-making process for offline analysis and reporting.

Ask your customer-service representative to set up a data share to route these tables into your preferred destination.

See our [developer hub](/developer-guide/aampe-data/data-share-overview) for a more detailed overview of our data sharing options.

## Composer Analytics

Aampe provides several charts to help you monitor your agent workforce. These are primarily located under the **Analytics** tab, but are also found throughout the composer for more focused content.

See [here](/user-guide/how-do-i-know/analytics/composer-analytics) for an overview of each chart, what it means, and how to use it.


# Composer Analytics
Source: https://kb.aampe.com/user-guide/how-do-i-know/analytics/composer-analytics

Let's take a tour of the reporting available within the Aampe composer. 

### Analytics: Messages Sent

The Messages Sent chart provides information on overall message volume and success rates. You can also drill into individual message formulas, labels, channel, and more.

<img alt="Sent Messages Line Chart" />

This information is helpful for questions about what Aampe is doing - such as

* How many messages are being sent every day for each channel?
* What messages are sent the most/least on a given day?
* How are messages balanced across different labels?

<Info>
  To see Aampe's "success rate" click on the % sign at the top left. \
  \
  Success rate is defined as the number of successful events divided by the total number of messages sent for the current week.
</Info>

### Analytics: Performance

To drill into the specific outcomes of messages, refer to the Performance tab. Choose a group of events (based on the Funnel categorization) along with any subset of message formulas to see (1) the number of events that were potentially influenced by Aampe messages or (2) the percent of messages led to a particular event.

<img alt="Performance Pn" />

At the moment, these insights are only available for aggregate funnel groups. You can, however, add and remove events from funnel groups to pinpoint individual events when needed.

### Insights: Frequency Tracker

There’s no one-size-fits-all answer to how often users want to hear from you. Some users thrive with five messages a week, others churn if you send more than two.

The Frequency Tracker shows what share of users received a specific number (or range) or messages each week.

<img alt="Frequency Pn" />

This information is helpful for ensuring users receive an appropriate number of messages. Note there is no category for 0 messages when looking at exact counts, but you can change the toggle on the right to see 1 message or less.

<Info>
  Currently, agents monitor frequency based on a rolling 7-day window while reporting via the Frequency Tracker is based on a calendar week. At times this means the Frequency Tracker will show a small subset of users receiving more messages than they should be allowed.
</Info>

### Insights: Message Scheduler

The Message Scheduler tracks how users engage with messages to identify their ideal send times. This dashboard shows how agents learn and adapt over time — eliminating guesswork by testing and adjusting delivery windows based on real performance.

<img alt="Scheduler Pn" />

* **Sent**: Messages are sent and validated
* **In Validation**: Waiting for message delivery confirmation
* **In Progress**: Actively sending messages
* **Scheduled**: Messages slotted for future delivery
* **Not Scheduled**: The day has not yet entered the scheduling window
* **Empty**:   No messages scheduled for that day. Time to add more content!
  <Info>
    Scheduled messages: agents make plans in pencil before making a real-time decision about whether to send a message and if so, what message to send.
  </Info>

### Insights: Week in Progress

The Week in Progress tag zooms in on the current week, showing you scheduled and sent messages for each day of the week and each 3-hour time bucket in the day (local time).

<img alt="Message Performance Pn" />

This also overlays performance from the previous week for easy comparisons week to week.

### Message Performance

The Message Performance provides a way to compare the performance of individual messages and their outcomes. The initial chart shows (1) total messages sent by day and (2) the estimated click-through rate of those messages based on the customer event feed. \
\
You can filter the chart to specific messages or groups of messages using the search bar, tags, or message status menus.

<Frame>
  <img alt="Message Performance" />
</Frame>

The click through rate looks at the total number of message-events and calculates the subset where a click-event falls within each message-event's attribution window. Aampe does not use cookies or UTMs to connect click-events to specific messages (many message providers do not provide that information). \
\
The success metrics in the table below make use of the same attribution-window heuristic, but for any funnel event.

<Frame>
  <img alt="Message Performance Table" />
</Frame>

* What share of message events have any conversion event within the attribution window?
* What share of message events have any engagement event within the attribution window?

Attribution windows vary by customer and are configured during customer onboarding. If you have forgotten your attribution window, you can contact your customer success manager. The default attribution window is 24 hours. \\

### Surface Performance

For customers using Surfaces, the Surface Performance tab provides insight on each Surface message and important details about it's delivery, consumption, and sucess.

<Frame>
  <img alt="Surface Performance" />
</Frame>

### Attribution and Click Counting in Greater Detail

<Info>
  When analyzing message performance, Aampe follows specific rules of how clicks are attributed. Key points:

  * For the sake of reporting, clicks make use of the message-send timestamp, not the actual click time.
  * Only clicks occurring within 24 hours of the send are counted; any click after that window is excluded.
  * If multiple messages could plausibly receive credit, Aampe shares or reduces attribution weight across them.
  * Data may take up to 24 hours to fully settle, due to ingestion and processing lag.
</Info>


# What Kinds of Experiments Work in Aampe?
Source: https://kb.aampe.com/user-guide/how-do-i-know/experiments/experiment-overview

1:1 personalization breaks message-level measurement 

### **A Fundamental Difference**

Traditional CRM systems operate through campaigns: fixed messages sent to defined audiences at specific times. Each campaign typically has its own random holdout group, and attribution is straightforward because all treated users receive the same message simultaneously.

Agentic AI systems like Aampe operate differently. Instead of campaigns, they create personalized message sequences for each user. This level of personalization is great for customers, but creates difficulties for traditional measurement techniques.

**Path Dependency and Its Implications**

In true 1:1 personalized systems like Aampe, actions become path-dependent. Each message influences the messages that follow depending on how it performs. This creates several measurement challenges for an individual message:

* **Random Assignment**: Recipients and non-recipients of a given message have been chosen *strategically*, not randomly.
* **Cumulative Impact**: Traditional A/B tests measure the immediate response to a message. Personalized sequences build impact over time as each message learns and improves from prior messages.
* **Treatment Timing**: Measuring impact is difficult when some users receive a message on a Tuesday morning, while other users receive the same message on a Saturday evening.
* **Learning Phases**: Aampe agents learn in real-time from watching users respond to different messages. It can take several customer interactions to discover strong patterns. Messages at the start of a sequence are not typically as impactful as messages later on.

### **Implications for Testing**

Standard campaign-level holdouts lose meaning when users receive different messages at different times. But 1:1 personalization is exactly that, different messages at different times.

So rather than evaluate individual messages, we need to step back and evaluate the message-generation process. Instead of asking, "does message A beat message B?" we start asking, "does an adaptive, learning system outperform static rules?" \
\
This requires longer test periods, different group structures, and metrics that capture cumulative rather than immediate effects.

What does this look like in practice? [Learn how to set up your first holdout test in Aampe](/user-guide/how-do-i-know/experiments/holdout-part2).

## Experiment FAQs

<Accordion title="How do we run a clean holdout test with Aampe?" icon="sparkles">
  Most customers who want to measure the incremental impact of Aampe do so by assigning a randomized portion of their users to Aampe audiences. This requires passing in the group assignment as a user attribute and using it to define audience eligibility. \
  \
  [Keep reading to learn more about how to set up an experiment in Aampe](/user-guide/how-do-i-know/experiments/holdout-part2).
</Accordion>

<Accordion title="When is my Aampe account ready for an experiment?" icon="sparkles">
  Aampe performs best with a rich content library and frequent customer interaction. On the other hand, it would be unwise to spend a year building out content in Aampe before knowing if it delivers value to your business. \
  \
  Somewhere in the middle is the sweet spot. You've built up enough of a content library in Aampe so that your agents have many ways to engage with users, but you're still testing early to see where/how Aampe is most effective. This helps inform your next wave of content. 
</Accordion>

<Accordion title="We ran a successful test on a small subset of users? Will my results scale to my entire customer base?" icon="sparkles">
  We certainly hope so! It depends on many things including the setup of the initial test, how easily the initial experience can be replicated, spillovers, and other forces of nature. 

  [Read more about how results can change as the audience scales.](/user-guide/how-do-i-know/experiments/will-results-scale)
</Accordion>


# How to Set Up an Experiment in Aampe
Source: https://kb.aampe.com/user-guide/how-do-i-know/experiments/holdout-part2

A practical example

### Comparing Systems

When 1:1 personalization makes traditional message-level testing impossible, we need to evaluate the entire system instead.

* This is true when comparing Aampe's agentic personalization against non-personalized customer experiences
* This is also true when comparing different agentically-personalized systems, such as when A/B testing various Aampe configurations.

What follows is an example framework that has worked well with many Aampe customers. Your specific setup will vary based on your individual circumstances.

### Group Structure

In the scenario when we are comparing agentic personalization against a non-agentic system, it is helpful to create three user groups:

* **No-Message Group**: Receives no marketing messages. This establishes your true baseline behavior—what happens without any messaging influence. While it may feel counterintuitive to leave out some users, this group reveals which behaviors are truly driven by messages.
* **Business-as-Usual Group**: Continues receiving existing campaign messages through current tools. This group provides the benchmark for what you're currently achieving.
* **Aampe Group**: Receives messages exclusively from Aampe's agents. As much as possible, no business-as-usual marketing messages should influence this group. This isolation allows you to measure what the AI system can achieve when given full control.

The size of each group is your choice, but there are tradeoffs with the size of each group and the amount of time required to confidently observe differences. Aampe has tools available to help you visualize these tradeoffs and decide on your group sizes.\
\
Another consideration is the size of the Aampe group. Because agents can learn from each other, a small Aampe group is inferior to a large Aampe group. To get the most accurate comparison of Aampe and a traditional system, it makes sense to have a larger Aampe group.

### User Group Assignment

Assignment should be randomly assigned to groups in a way that is easy to extend to new users who join during the experiment. The assignment is permanent and consistent throughout your system. For this example we'll randomize over user IDs.

```
CASE 
  WHEN MOD(HASH(user_id), 100) < 10 THEN 'no_message'
  WHEN MOD(HASH(user_id), 100) >= 10 AND MOD(HASH(user_id), 100) < 55 THEN 'business_as_usual'
  ELSE 'aampe'
END
```

**Include Everyone**: New users need to be assigned to a group upon entering the system. If new users all land in the same group, the results of the experiment will be biased.

**Apply Everywhere**: The group assignments must be consistent across all relevant tools.

* Data warehouse (for analysis)
* Existing marketing tools (for excluding the aampe-only and no-message groups)
* Aampe (for excluding the business-as-usual and no-message groups)
* Any other messaging systems

**Look out for Spillovers**: Ensure the experience of one group does not affect the experiences of other groups. If this is the case, Aampe can help you determine an alternative randomization strategy.

* Example: Business-as-usual sends coupons for a product. The product has limited supply and runs out of stock. The coupon recipients buy more of the product than usual, while the no-message group buys less of the product because it's out of stock.

### Content Requirements

For the AI to learn effectively, it needs sufficient material to work with:

* **Diverse Labels**: Create content across multiple distinct label categories representing different value propositions. If you only provide discount messages, the agents will only learn discount preferences.
* **Balanced Channels**: If business-as-usual messages apply to several channels, ensure the same channels are available to the agentic personalization group.
* **Comprehensive Audiences**: If the goal is to learn if agentic personalization performs better or worse than another approach, the Aampe audiences should be as diverse as the business-as-usual audiences.

Fortunately, Aampe provides the infrastructure to easily manage both content and audiences.

### Message Delivery

To ensure the test is running as expected, it is key to have visibility into what messages are delivered and when.

* The primary concern is that the business-as-usual messages are sent *only* to the business-as-usual group (same for the aampe group).

There may be times during the test when all users must be messaged. When unavoidable announcements must be made (major sales, critical announcements), message all groups equally.

### Pre-Test Planning

Before launching your experiment, establish your measurement framework:

* **Primary KPI**: Select your primary metric before starting. This prevents post-hoc rationalization and keeps analysis focused.
* **Statistical Power**: Understand how long you'll need to run the test given your metric's natural variance and the effect size you hope to detect. Higher variance metrics and smaller expected effects require longer test periods.
* **Burn-in Period**: Plan to exclude an initial period from primary analysis. Early results often reflect adjustment periods rather than steady-state performance—users adapting to no messages, agents still learning preferences, etc.

How do we compare the groups once we've completed the experiment? [Keep reading](/user-guide/how-do-i-know/experiments/holdout-part3) for thoughts on analyzing the experiment results.


# Measuring Results of an Aampe Experiment
Source: https://kb.aampe.com/user-guide/how-do-i-know/experiments/holdout-part3

We're in familiar A/B testing territory now

### From Setup to Analysis

Once your experiment groups are established and running, the focus shifts to measurement. Evaluating system-level performance requires different analytical approaches than individual campaign testing, with particular attention to cumulative effects and temporal patterns.

This section covers common analytical approaches that have proven useful, though the specific methods will depend on your metrics, user behavior patterns, and business context.

### Things to Look For

When examining your results, several patterns deserve extra attention:

* **Group Divergence**: Watch for groups gradually drifting apart over time rather than immediate separation. System-level effects often compound, making end-period performance more informative than early results.
* **Pre-experiment Trends**: Check whether groups showed similar patterns before the experiment began. Consistent historical behavior strengthens confidence that post-experiment differences are real.
* **Within-Group Outliers**: Identify users with extreme behaviors in each group. A single high-value customer can distort averages. Consider whether your conclusions change if outliers are handled differently.
* **Temporal Consistency**: Look for sustained differences rather than one-time spikes. A single good week doesn't prove system superiority.
* **Cross-Group Patterns**: If all groups show similar temporal patterns (everyone dips during holidays), these are likely external factors rather than treatment effects.

### Visual Analysis

Start with clear visualizations:

* Time series showing weekly or daily averages by group
* Confidence intervals or standard errors around estimates
* Cumulative metrics to show total impact over time
* Distribution plots to understand the full range of user behaviors, not just averages

Visualizations often reveal patterns that statistics might miss—sudden changes, gradual trends, or unusual volatility.

### Statistical Approaches

The specific approach of choice will vary across use cases, but here is a non-exhaustive list of useful methods that we often use when examining an experiment where the impact potentially builds slowly over time:

* **Difference-in-Differences (DiD)**: Compares the change in treatment groups against the change in control. This accounts for temporal trends affecting all users and isolates the treatment effect.
* **CUPED (Controlled Pre-Experiment Data)**: Uses pre-experiment behavior to reduce variance in estimates. Users who were highly active before the experiment tend to remain active—CUPED leverages this predictability to detect smaller effects.
* **Regression Analysis**: Model outcomes at the user level, including treatment assignment, pre-experiment behavior, and time effects. This allows you to control for confounding factors and estimate treatment effects more precisely.
* **Synthetic Controls**: Fit time-series models on pre-test data, then compare observed post-test results to predicted values. Useful when you have rich historical data and want to account for complex temporal patterns.

The choice of method depends on your data characteristics and the questions you're asking. Consider consulting with data scientists familiar with causal inference if these methods are new to your team.

### Special Considerations

* **Heavy-Tailed Distributions**: User behavior often follows power laws—most users do little, a few do a lot. Consider winsorizing extreme values or using median-based metrics alongside means.
* **Zero-Inflation**: Many metrics are mostly zeros (purchases, for example). Standard statistical models may perform poorly. Zero-inflated models or analyzing "probability of action" separately from "amount given action" can help.
* **Multiple Testing**: If you examine many metrics or time periods, some will show significance by chance. Consider corrections for multiple comparisons, or better yet, stick to your pre-registered primary metric.
* **Sample Size Imbalances**: If one group is much smaller than others, it may show more variance simply due to size. Weight your analyses appropriately or ensure adequate sample sizes in all groups.

Your test is done! Hopefully it executed without any major mistakes.

A clean experiment is a lot of work and surprises are inevitable. [Our final section](/user-guide/how-do-i-know/experiments/holdout-part4) lists common errors we've encountered while helping businesses set up system-level experiments as we've described.


# Common Problems with Experimentation
Source: https://kb.aampe.com/user-guide/how-do-i-know/experiments/holdout-part4

Turns out running a clean experiment is a hard thing to do

### Learning from Experience

Even well-designed experiments can fail due to implementation issues. Understanding these common pitfalls can help ensure your tests work out well.

### Error 1: Incomplete System Integration

Groups defined in Aampe but not excluded from other tools. This means we're testing Aampe *in addition* to the business-as-usual experience and there is no no-message group.

***Prevention***\*: Audit all messaging systems, implement exclusions universally, verify clean execution via message logs.\*

### Error 2: Premature Testing

It's possible to test agentic personalization too soon. Testing with insufficient content or limited use cases is not representative of Aampe's potential impact. Aampe provides the infrastructure to make this easy.

***Prevention***\*: Build a robust content library before testing. Ensure several relevant message types per user segment. Take the time to build out the Aampe experience before setting up a grand experiment.\*

### Error 3: Results Aren't Immediate?

It can take time for an experiment group to adjust to a new system. While analyzing results, this transition period is ignored and biases the results.

***Prevention***: Run tests long enough to observe cumulative patterns. Focus more on where the groups finish and less on the transition to the new steady state. \_

### Error 4: Asymmetric Capabilities

Business-as-usual includes promotions or other core offerings unavailable to Aampe.

***Prevention***\*: Assess all message types in both systems and ensure comparable offerings. Either add those use cases to Aampe, or pause them for the business-as-usual experience.\*

### Error 5: Excessive Broadcasts

Frequent "emergency" broadcasts to all users.

***Prevention***\*: This isn't always preventable. At the very least, document all emergency broadcasts and be ready to exclude those days from the final analysis as appropriate.\*

### A Common Thread

These errors often stem from applying campaign-testing frameworks to a system evaluation. Agentic AI requires testing highly personalized, adaptive experiences over time, not comparing individual messages. Design tests that measure what the system actually does: learn, adapt, and personalize at scale.

***


# Will My Early Test Results Scale?
Source: https://kb.aampe.com/user-guide/how-do-i-know/experiments/will-results-scale

Possibly yes. If not, here's why.

## Double the Winners = Double the Winnings?

Suppose an organization runs Aampe alongside their business-as-usual (BAU) messaging in a 50/50 split. When Aampe shows strong results, there's a natural expectation that switching the other half to Aampe should double the overall business impact.

That expectation makes sense and sometimes that's exactly what we see. Other times, however, things work out differently. Here are some potential reasons why an experiment may fail to replicate its early results.

### Cold Start for Personalization

Aampe agents learn individual behavior. Each new user begins in a learning phase where the agent tests timing, channels, and content combinations to discover what works.

Performance is naturally lower during exploration. Users with Aampe likely went through this for several weeks before seeing results. \
\
It's possible that the newly added BAU users will experience the same success as the Aampe group, and simply need more time for the agents to learn.

### Different Starting Points for BAU Users

Users under BAU are accustomed to a specific cadence, tone, and product focus.

When moved to Aampe, agents must work harder to overcome these patterns. Some users will respond to new and different content; others may not budge. A long history of BAU interactions potentially makes these users systematically different from the Aampe group in the test.

### Spillover Effects

In split tests, there's a risk that the treatment group influences the control group in some way. A common scenario is when treatment users respond to an incentive such that the product is no longer available to the control group.

When this happens, it exaggerates the differences between the two groups. The differences disappear, however, when both groups receive the same experience.

### Seasonality and Timing

Any test occurs during specific conditions: a particular season, a set of active promotions, certain market dynamics. While the environment is the same for both groups, the relative impact of Aampe may vary under a different season, different promotions, etc.

### Regression to the Mean

Smaller test groups are more likely to outperform long-run averages due to chance, user composition, timing, or other factors. This is true of any test.\
\
Full rollouts with larger groups settle toward true averages, however, which may differ from the short-term test results of a small group.

## Moving Forward

Full adoption marks the beginning of a new optimization phase. Some factors will improve with time (cold start). Other factors are worth examining to see how likely they are to have influenced the results.

This research can inform [how you work with agents moving forward](/user-guide/managing-agents-strategically/working-with-agents), as well as how you might improve upon experiments in the future.


# Content Coverage
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/content-coverage

Curious about how your Labels are spread across Message groups? This view will show you gaps and opportunities to add more content

The **Content Coverage** view helps you understand how well your [labels](/user-guide/welcome-to-aampe/how-does-aampe-work/labels) are distributed across Message groups, and where there are opportunities to add more alternates or balance existing ones. It brings together insights about combinations, balance, gaps, and opportunities — helping you identify where content can be expanded or optimised for better message variety and performance.

## What You’re Looking At

The grid represents pairs of Labels from two different Components (for example, *Offering* and *Value Proposition*).

<img alt="Content Coverage Preview" />

Each cell shows how often those two Labels appear together across all Message groups.

* **Rows** represent one Component (e.g., *Offering*).
* **Columns** represent another Component (e.g., *Value Proposition*).
* **Numbers in the cells** show how many possible Alternate combinations exist between the two Labels across all Message groups where they appear together.
* **Coloured triangles** in the cells highlight *content gaps* or *content opportunities*.

<Color>
  <Color.Row title="Grey Gaps">
    <Color.Item name="Gaps- Color" />
  </Color.Row>

  <Color.Row title="Yellow Opportunities">
    <Color.Item name="gray-200" />
  </Color.Row>
</Color>

You can **hover** over a cell to view balance details and **click** a cell to see a detailed breakdown of Message groups.

<Info>
  If you see "ML" anywhere against a Label, that means that Label is applied at a Message group-level.
</Info>

## **Key Metrics**

### **Combinations**

Combinations represent the total number of possible Alternate pairings between two Labels, summed across all Message groups where those Labels appear together. This also includes Labels which are applied at a Message group-level.

The higher the number of combinations, the better. It means that there’s more variation possible within those Messages.

<img alt="Combinations" />

### **Balance**

Balance shows how evenly Alternates are distributed between the two Labels in a pair, and can be viewed by hovering over a cell.

If one Label has significantly more Alternates than the other, it indicates an opportunity to add more content for the underrepresented Label.

<img alt="Balance" />

### **Gaps**

A **gap** appears when a Message group contains fewer than three Alternates for a given Label.

These are areas where content variety is low and can benefit from adding more variations. In the grid, these are marked with an **gray triangle**.

<img alt="Gaps Pn" />

### **Opportunities**

An **opportunity** appears when both Components are used in a Message group, but only one of the selected Labels is present.

Opportunities are indicated with a **blue triangle**. These are cases where a Label combination hasn’t yet been explored — adding Alternates for the missing Label can create new combinations.

Additionally, Message groups where both Components appear but **neither** of the Labels are used are also classified as opportunities. These appear lower in the Opportunities table in the **Detail view**, and if only such opportunities exist for a Label pair, the blue triangle indicator is not shown in the grid.

<img alt="Opportunities" />

## **Blank Cells**

Blank cells represent Label pairs that haven’t yet appeared together in any Message group.

* These cells are clickable and open a **Detail view**.
* Since there are no associated Messages, only the **Opportunities** table is visible.

Instead of scanning dozens of blank cells across multiple Component-pair views, you can see the top three Label-pair blank cells with the highest potential for impact based on performance. These are indicated by shining star icons.

<Frame>
  <img alt="Blank Content Coverage" />
</Frame>

Each blank cell is scored based on how well each Label in the pair is already performing. A Label pair where both Labels drive strong performance represents a high-value opportunity: the agents have evidence that users respond to each Label individually, but you haven't given them content that combines the two. Adding Alternates unlocks new territory for the agents to explore

***

## **Detail View**

Clicking on any cell opens a detailed view showing:

* The list of **Message groups** where the selected Label pair co-occurs
* Highlighted **Gaps** (in orange) for Message groups with less than three Alternates for a Label
* Counts of Alternates and their distribution (balance)
* Table for **Opportunities**

***

## **How to Use These Insights**

* **Fill gaps** by adding more Alternates for Labels with fewer than three.
* **Explore opportunities** by adding missing Label combinations to expand message variety.
* **Use blank cells** to identify new, unexplored Label pairings that could enhance coverage.


# Experimentation in the World of Agentic Personalization
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/experiment-overview

How does experimentation change when every experience is personalized?

### Millions of Mini Experiments

Aampe performs millions of mini experiments every day. Agents learn by sharing content with users, and since there's always some randomness in message assignment, every customer touchpoint is effectively a separate experiment.

If you love experiments, this sounds wonderful. But is there a way to organize agents to run more traditional experiments? When is that a good idea instead of relying on agents to deliver custom experiences?

## A/B Testing in Aampe

A/B tests compare two or more experiences to determine which performs better. In addition to the infrastructure required to support millions of agents, Aampe's audience builder, connected channels, and message composer provide everything needed to run traditional A/B tests.

To successfully execute an A/B test, you need:

* A user randomization strategy
* Distinct user experiences to compare
* Tools for tracking and measurement

All of these are available within Aampe, but when should you run an A/B test when there are millions of agents running mini experiments?

## A/B Testing vs Agentic Personalization

There are times when traditional A/B tests may be preferable:

* **Important experiences for new users**: You may still allow agents to experiment at the individual level, but there's value in A/B testing to find the best default experience since many agents will still be in a learning phase.
* **Experiences users encounter one time**: Agents learn by trying many things and establishing patterns over time. If you're limited in the number of times you can interact with a user, an A/B test would drive more business impact than agentic personalization.
* **System-level comparisons**: When evaluating whether agentic personalization itself outperforms traditional approaches, you need controlled experiments that compare entire systems rather than individuals.

<Card title="Running Experiments with Aampe" icon="sparkles" href="/user-guide/how-do-i-know/experiments/experiment-overview">
  See what experimental methods work in the world of agentic personalization and which ones do not. A 4-part series on how to run experiments in the world of agentic personalization
</Card>


# Label Weights
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/label-weights

Influence your agents by changing label weights 

<iframe title="YouTube video player" />

## What Are Label Weights?

Label Weights let you quickly shift messaging priorities without creating new campaigns. Simply increase or decrease a label's weight to change the share of messages with that label.

Weights are particularly helpful for labels associated with product offerings, topics, or value propositions. **When business priorities shift, you can adjust content priorities accordingly.**

* **Offerings:** toggle message volume based on inventory levels, seasonality, new products
* **Value Propositions:** increase messages on 'affordability' to accompany a TV campaign
* **Topics:** security, referral programs, changes to the app or website

Agents combine label weights with each user's preferences, so users with weak preferences are more likely to be affected by a change to label weights than users with strong preferences.

## How Label Weights Work

Each message in Aampe is associated with a set of labels. Behind each label is a probability model that tracks the label's expected performance and confidence level.

An Aampe agent chooses labels by sampling from each probability model and selecting the label with the highest draw. This ensures higher-performing labels and their associated messages are selected more frequently, while still allowing Agents to occasionally explore content with other labels.

## Why Use Label Weights?

* Priorities can change quickly, and label weights allow you to quickly communicate priorities to agents.
* Label weights take immediate effect. See results without waiting for agents to learn on their own.
* Labels are flexible. They can apply to entire messages or to select variants of a message.

| **Example Goal** | **Action** |
| - | - |
| Your company wants to increase the number of users with 2FA enabled | Increase the weights for your `security` label |
| Your company has a new food line. You want to promote it. | Increase the label weight for your new food line |
| Inventory is low for a specific product category. You want to send fewer messages for that category. | Decrease the weights for any low-inventory product offerings |

## How to Change Label Weights

* In the Aampe composer, navigate to `Monitoring > Label Management`
* On the `Label overview` tab, find the table of labels and choose `Edit Relative Strength`.

  <img alt="Label Weight Menu Pn" />
* Change the Relative Strength of the Label and save.

  <img alt="Label Weights Relative Strength Pn" title="Label Weights Relative Strength Pn" />

## Label Weight FAQs

<Accordion title="Does increasing a label weight guarantee more messages with that label?" icon="sparkles">
  Increasing a label's weight will increase its chances of being featured in a message, but results may vary depending on audience size, content quality, and other label weights.
</Accordion>

<Accordion title="Will changing label weights permanently change Agent priorities?" icon="sparkles">
  Agents will make use of your Label Weights until they are removed (set to neutral). It's possible, however, that increasing a label's weight simply helps an agent learn more quickly that customers do not like content with that label.
</Accordion>

<Accordion title="What does Relative Strength of +50 mean? Is it 50% more messages?" icon="sparkles">
  Because of differences in audiences, other label weights, and content quality, it is impossible to promise a specific increase in messages for a given increase in weight. We recommend starting with modest steps, monitoring the results, and then taking larger steps as needed.
</Accordion>

<Accordion title="Will increasing the weight of a label reduce the number of messages sent to other labels?" icon="sparkles">
  By design, agents do not send every message to every person. If agents are going to send \~3 messages to each customer this week and we increase a label's weight, any increase in messages with that label will naturally crowd out messages with other labels.
</Accordion>


# Topics
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/topics

Stay organized while enjoying a strategic overview of your content

**Topics** help you organise your Message Groups according to a shared theme, user journey stage, or product feature. They give structure to your content and offer an overview of how well different features and contexts related to your business are covered.

Aampe customers use Topics to:

* Organise related Message Groups
* View how many Message Groups are allocated to a Topic

<img alt="Topic Management" />

<Info>
  Topics are not the same as Labels. Agents do not learn on Topics. Topics are only meant for internal organization of content.
</Info>

## Why Use Topics?

Imagine you have several Message Groups about your product’s Premium Plan feature — and these Message Groups are spread across 5 languages, 3 channels, and various contexts (new-user nudges, abandon flows, awareness messages, etc.). All of these can be organized under a single Topic: **Music Premium**.

<img alt="Topic2 Pn" />

This makes it easy to see, at a glance, how many Message Groups relate to a specific feature or context. It also helps reveal imbalance: even if you have 50 Message Groups, they may all be about Feature A, with none covering Features B, C, or D.

Topics can follow any convention you like. Here are some popular concepts:

* New User Onboarding
* Educational Content
* Promos & Deals
* Abandon Cart

## Create a New Topic

<img alt="Create New Topic" />

1. Go to **Monitoring → Topic Management**.
2. Click **Create Topic**.
3. Enter a **Topic name** and, optionally, a **description**.
4. Select any related **Message Groups** and **Events** (these can be edited later).
5. Click **Save** to create the Topic.

Your new Topic will now appear in the grid and can be edited at any time.

## **Add Message Groups to Topics**

<img alt="Add Message Group To Topic" />

There are multiple ways to assign Message Groups to Topics:

* **During Message Group creation**: Select a Topic while setting up the new Message Group
* **When editing a Message Group**: Update the Topic selection from the Message Group setup view
* **Messages tables**: Select one or more Messages and the **Assign to a topic** option will appear
* **From Topic Management**: Add Message Groups directly from the Topic Management list or the Topic details page

<Info>
  You can change Topic assignments for a message at any time.
</Info>

## **View Topic Details**

<img alt="View Topic Details" />

To view the details of a Topic:

1. Go to **Monitoring → Topic Management**.
2. Click on any Topic.

The Topic details page displays:

* **Related Message Groups**
* **Related Events**
* **Labels** that are being used in the related Message Groups

From this page, you can:

* Add or remove Message Groups
* Move Message Groups to another Topic
* Edit the Topic name or description

## **Grouping by Topic in Messages**

<img alt="Group By Topic" />

The **Messages** section allows you to view Message Groups grouped by Topic.

You can also apply filters, such as **Audience**, to refine how coverage is displayed and better understand which areas need more content.

This helps teams quickly identify where Message Groups cluster and where gaps may exist.


# Topics vs Tags
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/topics-vs-tags

Understand when to use Topics versus Tags in Composer.

**Topics** and **Tags** are both organizational tools in Composer. \
**Neither should be confused with Aampe Labels.**

**Topics** help you organize Message Groups according to a shared theme, user journey stage, product feature, or content-map category. Composer has a dedicated Topic Management area where you can create Topics, view related Message Groups, add or remove Message Groups, and edit Topic names or descriptions.

The important difference is that **Topics are managed content groups**, while **Tags are filterable markers**. Examples:

| **Topic** | **What belongs inside it** |
| :- | :- |
| New User Onboarding | Message Groups that help new users understand the product and take first actions |
| Browse Abandonment | Message Groups that bring users back after browsing without continuing |
| Premium Plan | Message Groups that explain or promote paid-plan value |
| Payment Failure | Message Groups related to failed payments, retries, and account recovery |

**Tags** are organizational markers that help teams filter, isolate, or report on sets of Message Groups. A Message Group can have multiple Tags. Tags are useful for sorting and filtering, but they do not provide the same managed grouping experience as Topics.

Examples:

| **Tag** | **What it may be used for** |
| :- | :- |
| Indonesia | Identifying content for a specific country or team |
| Podcast | Identifying messages tied to a vertical or product area |
| Seasonal | Identifying seasonal content |
| Needs Review | Identifying content that needs cleanup |

> *Important: Tags are not Labels. Tags are organizational markers. Labels are a separate Aampe concept and should not be used as another word for Tags.*

## **The Short Rule**

Use **Topics** when you want a clear, managed way to group Message Groups by content area.

Use **Tags** when you need filterable markers across Message Groups, especially for reporting, operational review, team ownership, country, language, or vertical.

If you are creating a durable content structure from scratch, start with Topics.

## **Key Differences**

| **Capability** | **Topics** | **Tags** |
| :- | :- | :- |
| Purpose | Group related Message Groups into a managed content structure | Mark Message Groups so they can be filtered or isolated |
| Selection | One Message Group can belong to one Topic | One Message Group can have multiple Tags |
| Dedicated management area | Yes, Topic Management | No full tag management surface |
| Can edit the organizing object | Yes, Topic names and descriptions can be edited | Tag names are not currently editable after creation |
| Can delete unused/mistake values self-serve | Topic deletion exists, with Message Groups moved to No Topic | No full self-serve tag cleanup/management flow |
| Best for | Content maps, lifecycle stages, product areas, customer situations | Team ownership, country/language, verticals, temporary reporting needs |
| Customer value | See how content is grouped and where coverage gaps exist | Filter or isolate tagged content in current views |

## **Why This Matters**

Topics and Tags can both help organize content, but they answer different questions.

Topics answer:

> *"What content area does this Message Group belong to?"*

Tags answer:

> *"What marker do I need to filter or identify this Message Group by?"*

Tags were being used heavily before Topics because customers needed some way to sort and isolate content. For example, teams used Tags for countries, teams, verticals, languages, or reporting views. That is useful, but Tags are open-ended and can become inconsistent quickly.

Topics were introduced because Tags did not give customers a meaningful way to understand how many Message Groups existed against a content map, theme, product feature, or customer journey stage.

## **When to Use Topics**

Use Topics when the grouping should be durable and visible as part of your content strategy.

Good Topic use cases:

| **Use case** | **Example Topic** |
| :- | :- |
| Lifecycle stage | New User Onboarding, Winback, Retention |
| Customer situation | Browse Abandonment, Payment Failure, Trial Ending |
| Product area | Premium Plan, Referrals, Wallet |
| Content map category | Activation, Education, Conversion |
| Major recurring business motion | Renewal, Upgrade, Cross-sell |

Topics are especially useful when your team wants to answer:

| **Question** | **Why Topics help** |
| :- | :- |
| Do we have enough content for this journey stage? | Message Groups can be reviewed together by Topic |
| Which areas of our content map are missing in Composer? | Topics can mirror your content map |
| Which Message Groups are still uncategorized? | The No Topic folder makes gaps visible |
| Do we need to rename or reorganize a category later? | Topics can be managed after creation |

## **When to Use Tags**

Use Tags when you need a filterable marker, not a managed content group.

Good Tag use cases:

| **Use case** | **Example Tag** |
| :- | :- |
| Identify team or country ownership | Indonesia, Thailand, Growth Team |
| Identify a vertical for filtering or reporting | Podcast, Ride Hailing, Grocery |
| Mark a language or localization grouping | English, Bahasa, French |
| Mark an operational state | Needs Review, Migration Batch 1 |
| Add a temporary reporting marker | Q2 Promo, Holiday 2026 |

Tags are useful when a Message Group needs multiple markers at the same time. For example, a Message Group could be tagged with a country, vertical, and cleanup status.

Use Tags carefully because the tag list itself is not yet easy to manage. If teams create similar Tags such as Promo, Promotion, Discount, and Discounts, the account becomes harder to filter and audit.

## **How to Decide**

Use this decision table when setting up or cleaning up content.

| **If you are trying to...** | **Use** | **Why** |
| :- | :- | :- |
| Build a new content organization system | Topic | Topics are managed and visible in Topic Management |
| Mirror a content map or lifecycle journey | Topic | Topics are better for durable structure |
| Organize Message Groups by product area | Topic | Product areas usually need ongoing management |
| Group content by customer situation | Topic | Customer situations are durable enough to manage |
| Understand whether content coverage is broad or narrow | Topic | Topics show where Message Groups cluster |
| Filter messages by country, team, language, or vertical | Tag | Tags are useful filter markers |
| Add multiple markers to a Message Group | Tag | A Message Group can have multiple Tags |
| Mark content for cleanup or migration | Tag | Tags can support lightweight operational workflows |
| Rename or govern the organizing structure over time | Topic | Tags are harder to manage once created |

## **Examples**

### **Example 1: Premium Plan**

A subscription app has many Message Groups about its paid plan. Some are onboarding nudges, some are upgrade prompts, and some explain premium features.

Use a Topic for the durable content area:

| **Field** | **Value** |
| :- | :- |
| Topic | Premium Plan |

Use Tags only for filterable markers:

| **Field** | **Example values** |
| :- | :- |
| Tags | English, Growth Team, Needs Review |

The Topic shows that the Message Group belongs to the Premium Plan content area. The Tags help the team filter by language, ownership, or operational status.

### **Example 2: Country or Team Organization**

A regional customer has multiple teams or countries managing content. They may need to isolate content by country in result pages or message overview pages.

Use Tags for those markers:

| **Field** | **Example values** |
| :- | :- |
| Tags | Indonesia, Thailand, Vietnam |

Do not use separate Topics for every country unless country is the actual content strategy. If the content strategy is about user journeys or product features, keep those as Topics and use country as a Tag.

### **Example 3: Product Vertical**

A customer wants to see sends for a particular vertical, such as podcast content or grocery content.

If the vertical is a durable product/content area, it may be a Topic:

| **Field** | **Value** |
| :- | :- |
| Topic | Podcast |

If the vertical is mainly needed for filtering or reporting across several Topics, use it as a Tag:

| **Field** | **Value** |
| :- | :- |
| Tag | Podcast |

When in doubt, ask: "Do we need to manage this as a content group, or just filter by it?"

### **Example 4: Same Message Across Languages**

If the same Message Group exists across several languages, do not rely only on Tags to make that structure understandable.

Use a Topic for the content theme:

| **Field** | **Value** |
| :- | :- |
| Topic | New User Onboarding |

Use Tags for the language markers:

| **Field** | **Example values** |
| :- | :- |
| Tags | English, French, Bahasa |

This makes the content theme visible while still allowing language-level filtering.

## **Do's and Don'ts**

| **Do** | **Don't** |
| :- | :- |
| Use Topics for primary Message Group organization. | Do not use Tags as a substitute for a content map. |
| Use Topic Management to create, review, and edit content categories. | Do not expect Tags to provide the same managed grouping experience. |
| Use Tags for filterable markers like country, team, language, vertical, or review status. | Do not create many near-duplicate Tags with similar meanings. |
| Keep Tag naming consistent. | Do not create Tags casually; cleanup is harder later. |
| Use multiple Tags when a Message Group needs multiple markers. | Do not treat Topics as multi-select; one Message Group belongs to one Topic. |
| Keep Tags and Labels separate in your vocabulary. | Do not call Tags Labels. |

***

## Common Customer Questions

### Can one Message Group have multiple Tags?

Yes. A Message Group can have multiple Tags.

### Can one Message Group belong to multiple Topics?

No. One Message Group can be related to one Topic. A Topic can have many Message Groups.

### Do Topics affect which messages agents send?

No. Topics are organizational. They help your team group and review related Message Groups, but agents do not learn on Topics.

### Do Tags affect which messages agents send?

Treat Tags as organizational and filterable markers. Do not assume that adding a Tag changes send logic, targeting, frequency, or agent decisions.

### Are Tags and Labels the same thing?

No. This is an important distinction.

Tags are organizational markers used for filtering and identifying Message Groups.

Labels are a separate Aampe concept.

Do not use "Tag" and "Label" interchangeably. If you are unsure which one your team is looking at, ask your Customer Success contact before making bulk changes.

### Should Topics replace Tags?

Topics should replace Tags as the main way to organize content by theme, journey stage, product area, or content-map category.

Tags are still useful for filtering and reporting markers such as country, team, language, vertical, migration batch, or review status.

### What if our team already has many Tags?

Do not keep expanding the Tag list without a naming convention. First, identify which Tags are actually durable content categories. Those are usually better represented as Topics.

Then review the remaining Tags separately. Keep Tags that are useful for filtering or reporting, and avoid creating duplicates with slightly different names.

### Can we edit or delete Tags?

Tag management is limited. Current guidance from internal product notes is that customers have needed a better way to view all available Tags, edit Tags, and delete unused or mistaken Tags. If your account needs Tag cleanup, ask your Customer Success contact for the current support path.

### When should we ask Aampe for help?

| Situation | Why help is useful |
| - | - |
| You have a large existing message library | Aampe can help map old content into a cleaner Topic structure |
| Your Tags and Topics overlap | Aampe can help decide what should become a Topic |
| You have many duplicate or unclear Tags | Tag cleanup needs care because tag management is limited |
| You are unsure whether a term is a Tag or a Label | Aampe can confirm before you make bulk changes |


# Working With Agents
Source: https://kb.aampe.com/user-guide/managing-agents-strategically/working-with-agents

Content is live. Now what? 

## Manage Priorities

Priorities can change quickly. How do you keep your agentic workforce aligned? \
\
[Label weights](/user-guide/managing-agents-strategically/label-weights) allow you to increase or decrease the likelihood that a given label will be selected for message creation. Agents still consider individual preferences, so content is still balanced between what is relevant for the user and your priorities.

## Monitor Results

Log into Aampe regularly to keep an eye on the number of daily messages and recipients. You can also examine how labels interact with each of your audiences and discover new insights about your customers. Aampe can also share user and event-level data back to your data warehouse so you can build your own reports.\
\
[Read more about Aampe's analytics and data tools](/user-guide/how-do-i-know/analytics/analytics-overview).

## Curate Content

Agents thrive on a vast and varied corpus of content, but volume is not the only play. Once your content map is complete, there are regular decisions to make about what content to add, remove, or update.

## Run Experiments

While each agent automatically runs many little experiments, Aampe's infrastructure is also useful for running large A/B tests. With Aampe's audience builder and a little random assignment, you can create distinctly different experiences for similar audiences to learn which experience is best.

* How does email-only compare to push-only for reactivation?
* How do I compare agentic personalization vs a rules-based system?

[See our notes on how to successfully run experiments using Aampe's infrastructure](/user-guide/how-do-i-know/experiments/experiment-overview).

## Content FAQs

<Accordion title="How can I prioritize one set of messages over another?" icon="sparkles">
  You can use [label weights](/user-guide/managing-agents-strategically/label-weights) to increase or decrease the likelihood of agents choosing a given message.
</Accordion>


# User Guide
Source: https://kb.aampe.com/user-guide/user-guide

Resources for CRM and product professionals, Aampe administrators, analysts, etc.

<CardGroup>
  <Card title="Quick Start" icon="play" href="/user-guide/using-aampe/quickstart/overview">
    New to Aampe? We've got you covered.
  </Card>

  <Card title="Account Management" icon="user" href="/user-guide/using-aampe/admin/users-and-roles">
    Add users to Aampe, manage roles
  </Card>

  <Card title="Sending Messages" icon="pen" href="/user-guide/using-aampe/quickstart/quickstart-messages">
    Ready to go? Let's set up your first message.
  </Card>

  <Card title="Create an Audience" icon="people" href="/user-guide/using-aampe/audiences/audiences">
    Determine which users are eligible for which content
  </Card>

  <Card title="Product Surfaces" icon="tablet" href="/user-guide/using-aampe/quickstart/quickstart-surfaces">
    Bring 1:1 personalization to your app or website
  </Card>

  <Card title="Key Settings" icon="dial" href="/user-guide/using-aampe/admin/frequency-limits">
    Message limits, languages, and more...
  </Card>
</CardGroup>

### Featured Pages

* [Figma Surface Creator](/user-guide/using-aampe/tools/figma-plugin)
* [AamPT](/user-guide/using-aampe/tools/aampt)


# Agent-User Allocation
Source: https://kb.aampe.com/user-guide/using-aampe/admin/agent-user-allocation

For customers with a limited number of agents

Customers who have more users than agents often ask the following questions:

1. **Which users should we include in our data integration?**
2. **How should we allocate agents across our users?**
3. **Are experimental holdouts included in our agent headcount?**

This guide provides our recommendations to help these customers use Aampe most successfully.

## Which Users Should We Include in Our Data Integration?

We find that customers have the best results when they...

* Send **all** customer info to Aampe (users, events, etc.)
* Use **Aampe audiences** to manage the total number of addressable users

### Why We Usually Recommend This Approach

This approach offers several advantages:

* **Dynamic users**:  Having extra users available within Aampe makes it easy to pull in new users when other users naturally exit.
* **Easier maintenance**: Priorities change! Aampe customers with limited agents often want to try agentic personalization on different subsets of their customer base. This is much easier to do when audience logic lives in Aampe.

### Keeping Audiences Consistent Across Tools

One important consideration is how Aampe and its audiences interact with other tools.

When other tools need to know which users are eligible for Aampe, it can still make sense to send the full customer base to Aampe. Message eligibility, however, would be managed outside of Aampe and passed to Aampe via a user attribute.

## How Should We Allocate Agents Across Our Users?

Users receive an Agent as soon as they are eligible to receive messages. \
\
The best way to manage an Aampe-eligible subset of users depends on what you're hoping to accomplish. Here are our recommendations based on different scenarios:

* **If you have specific user segments in mind:**  You can easily limit Aampe-eligible users using Aampe's audience builder. You can even pass in a group identifier as a user attribute.
* **If you're unsure where agents can be most effective:** We suggest starting with a comprehensive cross-section of users. Aampe has proven effective across diverse user segments:
  * New users just getting started
  * Long-time, established users
  * Highly engaged active users
  * Inactive or dormant customers

Each Aampe customer is different. This broad approach will help you discover where agents can deliver the most value for your specific situation.

## Are experimental holdouts included in our agent headcount?

Many customers will occasionally hold out a subset of users for measurement purposes. Users in a control group will not receive messages, but they still have an agent assigned.

* Agents in the control group will still monitor customer actions, message eligibility, and take action to *assign* messages. They will not, however, *deliver* any messages.
* This gives us a detailed history of all the messages a user *would have received*, but did not due to being in the control group.

This setup allows us to conduct the cleanest possible measurement between treatment and control groups when the treatment varies across individuals.

## Questions?

If you have additional questions about agent allocation strategies, please connect with the Aampe team. Situations vary from customer to customer and we're here to help you find the best path forward.


# Event Funnel
Source: https://kb.aampe.com/user-guide/using-aampe/admin/define-funnel-events

Funnel event classification will keep all those charts nice and tidy

## Setting up your Event Funnel

Complete the following steps to set up your event funnel.

### Step 1: Import Relevant Events

1. After your data integration is complete, go to **System setup > Event management** in the left navigation.
2. Review the list of all available events. Make sure nothing is missing and all events are properly flattened (if needed).

### Step 2: Classify Funnel Events

Once imported, use the dropdown next to each event to designate the right event category. These categories allow Aampe to aggregate events more sensibly in any [reporting](user-guide/how-do-i-know/analytics/composer-analytics.mdx).

<img alt="Funnel Menu2 Pn" />

You can assign multiple events to the same classification type.

### Step 3: Check Reports

The reports found under the **Monitoring** tab will reflect the funnel groupings.


# Event Types
Source: https://kb.aampe.com/user-guide/using-aampe/admin/event-types

Which events are good? Which events are bad? You be the judge!

## What Are Event Types?

Agents do their best work when they have access to a rich, diverse event stream. But with so many events, agents need guidance to understand which events are good, bad, or simply not worth paying attention to.

**Event Types** solve this problem. They’re a setting in the Aampe Composer that lets you label events as positive, negative, or irrelevant. This way agents know what matters most to your business.

## How Event Types Work

Each action in a user’s event feed has a numeric reward value that tells agents how valuable that action is to your business.

* Some events are important and deserve **larger positive rewards**.
* Some events are harmful and deserve **negative rewards**.
* Others are unimportant and deserve **no reward at all**.

Agents measure the impact of their decisions by looking for sudden, meaningful changes in the **total reward** of events before and after a message is sent.

While agents can calculate reward totals automatically, they need your guidance to know whether an event is good, bad, or irrelevant in the first place.

## Configuring Event Rewards in the Aampe Composer

* In the Aampe Composer, navigate to `System setup > Event management`
* Select an event and click on its `Type` (you can also select multiple events using the checkbox)
* Select the appropriate event type for your chosen events and confirm your choice
* New events appear under **Uncategorized events**

  <Frame>
    <img alt="Event Type Selection" />
  </Frame>

  <img alt="Event Type Menu Pn" />

### **Available Event Types**

* **Positive events**\
  Examples: Opening the app, adding to cart, streaming content, leaving a review
  * Should be a **voluntary action taken by the user**
  * Receive positive rewards

* **Negative events**\
  Examples: Unsubscribes, order cancellations
  * Also must be **voluntary actions taken by the user**
  * Receive negative rewards

* **Irrelevant events**\
  Examples: System-generated events, involuntary events, scheduled events
  * Not used to evaluate the success of a message
  * Still useful for building audiences and triggering messages

<Info>
  A good rule of thumb for whether an event is irrelevant is, "Is this event for customer A the result of a decision made by Customer A?" If yes, the event is likely relevant and helpful for your agents. \
  \
  **Examples of an irrelevant event:**

  * Customer A receives a friend request from Customer B  (relevant for Customer B, but irrelevant for Customer A).
  * Customer A is automatically unenrolled from their subscription after 2 years of inactivity.
</Info>

## Event Type FAQs

<Accordion title="Will changing an event's type confuse agents?" icon="sparkles">
  No. Moving forward, agents will treat those events differently when measuring the success of a message.
</Accordion>

<Accordion title="Where do new events appear?" icon="sparkles">
  New events appear under the **Uncategorized event** tab. Agents do not include these events when evaluating message success.
</Accordion>

<Accordion title="How should I categorize small events like clicks?" icon="sparkles">
  Generally speaking, clicks and other high-volume, low-intent events are great positive events.
</Accordion>

<Accordion title="Sometimes an event is relevant to one message and not another. Shouldn't events have higher values for those relevant messages?" icon="sparkles">
  We agree. If a message is about your referral program, agents should give full marks for referral events. Other positive events should receive partial credit.

  As is, Aampe has one numeric value for each event and it is the same for all messages. But stay tuned: soon agents will be able to customise event rewards on a per-message basis
</Accordion>


# Frequency
Source: https://kb.aampe.com/user-guide/using-aampe/admin/frequency-limits

How many messages are too many? 

<iframe title="YouTube video player" />

## Setting Messaging Frequency

Aampe is designed to avoid spamming your users. Your agents are trained to send fewer, smarter messages that actually drive results. Many Aampe customers find their agents deliver better performance than traditional tools while sending significantly fewer messages overall.

Before any message is sent, your agents assess whether it will meaningfully increase the probability of a user taking the desired action. If the answer is no, the message is not sent.

That said, we know that some teams need to enforce additional guardrails. To support that, Aampe allows you to define **frequency limits** for how many messages users can receive in a given week.

### How to Set Messaging Frequency

1. Go to **Configure > Frequency Limits** in the left-side navigation
2. Click **Edit** next to any trigger
3. Set the **maximum number of messages per week** for that trigger
4. Click **Save**

> Your changes will take effect the following day.

### How Frequency Limits Work

Frequency limits are defined **per trigger**. This gives you granular control over messaging volume based on user behavior.

* If a user has **not qualified** for any trigger, only the \*\*"No Trigger"\*\* frequency limit applies.
* If a user has **qualified** for one or more triggers, they may receive:
  * Up to the max number of messages set under **"No Trigger"**
  * Plus, the max number of messages for **each trigger** they qualify for

<Info>
  Example: If you set a "No Trigger" limit of 5 messages per week, and a "Cart Abandonment" trigger limit of 4 messages per week, a user who qualifies for the Cart Abandonment trigger could receive up to 9 messages in total that week.
</Info>

<img alt="Scheduling With Guardrails Pn" />

### Keep in Mind

These are **upper bounds**, not quotas. Just because a user could receive that many messages doesn't mean they will.

Your agents still determine the **optimal** messaging frequency for each user, which is often well below the defined maximums—especially if higher volumes would not increase the likelihood of conversion.

## FAQ - Message Frequency Settings

<Accordion title="Will Aampe override the frequency caps set in my message delivery tool?">
  Only if you want it to. For select message providers, we have an option to override the delivery-layer settings. The option is unselected by default. 

  <Frame>
    <img alt="Delivery Provider Override" />
  </Frame>
</Accordion>

<Accordion title="Where can I monitor message frequency?">
  You can track detailed trends of messages-per-user each week in the [Frequency Tracker](/user-guide/how-do-i-know/analytics/composer-analytics).
</Accordion>


# Managing Content in Multiple Languages
Source: https://kb.aampe.com/user-guide/using-aampe/admin/languages

Fun fact - there are over 7,000 living languages spoken around the world today

<iframe title="YouTube video player" />


# Account and User Management
Source: https://kb.aampe.com/user-guide/using-aampe/admin/users-and-roles

Add users and manage roles

## Adding Users

To add a user to Aampe:

* `System Settings > Account members`
* Select the `Invite User` button
* Provide the user’s email and role

If needed, see the developer guide for [instructions on setting up SSO](/developer-guide/sso/setting-up-sso).

## User Roles and Permissions

Aampe provides several roles to ensure each user can contribute within appropriate limits.

### Admin

Admins can modify any account setting and have full content permissions. They can:

* Add/remove other Aampe users
* Change roles of other Aampe users
* Create new content
* Edit, archive, unarchive, and delete all content
* Share content with Editors
* Manage account settings
* Manage integrations

### Manager

Managers have full content permissions. They can:

* Create new content
* Edit, archive, and unarchive all content
* Share content with Editors

### Editor

Editors have limited content permissions. They can:

* Create new content
* Edit select content when granted access

To share content with other Editors, click the `share` icon and select the desired user. The following content types can be shared:

* Messages
* Surfaces
* Audiences
* Triggers
* Datasets
* Templates

### Reader

Readers can view all Aampe dashboards and content, but cannot edit content or account settings.

## Role and Permission Summary

| | Add/Remove Users | Change a User's Role | Add Content | Delete Content | Edit Content | Share Content | View All Content |
| :- | :- | :- | :- | :- | :- | :- | :- |
| Admin | x | x | x | x | All | All | x |
| Manager | | | x | | All | All | x |
| Editor | | | x | | Some | Some | x |
| Reader | | | | | None | None | x |


# Audiences
Source: https://kb.aampe.com/user-guide/using-aampe/audiences/audiences

Audiences define which users are eligible for which messages

<iframe title="YouTube video player" />

## What are Audiences?

Audiences in Aampe define who is eligible to receive a message based on user attributes. Unlike triggers, which are tied to specific user actions and events, audiences focus on stable or slowly changing characteristics, like language, region, or other data you send to Aampe.

Your agents use audiences as one of the starting points to decide which messages to consider for a user but also as guardrails. Importantly, attaching an audience to a message doesn’t guarantee delivery to all users in that audience. Agents still make the final decision on a per-user basis—whether to send the message at all, based on timing, behavior, and relevance. Think of the audience as an eligibility filter, not a send list.

Use audiences when you want to:

* Localize content (e.g., only send French messages to French-speaking users)
* Separate messaging by platform (iOS vs Android)

<img alt="Audiences Web" />

## How to Create an Audience

### Create a New Audience

1. Go to the Audiences tab in the left-hand navigation.
2. Click the + Create Audience button in the top-right corner.
3. Name your audience.
4. Click + Add New Filter to define the criteria (e.g., language = fr, platform = iOS).

### Live Audience Size Preview

As you add filters, Aampe will show you the total number of users who match that audience in real time, along with the percentage of your total user base.

### Sample User IDs

You want to cross-check if users you would expect to be in this audience are present? Click on the ellipsis (the three dots) and on "Sample user IDs." This will give you a list of random user IDs.

## Can't Find the Attributes You Need?

When you're just getting started with Aampe, not all user attributes are visible by default in the audience builder. This is intentional—to keep your experience focused and avoid cluttering filter menus with unnecessary options.

If you're missing an attribute you'd like to use:

* Go to System Setup > Attributes
* Activate the attributes you want to make available in your filters

Once activated, these attributes will appear in the audience filter dropdowns.

## How to Attach Audiences to a Message

There are two ways to target a specific audience with a message:

### Option 1: Start from the Audience Page

1. On your newly created audience's page, select it from the dropdown.
2. Click the + Create Message button at the bottom of the screen.

### Option 2: Assign Audience When Composing a Message

1. Start a new message in the Message Composer.
2. On the setup page, open the Audience dropdown and select your desired audience.

## Audience Best Practices

* **Keep it simple:** Start with broader audiences and refine as needed. Overly specific audiences can limit your reach.
* **Use meaningful names:** Name audiences clearly so their purpose is immediately obvious to anyone on your team.
* **Consider overlap:** Be aware that users can belong to multiple audiences. Design your audiences with this in mind.
* **Review regularly:** As your user base evolves, revisit your audience definitions to ensure they remain relevant.

<Tip>
  For maximum flexibility, consider creating a set of "base" audiences for common segmentation needs (language, platform, etc.) and then more specific audiences for targeted campaigns. This modular approach makes it easier to mix and match audience criteria as needed.
</Tip>


# Message Triggers
Source: https://kb.aampe.com/user-guide/using-aampe/audiences/triggers



## What Are Triggers?

In Aampe, triggers act as eligibility signals—they tell our AI agents which users could potentially receive a message, based on actions those users have taken. But unlike traditional systems where a trigger might immediately send a message, our agentic AI takes a more strategic approach.

Once a user qualifies for a trigger, the AI agent uses it as a guardrail, not a direct instruction. This allows the agent to decide the right moment to deliver a message within a relevant window, balancing timing, context, and message effectiveness.

## Trigger Types

We support three types of triggers:

**1. Aampe Trigger (Optimized Eligibility Window)**\
This trigger type functions like a dynamic audience filter based on events. If a user completes a specified event within a set timeframe (e.g., "purchased in the last 7 days"), they become eligible for the message.\
\
The AI agent then determines the best time to send it within that 7-day window, optimizing for maximum impact.\
\
**2. Real-Time Trigger**\
This is an immediate trigger, so a webhook is used to send the message as soon as the event occurs.\
\
It is useful when the timing of the message is critical—e.g., when confirming a booking, reacting to a major user action, or providing instant feedback.\
\
**3. Real-Time with Delay**\
Like the real-time trigger, this also uses a webhook but allows you to configure a delay, such as sending the message one day after the event.\
\
This is useful when you want to follow up on a real-time action, but not immediately, giving the user some space before messaging.

## Exit Events

Within any trigger, you can define one or more exit events. Users who complete an exit event immediately become ineligible for that trigger and any messages attached to it.\
\
This helps prevent irrelevant messaging, for example, if a user completes a purchase after entering a cart-abandonment trigger, you can set "Purchase Complete" as an exit event to stop further nudges.

## Trigger Configuration

<img alt="Triggers Web" />

<img alt="Triggers App Installed Web" />

## Using Triggers

Triggers let you send messages only after a user completes a specific action, such as making a purchase, completing onboarding, or finishing a level in your app.

This helps you send the right message to the right user at the right time.

<Warning>
  **Don’t Overuse Triggers!**\
  A common mistake is over-constraining your messages with too many triggers. Triggers limit the pool of messages your agents can choose from.
</Warning>

**Example:**

If you have 500 total messages, but 250 of them require a “purchase complete” trigger, then users who haven’t purchased anything will only see the other 250. That limits your reach and results.

Before adding a trigger to any message, ask yourself:

*“Does this message really need a trigger, or can it go to all users?”*

You might be surprised how many messages work without one!

## How to Set Up a Trigger

1. Go to **Configure > Triggers** in the left-hand menu.
2. Click the **+ Create** button.
3. Select the trigger type. *(If the real-time trigger is greyed out, please contact us to set it up for you.)*
4. Choose an event and an operator to define your condition:

   \== — Equals (e.g., Purchase\_Complete == 0 means no purchase made)

   != — Not equal to

   \> — Greater than (e.g., more than 1 purchase)

   \>= — Greater than or equal to

   \< — Less than

   \<= — Less than or equal to
5. Set a time window for when the event should have occurred.
6. *(Optional)* Add more conditions using the **+ Add** button.
7. Set an exit condition *(optional)*:

   By default, users exit once all trigger-linked messages are sent.

   You can also add exit events (e.g., Purchase\_Complete >= 1) to stop the trigger once the user takes that action.
8. Name your trigger and hit **Save**.

## How to Use a Trigger in a Message

1. Open the **Message Composer**.
2. Start a new message or open an existing one.
3. At the top, click the **Trigger** box (it will say **None** if no trigger is set).
4. Select the trigger you created and click **Save**.

## Important Notes About Triggers

**Aampe Optimized Triggers ≠ Guaranteed Delivery**

Even if a user matches a trigger, it doesn’t mean the message will be sent. Your agents choose the best message for that user based on what is most likely to drive conversion.

**That’s a good thing!**

Users often qualify for multiple messages. Your agents pick the highest-impact message of all eligible messages and send them at the optimal time.

**Real-time Trigger** and **Real-time with Delay** = **Delivery Guaranteed**

These work like the event triggers you’re familiar with. Once the event occurs, the message is triggered.


# Creating Custom Components
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/custom-components

Sometimes you want something other than 'other'

<iframe title="YouTube video player" />


# Email Best Practices for Agent Learning
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/email/best-practices



How to write, structure, and configure emails so Aampe's agents can learn and personalize effectively.

***

## Differences between existing email content vs Aampe email

Aampe's content model is fundamentally different from what any generic email builder understands:

<Info>
  **Building a regular Email**

  Template **→** Add Content and Merge Tags **→** Send
</Info>

<Callout icon="mailbox-flag-up">
  **Building a Aampe Email**

  Template **→** Fields **→** fill with Components × Labels × Alternates **→ Agent Learning Enabled 🤖**
</Callout>

***

## How Agents Learn from Emails

Aampe's reinforcement learning agents don't just send emails — they learn from every interaction. In this context, an interaction means the agent putting labeled content in front of a user, whether that's through email, push, or an in-app surface. Opens, clicks, and similar behaviors are signals that help the agent learn from those interactions over time. As those signals accumulate, agents discover each user's preferences across value propositions, tones, offerings, and calls to action, then use those preferences to assemble the most effective message for each person.

For this to work, agents need **material to experiment with**. If every email says the same thing in the same way, there's nothing to learn. The more varied and well-structured your email content is, the faster agents learn and the better your results.

***

## The Golden Rule: Coverage Over Volume

The single most important principle for agent learning is **coverage**, not message volume. Coverage means having content that spans the full range of things your users might care about.

Think of it this way: agents don't change user behavior — they *discover* it. If a user isn't in the market to buy something right now, it doesn't matter how many "buy now" emails you have. But if you also have content about new features, tips and tricks, community stories, or educational material, the agent can find something that resonates, keep the user engaged, and set the stage for conversion when the moment is right.

Your **Strategy Map** defines all the things a user could be in-market for. You need at least some content for most of those rows, because that's what allows agents to meet users where they are.

**What this means practically:**

* If your Content Map has 80 rows and you've implemented content for 10 of them, adding more alternates to those 10 won't help nearly as much as covering 30–40 rows with even basic content.
* A customer with 200 messages concentrated on a single topic can still have 49% of users receiving nothing that resonates, because coverage was only 10% of the product.
* Even if you're optimizing for a specific business outcome (like purchases), agents need diverse content to learn the indirect paths that lead to that outcome.

***

## Structuring Email Content for Agents

### Components: The Building Blocks

An email in Aampe is built from **components** — distinct sections of the email that agents can mix and match. Common email sections include:

* **Subject line** — the first thing users see; high-impact for open rates
* **Pre-header** — the preview text shown alongside the subject line in the inbox
* **Email title / headline** — the main heading inside the email body
* **Body text** — the core message content
* **Call to action (CTA)** — the button or link driving the desired action
* **Offering** — the product, feature, or benefit being highlighted

Make as many sections of your email with agentic fields as possible to enable your agents to learn upon.

<Info>
  Prioritize **Value Proposition** and **Offering** components over structural ones like Greeting and CTA. Agents learn the most from semantic components the *what* and *why* of your message rather than structural ones like `**"Hi {first-name}"**` or "Click here."
</Info>

### Labels: What Agents Actually Learn On

**Labels are the core of agent learning.** They're the categories that tell the agent *what kind* of content an alternate represents. When an agent learns that a user prefers "social proof" over "financial benefit" as a value proposition, it's learning at the label level.

Common label types include:

* **Value Proposition labels:** Social Proof, Convenience, Savings, Reliability, Trust, Exclusivity
* **Offering labels:** Feature-specific labels tied to your product (e.g., "Group Ride," "Document Manager," "Mobile Pay")
* **Tone labels:** Direct, Motivational, Reassuring, Enthusiastic, Encouraging
* **CTA labels:** Soft (Learn more), Direct (Buy now), Urgent (Don't miss out)

**Key guidelines for labels:**

* Use **all available labels** (or as many as possible) for every component in an email. If you have 6 value proposition labels, each email message should ideally have alternates for all 6, not just 2 or 3.
* Every label is a hypothesis. If a component has only one label, the agent can't learn preferences for that component — there's nothing to compare against.
* If a label has too few alternates, users who prefer that label won't receive the message again because agents protect against redundant experiences.

### Alternates: Giving Agents Options

Alternates are the different versions of copy within a component, tagged with labels. They're what the agent actually selects from when assembling a message.

**The rule of thumb: aim for at least 3 alternates per label per component within each message group.**

Why 3? With fewer, agents don't have enough variety to prevent repetitive experiences. With significantly more (say 10+ per label while another label has only 1), the imbalance can skew learning.

Keep your alternates **balanced across labels.** Don't create 10 alternates for one label and 1 for another — this creates uneven learning and means the agent over-indexes on the well-represented label.

***

## Email-Specific Best Practices

### 1. Keep Component Count Manageable

Emails are more complex than push notifications because they have more sections & opportunities for personalization. But more components means exponentially more combinations, and agents need enough interactions to learn patterns across all of them.

**Recommended approach:**

* Aim for **3 to 5 components** per email message. This is the sweet spot for meaningful learning.
* If your email has many sections (e.g., header, intro, 3 product blocks, footer), consider which sections truly benefit from personalization and which can stay static.
* Each label is a hypothesis, and each message is an experiment. The more complex the experiment, the higher the chance agents measure noise instead of signal.

### 2. Use Component Locking

When your email has repeating sections (e.g., three product recommendation blocks), use **label locking** to ensure label consistency across them. Without locking, agents might pair a "luxury" focused headline with a "budget savings" body copy creating a disjointed experience.

Component locking ensures that when the agent selects a label for one section, matching sections use the same label, keeping the email coherent.

### 3. Make Subject Lines and Pre-headers Dynamic

Subject lines and pre-headers are the highest-impact components of an email because they determine whether the email gets opened at all. Make both dynamic with labeled alternates so agents can learn what drives opens for different users.

* Create subject line alternates that vary by value proposition and tone.
* Pair pre-headers with subject lines thoughtfully, they should complement, not repeat.

### 4. Preserve Your Template's Technical Elements

When importing HTML templates, make sure to preserve:

* **Tracking parameters** on all URLs (UTM tags, session IDs)
* **Conditional logic** from your ESP (Braze liquid tags, Customer.io conditionals)
* **Content blocks** (footers, unsubscribe links, compliance text)
* **Image query strings** (cache-busting parameters, resize specifications)

These elements are essential for deliverability, compliance, and analytics. Use the [Email Configurator](https://apps.aampe.com/email-config) to set up your templates while preserving these technical details.

### 5. Handle ESP Variables Separately

Your email templates likely contain variables from your ESP (like `{{first_name}}`, Braze connected content, or unsubscribe links). These are **not** Aampe variables — they're resolved by your send tool at delivery time.

When configuring your template, distinguish between:

* **Aampe fields** — sections where the agent selects personalized content (your components)
* **ESP/personalization fields** — variables resolved by your send tool (first name, unsubscribe links, dynamic content from APIs)

<Info>
  **Note:** If you plan to use your ESP’s conditional logic, such as Braze Liquid tags or Customer.io conditionals, please inform your Customer Success Manager so we can enable the appropriate support on our end.
</Info>

### 6. Working with Modular Email Layouts

Many teams don't work from a single fixed email template. They have a set of reusable HTML blocks — headers, body sections, CTAs — that get mixed and matched into different layouts depending on the campaign. This is compatible with Aampe; here's how to approach it.

**Set up one template per distinct layout, not one per every possible combination.** If you have 3 common email structures (say, a single-column with a hero, a two-block product layout, and a plain text format), configure those 3 as separate templates in Composer. Avoid trying to capture every permutation — that creates more complexity than agents can meaningfully learn from.

**ESP content blocks stay as-is.** If your modular blocks are managed by your ESP (for example, Braze content blocks referenced as liquid tags), you don't need to change anything. Aampe preserves those references in the HTML and your ESP resolves them at send time. What Aampe personalizes are the text and content fields *within* the template, not the structural blocks themselves.

**If you want agents to learn which layout works better, make it a component.** If the structural variation is meaningful — like testing a hero image layout vs. a plain text layout — you can create a label for it (e.g. an "Email Format" component with labels like "Hero" and "Plain"). This lets agents discover which layout resonates with each user over time.

<Info>
  **One heads-up:** Making a header section dynamic can sometimes strip its CSS styling in some email clients. If you see rendering issues after configuring a header as a variable, check that the styling is still applied and add it back manually if needed.
</Info>

***

## Understanding your Content Coverage

**Content Coverage** (found under Monitoring > Label Management) is your primary tool for identifying where to invest your content efforts. It shows a grid comparing two component types (e.g., Offering × Value Proposition) and reveals:

* **Gaps** (black triangle): label pairs with fewer than 3 alternates — these need more content
* **Opportunities** (yellow triangle): label pairs that appear in a message group but are missing one label — easy wins for expansion
* **Blank cells**: label pairs that haven't appeared together yet — new territory to explore

Use this map regularly to guide where you create new alternates. Focus on filling gaps and opportunities before exploring blank cells. (A Guide on Coverage coming soon)

***

## Content Creation Targets

While every account is different, here are general benchmarks based on experience across customers:

**For a healthy email strategy:**

* Cover **50–60% of your Content Map** rows within the first year
* Aim for **at least 3 alternates per label per component** in each message group
* Target **10+ offering labels, 10+ value proposition labels, and 5+ CTA labels** for mature programs
* Ensure content spans both **core value propositions** (the main drivers of your business) and **niche value propositions** (contextual, specific angles)

**For agent learning specifically:**

* Agents need enough interactions to discover preferences. A healthy baseline is **14+ agent-customer interactions per week per user** (the TACIR metric), with the ideal range being 28–42.
* This doesn't mean sending 14 emails per week — it means having enough content variety across channels (push, email, surfaces) so agents have material to work with at every touchpoint.
* More content variety, not more sends, is what drives higher interaction rates.

***

## Common Aampe Email Mistakes to Avoid

**Building content for only one goal.** If you define a single outcome and build all content narrowly around it, learning stalls. Agents can't explore alternative paths to conversion, and users get over-messaged on a single topic. Remember: measurement should be scoped to a goal, but learning shouldn't be.

**Too many components in one email.** A single email with 21 components can generate trillions of alternate combinations, but agents can't meaningfully learn across that many variables. Keep it focused. If you want to start simple, begin with subject lines and pre-headers.

**Unbalanced label coverage.** Having 10 alternates for one label and 1 for another creates skewed learning. Keep alternate counts roughly even across labels.

**Treating structural components as semantic ones.** Greeting variations ("Hi!" vs "Hey!" vs "Hello!") don't teach agents much about user preferences. Treat greetings as openers or hooks to engage the customer. They do not necessarily have to be a simple hello — they can also be a statement or a question. Invest your effort in meaningful content variation — the value propositions, offerings, and angles that actually differentiate messages.

**Never iterating on content.** Once you've established a healthy baseline, review performance regularly, refresh stale content, and add new variants where you need more coverage or experimentation. This iterative process is what turns a good portfolio into a great one.

***

## Quick Reference Checklist

* Content Map covers the full range of user motivations, not just one goal
* 50%+ of Content Map rows have at least basic content implemented
* Each email message has 3–6 dynamic components
* Every component uses all available labels (or as many as make sense)
* At least 3 alternates per label per component
* Alternate counts are balanced across labels
* Subject lines and pre-headers are dynamic with labeled alternates
* Component locking is enabled for repeating sections
* Value proposition and offering components are prioritized over greetings/CTAs
* Content Coverage map is reviewed regularly for gaps and opportunities
* Template technical elements (tracking, conditional logic, content blocks) are preserved

***

## Further Reading

* [Components & Labels in the KB](https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/component_and_labels)
* [How to use the coverage map](https://kb.aampe.com/user-guide/managing-agents-strategically/content-coverage)
* [Organizing messages into topics](https://kb.aampe.com/user-guide/managing-agents-strategically/topics)
* [Import and configure HTML templates](https://apps.aampe.com/email-config)


# Create an Email Message
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/email/create-email

Personalization is so much more than 'hello {first-name}'

## How to Create Emails in Aampe

<iframe title="YouTube video player" />

## Step 1: Create a Template

Under **Message Settings > Email templates**, click **Create**.

<img alt="Email Template Menu" />

Give your new template a name. You will also choose if you want to design with Aampe's template builder or create the email via HTML.

<img alt="Create Email Template Menu" />

### Aampe Email Template Builder

The email template builder is a no-code interface that allows you to construct visually appealing emails that immediately connect with Aampe's personalization features.

Simply drag the components onto the canvas and arrange them however you like.

<img alt="Email Builder" />

Looking for a novel image? Use the **Magic Image** feature to create new images on the fly.

<img alt="Email Image Maker" />

### Dynamic Fields

When building out the email template, use a `{{fieldname--field}}` placeholder to designate dynamic fields.

Refer to the following syntax to insert dynamic fields:

| **Element** | **Dynamic field format** |
| - | - |
| Single line header | `{{headline--field}}` |
| Another Single line header | `{{headline_2--field}}` |
| Multi-line Body | `{{body--multiline}}` |
| Another Multi-line Body | `{{body_2--multiline}}` |
| Button labels | `{{button--field}}` |
| Another button label | `{{button_2--field}}` |
| Button URL | `{{button_url--link}}` |
| Image URL for image components | `{{image_url--image}}` |
| Image Link (on click of image) | `{{image_url--link}}` |

* If you're comfortable editing HTML, you can place the dynamic fields *anywhere*. Image URLs, font sizes, or text.

<img alt="Dynamic Field Example" />

When your template is ready, press **Publish** to make the template visible to your content catalog.

## Step 2: Populate a Template with Content

In the **Messages** panel, click **Create a New Message** to bring up the following menu. Click **Email**.

<img alt="Messages Channel Menu Email" />

Fill out the Message Setup form

* Give your message a name
* Choose your template
* Select your [audience](/user-guide/using-aampe/audiences/audiences)
* Designate a sender (from field).

You can also add any tags, [triggers](/user-guide/using-aampe/audiences/triggers), or labels, as needed.

<img alt="Email Message Setup" />

Click **Next**.

To build out the dynamic content for your email

* Enter text
* Highlight any text you would like to vary across users
* Create the specific variants

<img alt="Message Composer" />

Need a refresher on components and labels? See [here](/user-guide/using-aampe/messages-by-channel/component_and_labels) for a deep dive with examples for each of our label groups.

For best results make sure each variant has a label. You can have hundreds of variants but should only create new labels when necessary.

<img alt="Message Variants" />

After creating all the variants, click **Next** and review all the alternates and labels for each field.

<img alt="Check Variants" />

Make changes as needed and click **Next**.

### Scheduling

Choose your preferred scheduling heuristic.

* **Delegate to agents:** Your agents determine the ideal variant and time for each user.
* **Automated scheduling with guardrails:** Specify certain days of the week, specific calendar days, or hours of the day that agents can operate within.
* **One-at-a-time message scheduling:** Send to everyone at once, bypassing the agent.

<img alt="Email Scheduling" />

Click **Next** for a final review.

In the final panel you can click through alternates to inspect the final result. You can also send a test email to yourself or someone else for a high-fidelity test.

<img alt="Review" />

Click **Save**. Your email message is available for agents to send.


# Create an Email Message
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/email/create-email-in-aampe

Personalization is so much more than 'hello {first-name}'

<Steps>
  <Step title="Create a Template">
    Under **Message Settings > Email templates**, click **Create**.
  </Step>

  <Step title="Build your template">
    <Card title="Use the Email Template Config app" icon="mailbox-flag-up" href="user-guide/using-aampe/messages-by-channel/email/using-the-email-config-app">
      The app allows you to build out your email templates for the agents to send
    </Card>
  </Step>

  <Step title="Create a New Email Message">
    In the **Messages** panel, click **Create a New Message** to bring up the following menu. Click **Email**.

    <img alt="Messages Channel Menu Email" />
  </Step>

  <Step title="Setup your New Email message">
    Fill out the Message Setup form, give your message a name, Choose the template you created, Select your [audience](https://kb.aampe.com/user-guide/using-aampe/audiences/audiences) and designate a sender (from field). You can also add any tags, [triggers](https://kb.aampe.com/user-guide/using-aampe/audiences/triggers), or labels, as needed. Click **Next** to pop

    <img alt="Email Message Setup" />
  </Step>

  <Step title="Populate a Template with Content">
    To build out the dynamic content for your email

    * Enter text
    * Highlight any text you would like to vary across users
    * Create the specific variants using Component and Labels. Need a refresher on components and labels? See [here](https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/component_and_labels) for a deep dive with examples for each of our label groups.

      <img alt="Message Composer" />

    For best results make sure each variant has a label. You can have hundreds of variants but should only create new labels when necessary.

    <img alt="Message Variants" />
  </Step>

  <Step title="Review all Alternates">
    After creating all the variants, click **Next** and review all the alternates and labels for each field. Once done, proceed to Scheduling.

    <img alt="Check Variants" />
  </Step>

  <Step title="Choose your preferred scheduling heuristic">
    * **Delegate to agents:** Your agents determine the ideal variant and time for each user.
    * **Automated scheduling with guardrails:** Specify certain days of the week, specific calendar days, or hours of the day that agents can operate within.
    * **One-at-a-time message scheduling:** Send to everyone at once, bypassing the agent

    Once done, click **Next** for a final review.

    <img alt="Email Scheduling" />
  </Step>

  <Step title="Final Review">
    In the final panel you can click through alternates to inspect the final result. You can also send a test email to yourself or someone else for a high-fidelity test.

    <img alt="Review" />
  </Step>

  <Step title="Click Save & Send your email message for Review or make it Live.">
    Congrats! Your email message is available for agents to send.
  </Step>
</Steps>


# Using the Email Config App
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/email/using-the-email-config-app



The Aampe Email Configurator helps turn static HTML email templates into dynamic templates with Aampe-ready placeholder fields.

It is best understood as a setup tool. You start with existing email HTML, mark which parts should become dynamic, preview the result, and then hand the configured template off for use in your email workflow.

<Warning>
  **It is NOT:**

  * a drag-and-drop email builder
  * your sending platform
  * a replacement for Composer
</Warning>

## Why it matters

Email templates often already exist, but they are usually static and hard to personalize safely.

The configurator helps you:

* reuse existing email templates instead of rebuilding them
* mark headlines, paragraphs, images, links, and buttons as dynamic fields
* preserve advanced code such as JSON-LD and template syntax
* preview the finished template before handoff

In practice, this has been especially helpful for teams importing real customer HTML from platforms like Braze, Customer.io, and SFMC.

## How it works

The tool follows a three-step workflow:

1. [Add HTML](#step-1-add-original-html)
2. [Configure Fields](#step-2-configure-fields)
3. [Preview and Export](#step-3-preview-and-export)

***

## Step 1: Add Original HTML

Bring your HTML email template into the editor in one of three ways:

* paste HTML directly into the editor
* upload an HTML file
* load a sample template from Saved Templates

<Note>
  We have built-in sample templates like product recommendations, these samples are read-only and are useful for learning the workflow before using your own HTML.
</Note>

### Cleanup HTML

<Warning>
  Do not use Cleanup HTML if your template includes:

  * JSON-LD structured data
  * Jinja2 template tags
  * Liquid template tags
  * custom script blocks

  Those should be added or preserved through the code editor in Step 2 instead. This is feature is in Beta, please use with caution. Always have a backup of your template before using the cleanup feature.
</Warning>

After loading HTML, you can use Cleanup HTML to sanitize the template.It helps with:

* removes script blocks
* removes noscript blocks
* strips tracking-pixel images
* removes data attributes and inline event handlers
* preserves Outlook-specific MSO conditional comments

Use Cleanup HTML if the preview is blank or if you want a cleaner baseline for editing.

### Render Preview

Click Render Preview to see a live rendering of your HTML.

When preview mode is active, the Continue to Configure Fields button stays visible at the top of the editor panel.

### Save and Load

You can save your work at any time with Save Template and reload it later through Saved Templates.

**Keep in mind:**

* templates are stored in your browser's local storage only
* they are not synced across devices
* always save a backup by downloading or copying the final template

***

## Step 2: Configure Fields

This is the core step. You assign dynamic placeholder fields to specific parts of the email by clicking directly in the live preview.

### Clicking to assign a field

1. Hover over the preview and let elements highlight.
2. Click an element.
3. Enter a field name and choose a field type.
4. Confirm to create the placeholder.

The selected element is then marked in the template source.

### Tagging only part of an element

If you want to tag only part of a paragraph, bullet, or mixed-content block:

1. Click and drag to select the exact text you want.
2. Release the mouse.
3. Click inside the highlighted element.
4. Choose Specific text only.

This is helpful when an element contains both bold and plain text, or when only one span inside a larger block should become dynamic.

### Supported Dynamic fields

When building out the email template, use a `{{fieldname--field}}` placeholder to designate dynamic fields.

Refer to the following syntax to insert dynamic fields:

| **Element** | **Dynamic field format** |
| :- | :- |
| Single line header | `{{headline--field}}` |
| Another Single line header | `{{headline_2--field}}` |
| Multi-line Body | `{{body--multiline}}` |
| Another Multi-line Body | `{{body_2--multiline}}` |
| Button labels | `{{button--field}}` |
| Another button label | `{{button_2--field}}` |
| Button URL | `{{button_url--link}}` |
| Image URL for image components | `{{image_url--image}}` |
| Image Link (on click of image) | `{{image_url--link}}` |

* If you're comfortable editing HTML, you can place the dynamic fields *anywhere*. Image URLs, font sizes, or text.

### Notes on supported fields

The subject and preheader fields are automatically added to every template. You do not need to assign them manually.

Both are visible in the envelope bar above the email preview.

When you click a button or linked element, you can choose between:

* the visible CTA text
* the destination URL
* a general single-line text replacement

If an image is wrapped in a link, clicking the image also lets you target the wrapping link URL.

### Target selection

For text elements, you can choose whether the field should replace:

* the entire element content
* only the selected text
* the parent container

### JSON-LD, scripts, and custom code

If your template contains JSON-LD or other script blocks, the preview shows blue info badges at the top of the iframe.These scripts are not rendered as visible email content, but they are preserved in the exported HTML.Use the Edit HTML code editor in Step 2 to add or maintain:

* JSON-LD
* Jinja2 syntax
* Liquid syntax
* any other custom code that should survive to export unchanged

Code editor changes are preserved even if you continue assigning fields from the preview.

### Viewport preview

Desktop is the default view and You can switch between Mobile (375px) and Desktop (800px).

### Managing fields

The field list on the right shows every configured field. You can rename or delete most fields. The subject and preheader fields are pinned and cannot be removed.

***

## Step 3: Preview and Export

Preview mode lets you type real values into each configured field and see exactly how the email will look before final handoff.

### Filling in preview values

Each field appears in a form under Preview. As you type values, the email preview updates live.

This includes:

* subject
* preheader
* text fields
* image URLs
* links
* button labels

### Email envelope bar

Above the email body preview, the tool shows a two-row bar for:

* Subject
* Preview, meaning preheader

These values update instantly as you type.

### Hover highlighting

When you hover over a field row in the left panel, the matching area in the preview is highlighted so you can verify that each field targets the correct element.

***

## Final handoff

Click Export Template to open the handoff panel.

It guides you through:

1. Copying the configured HTML
2. Opening Aampe Composer so you can paste it into the email template editor

You can also set a filename and download the HTML file directly.

Important:

* the final HTML contains placeholder tokens, not preview values
* custom code such as JSON-LD, Jinja2, and Liquid is preserved verbatim

***

## Best practices

* start with a sample template if you want to learn the workflow quickly
* keep field names short and descriptive
* drag-select only the text you want when tagging part of a larger block
* use the code editor for JSON-LD, Jinja2, and Liquid syntax
* preview at both 375 px and 800 px widths before final handoff
* save often and keep a backup
* start simple if your team is new to email personalization, using subject, preheader, and a few safe text fields first

***

## Common questions

### Can I use this without having my own HTML ready?

Yes. You can start with one of the built-in sample templates from Saved Templates.

### What kinds of things can I tag as fields?

You can tag text, long-form text, images, links, button labels, button URLs, video URLs, subject, and preheader.

### Do I need to add subject and preheader manually?

No. The tool automatically adds both fields to every template.

### Will custom template syntax survive?

Yes. JSON-LD, Jinja2, Liquid, and other custom code added in the code editor are preserved through final output.

### Why does the subject and preheader bar show placeholders instead of real text?

In Step 2, the bar shows placeholder tokens. In Step 3, once you enter preview values, it shows the actual typed text.

### What happens if copy to clipboard fails?

Use the download option instead and copy the HTML from the downloaded file.

***

## Troubleshooting

### The preview is blank or broken

Use Cleanup HTML in Step 1. Some email HTML contains scripts, noscript blocks, or tracking pixels that can interfere with the preview.

### My JSON-LD or template tags disappeared

Do not use Cleanup HTML on templates that contain script blocks or template control syntax. Add or preserve those through the Step 2 code editor instead.

### Fields are not appearing after I click an element

Make sure you clicked a valid element and entered a field name. If the placeholder syntax was manually edited and became malformed, delete the field and assign it again.

### I want to tag a button URL and its label separately

Tag the button URL and the button label as separate fields.

### Saving or loading templates is failing

Templates are stored in browser local storage, which has a size limit. If storage is full, keep the HTML file as a backup instead.

### The final HTML is not rendering correctly in my email client

Test the final HTML in the target email client. Some clients strip or alter CSS, and that behavior is outside the scope of the configurator itself.

Also note that real setup feedback included cases where making a header dynamic affected its styling and required follow-up correction. If a fielded element looks visually off, inspect both the placeholder placement and the surrounding HTML and CSS rather than assuming the field itself is wrong.


# Personalizing Messages with User Attributes
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/personalization

Use dynamic placeholders to personalize message content with real user data

Aampe lets you insert per-user attribute values directly into your message copy using a simple placeholder syntax. When a message is sent, Aampe resolves each placeholder with that user's actual data and falls back to a default value if the attribute is missing.

## Syntax

```
{{aampe.user_property.ATTRIBUTE_NAME|FALLBACK_VALUE}}
```

| Part | Description |
| :- | :- |
| `aampe.user_property.` | Required namespace prefix |
| `ATTRIBUTE_NAME` | The name of the user attribute (e.g. `first_name`, `tier`, `city`) |
| `\|` | Separator between the attribute name and the fallback value |
| `FALLBACK_VALUE` | The value to use if the attribute is null or missing for this user |

## Fallbacks Are Required

Every placeholder **must** include a fallback value. If a placeholder is written without one (e.g. `{{aampe.user_property.first_name}}`), it cannot be resolved and the message will not be delivered to that user.

<Warning>
  Messages containing unresolved placeholders are dropped at send time. Always include a fallback to ensure delivery.
</Warning>

## Examples

**Greeting with first name:**

```
Hello {{aampe.user_property.first_name|there}}!
```

Renders as `Hello Sarah!` if `first_name` is set, or `Hello there!` if it isn't.

**Subscription tier:**

```
You're on the {{aampe.user_property.plan|free}} plan.
```

**Numeric attribute:**

```
You have {{aampe.user_property.points|0}} reward points.
```

**City-based copy:**

```
Check out what's trending in {{aampe.user_property.city|your area}} right now.
```

## How Resolution Works

* Placeholders are resolved **before** the message is sent to your delivery provider.
* If the attribute exists and has a value (even `0`, `false`, or an empty string) that value is used. The fallback is only triggered when the attribute is `null` or absent entirely.
* All resolved values are treated as strings in the final message content.

## Using Your Delivery Provider's Personalization Syntax

Your delivery provider may have its own syntax for personalizing messages. For example, Braze supports dynamically adding user attributes via [Liquid](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/liquid/using_liquid#liquid-syntax). If your messaging provider supports referencing user attributes via the send API, you can include the syntax directly in the Aampe message builder.

<img alt="Braze Liquid syntax entered in the Aampe message builder" />

<Note>
  When using provider-native syntax alongside Aampe placeholders, Aampe resolves its own `{{aampe.user_property.*}}` placeholders first. Your provider then processes its own templating when the message is delivered.
</Note>

## Where to Find Your Attribute Names

The attribute names available to you are the user properties you send to Aampe via your data integration. You can find a reference list of common properties in the [User Attributes](/developer-guide/data-ingest/user-properties) guide, or check with your data or engineering team for the exact keys in your dataset.

## Using Personalization in a Message

There are two ways to insert a placeholder into your message:

**Option 1: Insert User Attribute button (recommended)**

Click the **Insert user attribute placeholder** button in the bottom right of any message text field.

<img alt="Insert user attribute placeholder button" />

The **Add user attribute** modal will open. Select an attribute from the dropdown and enter a fallback value. Both fields are required before the placeholder can be inserted.

<img alt="Add user attribute modal" />

**Option 2: Type it manually**

You can type the placeholder syntax directly into any text field:

```
{{aampe.user_property.first_name|there}}
```

<img alt="Placeholder typed manually in the message body field" />

Both methods produce identical output when the message is sent. The UI button has the advantage of validating that both the attribute name and fallback value are present before insertion. Manual typing has no such check, so a malformed placeholder won't be caught until send time.

To verify your placeholders are working correctly before going live, use the [send test message](/user-guide/using-aampe/messages-by-channel/push/send-test-message) feature to preview how a message renders for a specific test user.


# Action Buttons
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/push/action-buttons



When you add action buttons to a push notification, users see one or more tappable buttons below the notification text. Each button can trigger a specific action: opening the app, navigating to a web URL, or deep linking to a specific screen within your app.

Action buttons are available for **push notifications only** and work on both iOS and Android, though the experience differs between platforms.

***

## Platform Behavior

### iOS Action Buttons

iOS uses a system of **notification categories** — pre-defined button groupings that your app registers during setup. When you configure action buttons in Aampe, you select a category, and the corresponding buttons are displayed automatically.

Available categories:

| Category | Buttons Displayed |
| :- | :- |
| Accept / Decline | Accept, Decline |
| Yes / No | Yes, No |
| Confirm / Cancel | Confirm, Cancel |
| More | More |

On iOS, button labels are determined by the selected category. Custom button text is not supported for most providers.

### Android Action Buttons

Android supports fully customizable action buttons. You can set any text for each button and configure up to 3 buttons per notification. No category selection is required.\\

## Setting Up Action Buttons in Composer

1. Create or edit a **push notification** message in Composer.
2. Navigate to the **Content** step.
3. Locate the **Action Buttons** section.
4. For each button, configure:
   * **Action type:** Open App, Redirect to Web URL, or Deep Link into Application
   * **Button text** (Android): Enter your custom label
   * **Category** (iOS): Select from the available notification categories
5. Save your message and use the preview to verify the button configuration.

***

## Action Types

| Action Type | What It Does | Example |
| :- | :- | :- |
| **Open App** | Launches the app to the default screen | "Open" button on a promotional notification |
| **Redirect to Web URL** | Opens a web page in the device browser | "Learn More" linking to a landing page |
| **Deep Link** | Opens a specific screen within the app | "Listen Now" linking directly to a playlist |

Deep links are the most effective option for driving conversions — they take users exactly where they need to go, reducing the steps between notification and action.

***

## Provider Notes

Action button behavior may vary slightly depending on your messaging provider. Here's what to know:

* **Braze:** Supports standard iOS notification categories. Android buttons are fully customizable. Uses category identifiers like `ab_cat_yes_no` and `ab_cat_accept_decline`.
* **Airship:** Similar category-based approach for iOS with identifiers like `ua_yes_no_foreground`. Android is fully customizable.
* **OneSignal:** Supports fully customizable buttons on both iOS and Android.

If you're unsure which options are available for your setup, contact your Aampe representative and we'll help you configure the right approach for your provider.

***

## Best Practices

* **Keep labels short and actionable.** Two to three words work best. Users scan notifications quickly — "Book Now," "View Deal," and "Listen" are clearer than longer phrases.
* **Use deep links whenever possible.** A button that takes a user directly to a product page, booking screen, or content item will outperform one that simply opens the app's home screen.
* **Match buttons to notification intent.** If the notification recommends a specific item, make the button take the user to that item. If the notification asks a question, use Yes/No or Accept/Decline categories.
* **Consider buttons for lightweight engagement.** Patterns like "Interested / Not Interested" or simple preference choices (e.g., "Beach / Mountains") can drive taps even when the user isn't ready to convert, generating useful engagement signals.
* **Test on both platforms.** Because iOS and Android handle buttons differently, always preview and test on both to make sure the experience matches your expectations.

***

## Frequently Asked Questions

<Accordion title="Can I use different button text for different users?">
  Not currently. Action button content cannot be varied using alternates at this time. To test different button configurations, you can create separate messages with different static button setups.
</Accordion>

<Accordion title="Why can't I customize button labels on iOS?">
  iOS requires apps to pre-register notification categories with fixed button labels. The available labels depend on the categories your app has registered and your messaging provider's support. Android does not have this constraint.
</Accordion>

<Accordion title="Can I add action buttons to email or SMS messages?">
  No. Action buttons are a push notification feature only. For email messages, use the CTA buttons available in your email template builder.
</Accordion>

<Accordion title="How many buttons can I add?">
  Up to 3 buttons on Android. On iOS, the number of buttons is determined by the selected notification category (typically 1–2).
</Accordion>

<Accordion title="Do action buttons affect notification delivery or open rates?">
  Action buttons do not affect delivery. They may improve engagement metrics (click-through rate) by giving users a direct path to take action from the notification itself.
</Accordion>

***

## Troubleshooting

<Accordion title="Buttons aren't appearing on my iOS test device">
  Make sure your app has registered the relevant notification categories in its SDK and that you've selected a category in Composer. iOS will not display buttons without a valid registered category.
</Accordion>

<Accordion title="Buttons appear on Android but not iOS">
  This usually means no iOS category was selected in Composer. Android renders custom buttons automatically, but iOS requires an explicit category selection.
</Accordion>

<Accordion title="Deep link isn't working">
  Verify that the deep link URL is correctly formatted and that your app's SDK is configured to handle the link scheme. Test the deep link in your app directly to confirm it resolves correctly before configuring it in Aampe.
</Accordion>


# Create a Push Notification
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/push/create-push

Thousands of live messages in as little as 15 minutes

## How To Create Push Notifications in Aampe

<iframe title="YouTube video player" />

## Step 1: Create a Message

Navigate to the **Messages** tab. Click **Create new message**.

<img alt="Message Create New Pn" />

Choose **Mobile push** for your channel.

<img alt="Channel Selection Pn" />

In the **Message setup** panel, give your message a name. You can also configure

* [audiences](/user-guide/using-aampe/audiences/audiences)
* [triggers](/user-guide/using-aampe/audiences/triggers)
* tags
* labels that apply to the entire message

<img alt="Message Setup Pn" />

## Step 2: Create the Message Content

You have fields for the message header, message body, an image, and a deeplink URL. The icons beneath the Deeplink field allow you to

* [connect a CMS feed](/user-guide/using-aampe/quickstart/quickstart-cms)
* [connect a dataset](/user-guide/using-aampe/tools/datasets)
* add a button
* send a test message
* add image alternates

Write a message to start things off. Think about the components of your message and how you might rewrite the message with different value propositions, offerings, etc.

<img alt="Message Content Pn" />

To create a message component, simply highlight the text. Choose the kind of message component from the dropdown.

* See [here](/user-guide/using-aampe/messages-by-channel/component_and_labels) for a deep dive on message components
* See [here](/user-guide/using-aampe/messages-by-channel/custom-components) for a guide on creating custom message components

<img alt="Highlight Message Components Pn" />

For each component, create alternates. Give each alternate a label.

<img alt="Message Component Labels Pn" />

Take a minute to review all the possible alternates. Make changes if needed and click **Next** once you are ready.

<img alt="Review Alternates Pn" />

## Step 3: Schedule and Review

Choose your preferred scheduling heuristic.

* **Delegate to agents:** Your agents determine the ideal variant and time for each user.
* **Automated scheduling with guardrails:** Specify certain days of the week, specific calendar days, or hours of the day that agents can operate within.
* **One-at-a-time message scheduling:** Send to everyone at once, bypassing the agent.

<img alt="Scheduling Pn" />

One last check. Some things to look for:

* Is the audience correct?
* Should the message operate within a specific time range?
* Do the alternates read correctly?

<img alt="Final Check Pn" />

See [here](/user-guide/using-aampe/messages-by-channel/push/send-test-message) for instructions on how to send a test message of your choosing to an approved test device.

Click **Start sending** and your message is live!


# Send a Test Message
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/push/send-test-message

Because we'd rather not send a million messages with typos

## How to Send a Test Message

### Step 1:  Add Test-Message Recipients

<Info>
  Test-message recipients only need to be added once. If you have your preferred test users from a previous message, feel free to skip this step.
</Info>

1. Go to **Account members > Test message settings** and click the **+ Add user** button.

   <img alt="Add Test Message User Pn" />
2. This will open a menu for adding a test user.

   <img alt="Add Test User Module Pn" title="Add Test User Module Pn" />
3. Fill in the three required fields:
   * Receiver name: name of the recipient
   * Token:
     * Push notifications - this is the device token
     * Emails - this is the recipient's email address
   * Provider name: the message delivery partner
4. Click **Create user** to finish adding your test-message recipient.
5. (Optional) If you want to send a test message to several recipients all at once, click the **+ Add group** button.

   <img alt="Add Group Button Pn" />

   Give your group a name and add any of your existing users to the group. You can also create new users and immediately add them to this group by adding their names and tokens in the appropriate fields.

   <img alt="Create Group Menu Pn" title="Create Group Menu Pn" />

   Click the **Create new group** button to finish creating your group.

### Step 2:  Send a Test Message

1. Open your message
2. Click the **Send a Test Message** button at the top of the page

<img alt="Send Test Message Button Pn" />

3. Select the language and message elements for your test message. This can include a  [dataset](/user-guide/using-aampe/tools/datasets) row, images, or specific labels. You can also click the **Randomize** button to select a random message variant for your test message.\
   \
   When the message is ready, click the **Select test audience** button to advance.

   <img alt="Send Test Message Menu Pn" />
4. Select your message recipients, either an individual user or a group. See [Step 1](/user-guide/using-aampe/messages-by-channel/send-test-message#step-1:-add-test-message-recipients) if you need to add a new user or group.

<img alt="Send Test Message Audience Pn" />

5. Click the **Send test message** button to deliver your message.

### What is My Device Token?

If you're unsure how to get your device token (often the case for push notifications)...

* Click the **"Need help getting this?"** link in the test message window
* This will automatically send a request to our team at [developer@aampe.com](mailto:developer@aampe.com), and we'll assist you directly


# Scheduling
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/scheduling



Message scheduling is about determining the optimal time to deliver your messages to maximize engagement and effectiveness. Proper scheduling ensures your messages reach users when they're most receptive.

## Scheduling Strategies

* Time zone optimization: Delivering messages at appropriate local times
* Behavioral timing: Based on when users typically engage with your app
* Frequency capping: Preventing message fatigue by limiting delivery
* Sequence planning: Coordinating multiple messages in a logical order

Aampe's AI-powered scheduling learns from user engagement patterns to determine the best time to send messages to each individual user, significantly improving open rates and engagement.

## How to Schedule Messages

Sometimes you'll want to send a message **during a specific window**—like for a holiday promotion, a product launch, or a time-sensitive campaign.

While Aampe's agentic model thrives on having a rich catalog of messages to choose from, **scheduled messages** give you extra control when content is only relevant during a particular date range.

### Steps to Schedule a Message

1. **Write your message** as you normally would in the Message Composer.
2. Go to the `Scheduling tab` in the editor.
3. Choose your schedule
   1. **Delegate to agents** is the default. Your agents will find the right time, day and frequency.
   2. **Messages that should be sent during a certain time** is a good choice for seasonal messages related to holidays.
   3. **One-time-send**\
      If you have a message that should be sent only once, like a monthly newsletter, you can use this scheduling functionality. Be aware that these messages are excluded from learnings for your agents.
4. When you're ready, you can review everything and hit `Start Sending` to activate the message.

Once the scheduled window ends, the message will automatically be moved to your **Expired** folder. It will no longer be eligible for delivery.

<img alt="Scheduling Options Web" />

### A Few Important Notes

<Card title="Scheduling sets eligibility, not a send time">
  Your agents will still choose the **best time** to send the message within your defined window, based on each user's behavior and context.
</Card>

<Card title="Not all users will receive all messages">
  Just because a message is live and a user is eligible doesn't guarantee delivery. Your agents select the message most likely to drive your defined goal for that user.
</Card>

<Card title="Need 100% delivery?">
  If the message must reach every user in an audience, consider using a **One time send**, which bypasses agentic optimization and ensures delivery.
</Card>


# Create an SMS Message
Source: https://kb.aampe.com/user-guide/using-aampe/messages-by-channel/sms/create-sms

Highly personalized content and timing via SMS

## How to Create an SMS Message in Aampe

## Step 1: Create the Message

Navigate to the **Messages** tab. Click **Create new message**.

<img alt="Create New Message Pn" />

Choose **SMS** for your channel.

<img alt="Select Channel Pn" />

In the **Message setup** menu, give your message a name. You can also configure

* [audiences](/user-guide/using-aampe/audiences/audiences)
* [triggers](/user-guide/using-aampe/audiences/triggers)
* tags
* labels that apply to the entire message

<img alt="Message Setup Pn" />

## **Step 2: Create the Message Content**

Write an initial message to get started. Think about the components of your message and how you might rewrite the message with different value propositions, offerings, etc.

The icons beneath the Message field allow you to

* [connect a CMS feed](https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-cms)
* [connect a dataset](https://kb.aampe.com/user-guide/using-aampe/tools/datasets)
* send a test message
* add image alternates

<img alt="Message Content Pn" />

To create a message component, simply highlight the text. Choose the kind of message component from the dropdown

* See [here](/user-guide/using-aampe/messages-by-channel/component_and_labels) for a deep dive on message components
* See [here](/user-guide/using-aampe/messages-by-channel/custom-components) for a guide on creating custom message components

<img alt="Component Highlight Menu Pn" />

Create alternates for each component. Give each alternate a label.

<img alt="Components And Labels Pn" />

<img alt="Review Alternates Pn" />

Review your work and make changes if needed. Click **Next** once you are ready.

## Step 3: Schedule and Review

Choose your preferred scheduling heuristic.

* **Delegate to agents:** Your agents determine the ideal variant and time for each user.
* **Automated scheduling with guardrails:** Specify certain days of the week, specific calendar days, or hours of the day that agents can operate within.
* **One-at-a-time message scheduling:** Send to everyone at once, bypassing the agent.

<img alt="Scheduling Pn" />

One last check. Some things to look for:

* Is the audience correct?
* Should the message operate within a specific time range?
* Do the alternates read correctly?

<img alt="Final Pn" />

Click **Start sending** to add your SMS message to your content catalog. Agents will start sending messages within 24 hours.


# Creating the Surface
Source: https://kb.aampe.com/user-guide/using-aampe/product-surfaces/surfaces-composer

Creating an Aampe Surface results in an API that can power a personalized frontend experience. 

## Creating Surfaces

Once you know the Surface elements you would like to personalize and have any necessary creative assets prepared, you're ready to create the Surface in Aampe.

* Not sure if you're ready to create a Surface? Read up on preparing your content for Surfaces.

The steps to create a Surface include:

* Creating and reviewing all the fields we'd like to include in the API payload
* Creating variants for all of those fields
* Assigning specific events to measure the impact of Surfaces (optional)

### Creating and Reviewing Surface Fields

<Note>
  This step can also be completed via Figma's Aampe Surface Creator. See here for instructions on using the Aampe Surface Creator in Figma.
</Note>

Within the Aampe composer, navigate to the Surfaces section.

* Click "Create Surface" to bring up the following form

<img alt="Surface Setup Pn" />

* When naming the Surface, keep in mind that the Surface may include content for multiple page components
* Frequency Guardrails allow you to require a minimum amount of time to elapse before showing Surface content again. (e.g. You want to show the personalized message no more than once a week, even if the user opens the screen many times a day).

### Creating Fields via Surface Templates

If you have a ready-made template, feel free to select it. A template is simply a list of fields and is unrelated to the message variants that will eventually populate those fields.

You can also create the list of fields directly by selecting `+ Create Custom` from the Surface Template menu.

In this example, we have a template called 'Fitness App' that we made previously.

<img alt="Surfaces Demo Composer Template1 Pn" />

After reviewing the list of fields, we are ready to attach message variants.

## Creating Surface Templates

If you do not have a template to use and would like to create one, navigate to the Surfaces > Templates page in the Aampe Composer

* Click `Create Template` to bring up the following screen

  <img alt="Surfaces Demo Createtemplate2 Pn" />
* Add each field you want returned when calling the Surfaces API
* Save the template

## Attaching Content to Surface Fields

A Surface needs at least 1 message, and that single message can have many variants.

### Adding a Message

* After saving your template, click `+ Message` to bring up the **Create message** form
* Choose an appropriate name, audience, and labels (optional)

<img alt="Surface Demo Message1 Pn" />

You will have the option later on to add additional messages. Assigning multiple messages to a Surface allows you to

* Add additional content without manipulating existing messages and variants
* Create content for specific audiences
* Ensure elements of the page are thematically consistent (e.g. if you want a picture of a dog to appear with subtitles that mention dogs)

### Adding Message Variants

Creating message variants within Surfaces is generally the same as creating message variants for Push, Email, or SMS (see here to review how to create messages and variants for outbound messages).

* Write your first text in each field
* Highlight components in each field to add variants and apply labels (this enables experimentation and learning)

For visual elements (e.g. button color), your variants may be a single word, color codes, image urls, or numbers for size or positioning variables.

<img alt="Surfaces Demo Messages3 Pn" />

<Note>
  Image field types are currently unable to create variants. If you want to create variants of image urls, simply use a generic single-line text field.
</Note>

## Select Funnel Events

Saving your messages brings you an optional step of selecting specific events to associate with this funnel. \
\
If your Surface is inviting users to complete a daily lesson, make a purchase, or refer a friend, you can choose the event that aligns with that specific goal.

<img alt="Surfaces Demo Funnel Events1 Pn" />

## Review API Results

Saving the Funnel Events brings you to the final `Review` screen which demonstrates how you would call the Surfaces API to retrieve intelligent content combinations for a specific user.

On this page, you'll find details for calling the API directly, as well as for connecting the API to assets managed by Braze.

<img alt="Surfaces Demo Review API Pn" />

The API Response on the screen is for illustrative purposes only (hence the "sample value" placeholders), but will make it easier for developers to start integrating the Surface into the intended frontend experience.

```
[
  {
    "surface_id": "7a6070e3-9217-4480-a530-6ea6a90ebcac",
    "assignment_id": "b022b907-d607-4055-b69a-3dea450ec4ae",
    "n_alternates": 1,
    "control": {
      "min_gap_days": 1
    },
    "alternates": [
      {
        "alternate_assignment_id": "c0858305-9b10-42a6-95cf-6d92af3b69ed",
        "subtitle": "Sample Value",
        "button-color": "Sample Value",
        "button-text": "Sample Value",
		"image-url": "Sample Value"
      }
    ]
  }
]
```

## Ready to Integrate Surfaces into Your Product?

See our [developer guide](/developer-guide/surfaces/surfaces-embed) for instructions on how to embed Surface content into your application.


# Preparing Content for Surfaces
Source: https://kb.aampe.com/user-guide/using-aampe/product-surfaces/surfaces-content

If code renders the element on your screen, Surfaces can personalize it

## The End Goal

To implement Surfaces, your goal as an Aampe user is to

* create a list of all the surface elements that will personalize when a page loads
* prepare any images or other creative assets, if needed

When you load this information into the Surfaces composer, it will provide you with an API. You can share this API with your engineering team to embed Aampe into your application.

## Step 1: Examine Your Current Screens

Consider any screen in your app or website. What elements could be personalized? \
\
Let's examine this fictional landing page.

<img alt="Surfaces Demo Fitness1 Pn" title="Surfaces Demo Fitness1 Pn" />

Even on a simple screen like this, there are several elements we could personalize.\
\
Let’s start with the gray subtitle. Instead of **smarter workouts**, some users may respond more to **community and connection**.

<img alt="Surfaces Demo Fitness2 Pn" />

Suppose you also want to personalize the call-to-action button with variations in text, color, size, or all of the above.

<img alt="Surfaces Demo Fitness3 Pn" title="Surfaces Demo Fitness3 Pn" />

## Step 2: Prepare Visual Assets

Once you've decided what elements are worth personalizing...

* Prepare any images and other pre-made visual assets you'd potentially use. If you're personalizing which of 10 cat pictures will show up for each user, you'll need all of those images ready.
* List the text fields, colors, button sizes, or other UI elements you want to personalize
* Make sure these fields can be programmatically defined at runtime—Aampe will overwrite them with values from the Surfaces API when the page loads. For images, this usually means having an image url assigned.

## Step 3: Create the Surface in Aampe

Almost there! [See these instructions](/user-guide/using-aampe/product-surfaces/surfaces-composer) for creating your Surface in Aampe.

## Bonus: Special Tools for Figma Users

If you're working in Figma, the [Aampe Surface Creator](/tools/figma-plugin) plugin can help you quickly extract page components and prepare them for integration.


# Aampe Quickstart Guide
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/overview



## Steps to Setting Up Aampe

* [Signing in and inviting colleagues](/user-guide/using-aampe/quickstart/quickstart-signin)
* [Connect Aampe to a data source](/user-guide/using-aampe/quickstart/quickstart-datafeed)
* [Define funnel events](/user-guide/using-aampe/quickstart/quickstart-events)
* [Connect Aampe to your messaging tools](/user-guide/using-aampe/quickstart/quickstart-messages)
* [Create an audience](/user-guide/using-aampe/quickstart/quickstart-audiences)
* [Create and send your first message](/user-guide/using-aampe/quickstart/quickstart-messages)

## Advanced Features

* [Connect CMS data](/user-guide/using-aampe/quickstart/quickstart-cms)
* Integrate a recommendation engine
* [Bulk content management](/user-guide/using-aampe/tools/datasets)
* [Integrate Aampe into an app or website](/user-guide/using-aampe/quickstart/quickstart-surfaces)
* [Working with agents](/user-guide/managing-agents-strategically/working-with-agents)
* [Send Aampe data to my data warehouse](/user-guide/how-do-i-know/analytics/data-share-overview)


# Create an Audience
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-audiences

Audiences connect groups of users with groups of potential messages

## How Aampe Audiences Work

Aampe audiences are different from typical marketing segments in that they define which users are *eligible* to receive a given message, rather than the result of assigning a user to receive a message.

Messages can be assigned to any number of audiences. A healthy audience has many potential messages available.

The task of each agent is to choose an effective sequence of messages.

## Common Audiences

Audiences allow you to align groups of messages with groups of users. This ensures messages with specific language are sent only to appropriate subsets of users.

<img alt="Audience Message Map Pn" />

* "Welcome to The Company!" content goes to new users
* "We miss you!" content goes to churned users

## Healthy Audiences

A healthy audience has a vast and varied collection of content available. Many Aampe customers find that churned users respond to evergreen content just as well as they respond to "come back" content.

Agents will manage the frequency of messages for each user based on their activity. Assigning a large number of messages to an audience does not mean the audience will receive more messages.

## Building Your First Audience

<Info>
  Please note that prior to setting up an audience, you need to [integrate a data source](/user-guide/using-aampe/quickstart/quickstart-datafeed).
</Info>

* Log into Aampe
* **Message Settings** >> **Audiences**
* Click **Create New Audience**

  <img alt="Audiences Setup Pn" />
* Give your audience a name
* Use the audience builder to create your audience

  <img alt="Audience Builder Pn" />
* **Save** (or **Save & Create Message** if you're ready to create content for your audience)

Congratulations on creating your first Aampe audience!

## Advanced Audience Features

Great work for this Quickstart. Time to check out our comprehensive [audience page](/user-guide/using-aampe/audiences/audiences).


# Connect CMS Data
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-cms

Insert dynamic product, content, or service information directly into your Aampe messages

## How It Works

Your CMS integration provides Aampe with real-time access to your product catalog, content library, or service listings. Agents can then reference this information when building personalized messages.

Instead of static messages, you create templates with placeholders that get filled in automatically with the best content for each user at send time.

For example, a message template might say "Check out this product\_name - now discount% off!" and agents will insert the most relevant product and current discount for each individual user.

## What You Can Connect

* **E-commerce Systems** provide product information like names, prices, images, categories, and current promotions that can be inserted into messages.
* **Content Management Systems** offer articles, videos, courses, or other content that can be recommended to users based on their interests and behavior.
* **Service Catalogs** include offerings, schedules, availability, and booking information that can be personalized for each user's location and preferences.
* **Inventory Systems** provide real-time stock levels, enabling messages about low inventory, back-in-stock notifications, or alternative product suggestions.

## Advanced Use Cases

* **Abandoned Cart Recovery** becomes incredibly powerful when agents can reference the specific items left in each user's cart and suggest related products or provide targeted incentives.
* **Product Recommendations** use both individual agent learning and your product catalog to suggest items that each user is most likely to purchase.
* **Dynamic Pricing** messages can include current promotions, user-specific discounts, or time-sensitive offers that create urgency while respecting individual preferences.
* **Inventory Alerts** notify users when items they've shown interest in come back in stock or when similar items become available.

## Benefits for Agents

CMS integration gives agents much richer information to work with when personalizing messages. They can learn not just what messaging style works for each user, but which types of products, content, or services resonate most.

Agents also use CMS data to improve timing decisions, learning when users are most likely to engage with different types of offers or content.

This creates a feedback loop where agents get smarter about both messaging and product recommendations, leading to better user experiences and higher conversion rates.

## Getting Started

Your development team will set up the technical connection between your CMS and Aampe. This typically involves API access or data sync processes that keep information current.

Start with your most important or popular products and content. You can expand the integration over time to include more catalog information and advanced features.

***


# Connecting Aampe to a Data Source
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-datafeed

Aampe needs user and event data

## What Data Does Aampe Need?

Aampe needs two types of data to work effectively.

* **User Events** are the actions people take in your app or website. These include purchases, page views, clicks, cart additions, and any other interactions that matter to your business.
* **User Properties** are basic information about your users. This includes things like country, language, or subscription status.

## How It Works

Your development team will connect Aampe to your existing data systems. This might be your analytics platform, data warehouse, or event tracking system.

Aampe supports periodic batch updates as well as real-time event streaming.

The connection is secure and fully respects your privacy requirements. Aampe only accesses the specific data you choose to share, does not ingest any personally identifiable information (PII), and stores your data in your preferred geographic region.

## What Happens Next

Once Aampe has a data source, you're all set to

* create audiences
* specify funnel events
* configure event rewards

And once you connect a messaging provider or integrate a Surface API, you're all set to deliver personalized experiences at scale.

## Getting Ready

Before starting this step, gather information about your current data setup. Know which systems track user behavior and where user information is stored.

Aampe will work with your development team to ensure the integration is successful. See [our list of supported data sources](/developer-guide/data-ingest/data-integrations) along with detailed integration guides.


# Organize Event Feed
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-events

Funnel events tell Aampe which user actions matter most for your business.

## Event Management

On the **System settings > Event management** tab you'll find two ways of categorizing events. Each serves a distinct purpose.

* [Funnel Events](/user-guide/using-aampe/admin/define-funnel-events): Puts events into groups for [tidy analytics](/user-guide/how-do-i-know/analytics/composer-analytics)
* [Event Types](/user-guide/using-aampe/admin/event-types): Key for learning. Designates whether an event is good, bad, or unimportant.

## Funnel Events

With so many different events, charts and reports can quickly turn into a mess. Setting up your Funnel Events will set you up for more elegant analytics.\
\
Your funnel represents the path users take from discovery to conversion. Different businesses have different funnels, but they often follow a similar pattern.

* **E-commerce Example:** Browse products → Add to cart → Complete purchase
* **SaaS Example:** Sign up → Complete onboarding → Use key feature → Upgrade to paid
* **Media Example:** Visit site → Read articles → Share article

See [our page on Funnel Events](/user-guide/using-aampe/admin/define-funnel-events) for step-by-step instructions and details on each category.

## Event Types

An agent learns by sending messages to a user and studying changes in their event stream. Event Types are how you designate which events are good, bad, or irrelevant for learning.

Aampe's goal is to deliver more good events (purchases, subscriptions, etc.) and fewer bad events (unsubscribes).

See [our page on Event Types](/user-guide/using-aampe/admin/event-types) for step-by-step instructions on setting up event types and guidance on knowing the right type to use for each event.

## Event Management FAQs

<Accordion title="How do agents use event data?" icon="sparkles">
  Your event feed plays two important roles:

  * enabling agents to learn which messages are effective in changing user behavior
  * defining message eligibility (e.g. only send this message to users who have done a specific action in a specific timeframe)

  [Read more about why Aampe agents measure the impact of messages using events instead of user attributes.](/user-guide/welcome-to-aampe/how-does-aampe-work/agent-help/events-vs-attributes)
</Accordion>


# Message Creation
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-messages

It's go time!

Creating a message in Aampe is a little different than other tools. A "message" is closer to a template in other tools in the way that it groups many distinct messages under a common pattern.

## Step 1: Choose Your Message Channel

Decide which communication channel you'll be using. Aampe supports multiple channels including:

* [**Push Notifications**](/user-guide/using-aampe/messages-by-channel/push/create-push) — Short, attention-grabbing updates
* [**Email**](/user-guide/using-aampe/messages-by-channel/email/create-email) — Rich content with lots of space to work with
* [**SMS**](/user-guide/using-aampe/messages-by-channel/sms/create-sms) — Short-form communication
* [Product Surfaces](/user-guide/using-aampe/quickstart/quickstart-surfaces) — Contextual content embedded in the product experience

Your channel will inform your message structure and tone.

<img alt="Channel1 Pn" />

## Step 2: Message Setup

To create your message, complete the Message Setup form.

Required fields include:

* Message name - ideally something that's easy to understand

Optional fields include:

* [Audiences](/user-guide/using-aampe/audiences/audiences) - specify which users are eligible for the message
* Triggers
* Custom tags
* Message-level labels

<img alt="Setup Pn" />

## Step 3: Define a Message Structure

The next step is to decide **how** your message will be assembled. This means defining a **message structure**—the layout of components that make up your message.

Think of this as creating a flexible template. You’re not writing a fixed message; you’re designing the *slots* your agent will use to dynamically assemble personalized messages.

### **What do we mean by structure?**

A structure is the **sequence of components** used in a message, such as:

* Greeting
* Value Proposition
* Offering
* Incentive
* Call to Action
* (Optional) Custom Components like Sub-feature, Music Genre, Cuisine Type etc

You can mix and match components in different orders depending on the message type or channel.

### **Structure Examples**

**Push**

* **Header**: \[Value Proposition]
* **Body**: \[Greeting] + \[CTA]

**Email**

* **Subject Line:** \[Value Proposition]
* **Pre-header**: \[Greeting]
* **Title**: \[Value Proposition]
* **Body**: \[Offering]
* **Button**: \[CTA]

**SMS**

* **Body**: \[Greeting] + \[Value Proposition] + \[CTA]

### **Tips for Defining a Good Structure**

* **Start simple.** Use 2–3 components per message to keep it modular and testable.
* **Always include an Offering and Value Proposition** in your early structures—they’re essential for agent learning.
* **Choose components that make sense for the channel.** For example, Push notifications often use:
  * Header → \[Value Proposition]
  * Body → \[Greeting] + \[CTA]
* **Skip what you don’t need.** Not every message needs an Incentive or Greeting. You can leave them out entirely, or test structures with and without them.
* **No repeats.** Don’t use the same component type twice in one message (e.g., two Value Propositions). It makes it harder for agents to learn what worked.

## Step 4: Create Alternates & Labels

Now it’s time to write content for each component in your message structure. Instead of writing full messages, you’ll create **alternates**—modular versions of each component—and tag them with **labels**. This is what enables your agent to learn, test, and personalize at scale.

### How to Write Alternates

* Write at least **3 alternates per label** for each component
* Make each alternate **single-focused**—it should express **one clear idea** only
  * *For example:* Instead of writing “Fast, easy, and cheap” (which spans 3 ideas), write separate alternates like “Fast delivery,” “Easy to use,” or “Best value”
* Keep the tone and sentence structure simple and natural
* Make sure each alternate can **stand alone** and combine cleanly with others

### How to Apply Labels

* Labels describe the **meaning or value** behind an alternate (e.g., *Convenience*, *Trust*)
* Use **distinct, non-overlapping labels**
* Assign **only one label per alternate**
* Reuse labels across different messages and offerings to help your agent learn faster

Start with 2–3 labels per component, and build from there. The more high-quality alternates and clear labels you create, the better your personalization will perform.

## Step 5: Preview and Test

Before sending your message to all users, it's important to preview and test it:

* Preview your message to ensure it looks good. You can use the **Cover** page to see all combinations and variants.

<img alt="Cover Pn" />

* Send a [test message](/user-guide/using-aampe/messages-by-channel/send-test-message) to yourself or a group.
* Check all links and interactive elements to make sure they work correctly
* Review the message for any typos or errors

## Message FAQs

<Accordion title="Does Aampe support multiple languages?" icon="sparkles">
  Yes, Aampe has features that make it easy to manage content in multiple languages. Read more about [how Aampe manages multiple languages](/user-guide/using-aampe/admin/languages).

  Aampe, however, does not offer a feature to translate content from one language into another. Our customer success team has experience in this area, however, and can offer guidance on any language translation projects.
</Accordion>

<Accordion title="How can I limit the number of messages sent to my customers?" icon="sparkles">
  You can set daily and weekly caps on the number of messages 

  * globally
  * by channel
  * by trigger

  This gives you the flexibility to enforce, say, one SMS message per week but still allow for outreach through other channels (push, email). \
  \
  Read more about [Aampe's frequency settings.](/user-guide/using-aampe/admin/frequency-limits) 
</Accordion>

<Accordion title="How many message variants do I need? " icon="sparkles">
  Agents do their best work when they have many message groups to choose from, and many message variants within each message group. It's easy to wear out a customer relationship when you only talk about one thing. \
  \
  How much is enough? It depends on how often agents interact with your users. To make this easier, we designed our [content coverage](/user-guide/managing-agents-strategically/content-coverage) map which highlights the messages in need of additional variants. 
</Accordion>

<Accordion title="How can I ensure certain components appear together?" icon="sparkles">
  It doesn't always make sense to mix-and-match message components. You may have an image that accompanies a specific offering, or components for city and state that need to appear together. \
  \
  There are two ways to link components together. 

  * [Syncing labels](user-guide/using-aampe/tips-and-tricks/label-locking.mdx) - specifically for labels and message components
  * [ Datasets](user-guide/using-aampe/tips-and-tricks/datasets.mdx) - can link labels, deeplinks, and any other message element
</Accordion>


# Connect Aampe to Your Messaging Tools
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-messaging-tools

Aampe doesn't replace your current setup—it makes it smarter

## How It Works

Aampe sits on top of your existing messaging infrastructure. It executes through your current push notification services, email platforms, SMS providers, and other communication tools.

When an agent decides to send a message, it triggers your existing systems using your established credentials and configurations.

This means your messages still come from your brand, use your templates, and follow your compliance settings. Aampe just decides what, when, and how often to send.

## Supported Messaging Channels

See [here](/developer-guide/message-providers/message-providers) for a list of supported messaging providers.

## What Your Team Needs to Do

Your development or IT team will integrate each messaging platform you want to use. This is often a matter of sharing API keys or other credentials so Aampe can send messages on your behalf.

They'll also check any specific settings within each tool like sender addresses, template preferences, or compliance requirements that should apply to all Aampe-generated messages.

This setup ensures that Aampe-powered messages look and feel exactly like your current communications, just with better timing, frequency, and content.

## Message Delivery Process

When an agent decides to send a message, it selects the best content variation and timing for that specific user. The agent then triggers your messaging platform to deliver the message.

All delivery tracking, bounce handling, and compliance management happens through your existing systems. Aampe receives delivery status updates to inform future agent decisions.

## Benefits of This Approach

You keep full control over your messaging infrastructure and compliance. Your data and customer relationships stay exactly where they are.

You also maintain all your existing reporting, analytics, and operational processes while gaining the benefits of 1:1 personalization.

## Getting Ready

Plan which messaging channels you want Aampe to optimize first. You can start with one channel and add others over time.


# Reward Functions
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-reward-functions

How do we define success for a given message?

How do you know if a message was successful? The answer depends on the message and its purpose.

* If the message is about your referral program, you would naturally measure success by looking at increases in referral events
* If the message is about using some specific product feature, you would measure success by monitoring usage of that product

**Reward Functions** are how you tell Aampe what success looks like for different each message.

<Warning>
  **Before you continue, are your Event Types classified?**<br />You will not be able to set up any Reward Functions until your event types are properly classified. Make sure you complete this step first. For a refresher on how to categorize events as positive, negative, or irrelevant, see our documentation on event types. [Learn More →](https://kb.aampe.com/user-guide/using-aampe/admin/event-types)
</Warning>

## Overview: How Aampe Evaluates Messages

Aampe measures the success of a message by looking for changes each user's event feed.

Each event in the event feed has a numeric value ("reward"). An agent compares the **sum of event rewards** in a period before and after the message was sent to determine if the user increased their activity in response to the message. <br /><br />But not all events are equally important. Agents typically places small rewards on log-ins, button clicks, and similar events. They place larger rewards on key conversion events and other events that frequently precede them.

How do we determine the reward for each event?

## Building A Reward Function

### Step 1: What specific outcome do you want to see as the result of a message?

Building a Reward Function starts by identifying the **one** desired outcome you want to see as a result of a message. Examples of key outcomes include:

* Making a purchase
* Enrolling in a paid subscription
* Streaming a movie or a song
* Referring a friend
* Trying out a new product feature
* Signing up for a webinar

In the Aampe composer, navigate to the Reward Function builder under **Settings > Reward Functions**. View the introductory guide and click **Create reward function**.

<Frame>
  <img alt="Guide Page" />
</Frame>

Provide a name and description. You can assign the Reward Function to specific messages now or do this later from the **Messages > setup** screen.

<Frame>
  <img alt="New Function Name" />
</Frame>

Click **Select events**.

### Step 2: Identify Target Events

With the key outcome in mind, we need to determine which events in the event feed are the best indicators of success for any assigned messages.

Aampe calls these events **target events**. These events receive full points when observed within an attribution window. All other positive events receive some amount of partial credit. See [our page on Event Types](/user-guide/using-aampe/admin/event-types) for a refresher of positive, negative, and irrelevant events.

> **Example:** Let's say I want to set up a Reward Function for messages focused on selling a product. I am going to name my Reward Product "Selling Products" and look for events in my event feed mean someone bought my product.

**Reality check:** Two things tend to make this exercise difficult

* Event streams are messy.
* Not all events are equally useful as target events

Agents can quickly learn user preferences when the target events are **voluntary** and **repeatable**. Agents struggle when target events are infrequent, delayed, or unrepeatable. (For a deeper look at which events make good learning signals, see our page on the [characteristics of good target events](/developer-guide/data-ingest/data-ingest-help/what-events-should-i-send-to-aampe#characteristics-of-good-reward-events).)

With this in mind, Aampe scores all your events based on their potential for being a strong target event.

### **Suitable and Unsuitable Events**

Events that Aampe considers to be suitable as target events are called "suitable events." You will find them easily in the main list of events. Aampe's **Learning Quality** score indicates the strength of that event as a potential target event.

<Frame>
  <img alt="Select Target Events" />
</Frame>

It's possible an event of interest is infrequent or unrepeatable and so is categorized as an **unsuitable event**.

<Frame>
  <img alt="Unsuitable Counter" />
</Frame>

Maybe this is *the* event you need.  What do you do now?<br /><br />**You can still use unsuitable events as target events.** There is some nuance to consider.

* If the Reward Function is intended to be broadly applied to many different messages, you will want to pair up your unsuitable event(s) with at least one suitable event.
* If the Reward Function is for a focused set of messages with a distinct call to action *and* the unsuitable event is the result of that action, you can confidently proceed with the unsuitable event as your target event.

### Step 3: Review the Individual Event Rewards

Once you've selected your target event(s), Aampe automatically score *all other* events based  on how often they precede the chosen target events.

<Frame>
  <img alt="Selected Target Event" />
</Frame>

The partial credit Aampe assigns for these events is central to how Aampe works. Not every message will lead to a purchase, but Aampe agents can still learn from changes in other routine events.

### Sometimes Individual Event Rewards are Negative

Not every event in a user's event stream is good. How does an Aampe agent account for unsubscribes, order cancellations, or other similarly bad events? <br /><br />Negative events receive negative rewards. Since agents learn from the **sum** of individual event rewards, agents will learn to avoid negative events.

Click **Review**.

### Step 3: Review and Save

Take a minute to review the Reward Function details.

<Frame>
  <img alt="Review Screen" />
</Frame>

Click **Save reward function.**

***

## Reward Function FAQs

<Accordion title="How many Reward Functions should we have?" icon="sparkles">
  A reward function tells agents what high-level use case they should be paying attention to when they're judging the success of a message. So we recommend one reward function per high-level use case (for example, if you have a goal for increasing subscriptions and a goal for increasing conversion, that's two RFs).

  Some customers only require one RF to cover their use cases; some have three to five. It depends on the use cases you want your agents to think about.

  Pro tip: You don't need to get too granular within the use case. For example, purchasing shoes, hats and shirts can all share one "purchase" RF. The system does not benefit from a distinct RF for shoes vs hats vs. shirts.
</Accordion>

<Accordion title="Will adding additional Reward Functions confuse my default Reward Function?" icon="sparkles">
  No. If anything it helps provide agents with helpful context when evaluating the success of a message.

  Messages about referrals *should* be evaluated on how they generate referrals while messages about purchases *should* be evaluated on whether they generate incremental purchases.
</Accordion>

<Accordion title="How do Reward Functions differ from Event Types?" icon="sparkles">
  Event Types is how Aampe categorizes events as positive, negative, or irrelevant. Target events can only be selected from positive events. Negative events will have negative event rewards. Agents ignore irrelevant events when calculating the final reward for a message. See the [Event Types page](/user-guide/using-aampe/admin/event-types) for setup instructions.
</Accordion>

<Accordion title="What makes an Target Event suitable?" icon="sparkles">
  Events work best when they provide a strong, consistent signal about user behavior. A suitable event typically has the following characteristics:

  * \*\*Broad coverage: \*\*The event applies to a large portion of your user base, not just a small segment.
  * \*\*Repeatable behavior: \*\*Users trigger the event across multiple days, allowing the system to learn patterns over time.
  * \*\*Occurs regularly: \*\*The event typically happens within a week and is distributed throughout the week.
  * \*\*Discrete action:\*\*The event represents a clear, trackable action such as a click, play, or purchase.
  * \*\*Balanced frequency: \*\*The event occurs at a reasonable rate per user. It is not so rare that it lacks signal, and not so frequent that it becomes noisy

  <Info>
    If you need more specifics or deep dive into Target events, please reach out to your Customer Success Manager.
  </Info>
</Accordion>

<Accordion title="What makes an Target Event unsuitable?" icon="sparkles">
  Events are not effective when they lack consistency, scale, or clarity. Avoid using events with the following characteristics:

  * **Limited coverage:** The event is triggered by only a small subset of users.
  * **Infrequent or inconsistent:** The event does not repeat reliably across days or within a short time window.
  * \*\*Irregular timing: \*\*The event does not occur consistently throughout the week.
  * \*\*Ambiguous or continuous signals: \*\*The event is not a clearly defined action and may represent a state rather than a behavior.
  * \*\*Too sparse or low signal: \*\*The event does not occur often enough to provide meaningful learning, or does not reflect meaningful user intent.

  <Info>
    If you need more specifics or deep dive into Target events, please reach out to your Customer Success Manager.
  </Info>
</Accordion>


# Sign In to Aampe
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-signin

This will be a day to remember!

## Accept the Invitation

Aampe will send an email to the first user of each account inviting them to join Aampe as an admin.

Follow the instructions in the email to accept the invitation by creating an account along with a username and password.\
\
Then invite your colleagues, as needed.

## Invite Colleagues

Follow the instructions [here](/user-guide/using-aampe/admin/users-and-roles) to invite other users and manage roles.


# Surfaces
Source: https://kb.aampe.com/user-guide/using-aampe/quickstart/quickstart-surfaces

Surfaces bring agentic infrastructure directly to your app or website.

## What Are Surfaces?

Rather than showing every user the same content, Surfaces enable agents to personalize the language, imagery, and layout of your app or website.

<img alt="Surfaces Demo Example Pn" />

In this example, 4 different users log into a fitness app. Surfaces adapts the subtitle so that each user sees language that speaks to their motives.

* Aisha wants to live a healthy and pain-free life
* Claire is motivated by setting and achieving goals
* Ben finds joy in social connection and teamwork
* Malik likes the app's science-based approach to exercise

Aampe agents test and select different variants over time to help your business meet its goals. As users engage with this and other Aampe-powered content, agents learn which experiences resonate best with each individual.

## Where Can I Use Surfaces?

Surfaces allow you to dynamically influence any logged-in experience that can call the Aampe Content API. Common use cases include

* App headers, slogans, greetings, and other text snippets
* Website images, colors, or specific creative assets
* Pop-up content cards, sliders, carousels
* Layout, ranking, and overall organization of screen content

Surfaces aren’t limited to apps and websites. As long as you know the user and can call an API on their behalf, you can make use of Surfaces. Additional use cases include

* Inserting Aampe's dynamic content into custom messaging applications
* Simulating Aampe recommendations offline

## How Do Surfaces Integrate with My App/Website?

There are three commonly-used ways of leveraging the Surfaces API.

* **Direct integration:** Call the Aampe API from within your application
* **Third-party tools:** If you're using a tool like Braze to manage pop-ups, you can call the Surfaces API from within that tool
* **Batch and save:** Write a script to call the Surfaces API and save the results in a convenient place for your app, offline analysis, or any other use case

Check out our [developer guide](/developer-guide/surfaces/surfaces-embed) for instructions on how to connect your application to Aampe Surfaces.

## How Do Surfaces Work with Messages?

When Messages and Surfaces share common labels, the insights from one are automatically shared with the other.

* Every push notification, email, and text message works to identify the offerings and value propositions that resonate with each user. These insights help improve the user experience when users log into your app or website.
* With Surfaces, every page load, scroll, and purchase is measured against the app/website experience to further refine the content that motivates each user. These insights are automatically leveraged to improve every outbound communication.

## Ready to start?

The first step in connecting Aampe to your app or website is to [prepare your content](/user-guide/using-aampe/product-surfaces/surfaces-content).

## Surfaces FAQs

<Accordion title="Which web/app frameworks does Aampe support for Surfaces? " icon="sparkles">
  You can integrate Aampe surfaces with any platform that can make an API call. Often these are apps and websites but any customer interaction that you're able to label and monitor is a potential use case for surfaces.
</Accordion>

<Accordion title="How fast is a call to the Surfaces API?" icon="sparkles">
  We hold ourselves to a P95 latency of 150ms or less for API calls from the same geographic region. [Read more about Surface performance.](/developer-guide/surfaces/surfaces-embed-advanced) 
</Accordion>

<Accordion title="What happens if the Surface API fails? " icon="sparkles">
  We recommend customers integrate Surfaces with a hard timeout and fallback content. If the Surfaces API fails for any reason, the user will have the default experience. [Read more about implementing fallback content.](/developer-guide/surfaces/surfaces-embed-advanced) 
</Accordion>

<Accordion title="Will Surface content update in real time with customer site activity?" icon="sparkles">
  If you are [sending customer events to Aampe in real time](/developer-guide/data-ingest/data-sources/streaming-aampe-api), users can quickly move in and out of audiences so as to receive contextually appropriate content. \
  \
  You can also apply your own business logic to the content returned by the Surfaces API to ensure content updates immediately. (e.g. ask for the top 5 messages and filter out messages on certain topics if the member has already converted). 
</Accordion>

<Accordion title="Can I ensure the Surfaces API sends words that match the accompanying imagery?" icon="sparkles">
  Yes. If you want messages about chairs to accompany picture of a chair, you can [link the labels](/user-guide/using-aampe/tips-and-tricks/label-locking) while creating the message. You can also upload a [dataset](/user-guide/using-aampe/tips-and-tricks/datasets) that places the preferred image for each message. 
</Accordion>


# Copy & Paste from Google Sheets
Source: https://kb.aampe.com/user-guide/using-aampe/tips-and-tricks/copy-paste

Seamlessly transfer content from Sheets into Aampe

<iframe title="Loom video player" />

If you're using Google Sheets to create, edit and maintain your content catalog, it's very easy to copy from your sheet into the Aampe composer. Here's how to do it:

1. Make sure your content in sheets is set up in the right format. For a push notification with a Header and a Body, it should look something like this:

   <img alt="Template Paste Pn" />
2. Create a new message in Aampe

   <img alt="Create Message Pn" />
3. Add the base alternates (the first alternate for each component) and set up all your components in the right order

   <img alt="Messagecreationinterface Pn" />
4. Make sure the labels you're about to use already exist in the Aampe Composer. Double check for spelling and capitalization mismatches (if the labels don't match, only your alternates will get copied and you will need to relabel them manually)
5. If you choose to copy each component one by one, select the component table in the sheet, hit "Copy"

   <img alt="Greeting Pn" title="Greeting Pn" />

   \
   Then go to your Aampe message editor, click on the component you want to paste in, then click "Paste"

   <img alt="Paste1 Pn" />
6. If you want to copy the full message in one go, copy the entire message in the sheet

   <img alt="Copy All Pn" />

   \
   Then go to the **Alternates** tab in your message, and click the "Paste" icon on the top right corner

   <img alt="Paste All Pn" />

And that's it! All your content should get pasted in.

Need help? Use this [sample template](https://docs.google.com/spreadsheets/d/13RIiiRseMmYjpYDiGMqC18NtYRyL9tZnXr7mFe2rkwA/edit?usp=sharing) to practice, or reach out to our Customer Success team.


# Bulk Content Management with Datasets
Source: https://kb.aampe.com/user-guide/using-aampe/tips-and-tricks/datasets

When dealing with a large number of message inputs, save time with an Aampe dataset

<iframe title="YouTube video player" />

## What Is a Dataset?

Datasets are a way to upload and manage content components in bulk. Once a dataset is created, the components can be referenced in any message where the dataset is selected.

Content in a dataset changes infrequently. For real-time message-content, consider [integrating your CMS](/user-guide/using-aampe/quickstart/quickstart-cms).

## When Should I Use Datasets?

Datasets in Aampe are a way of managing messages with a large number of specific inputs. They are also helpful when managing combinations of message components

* Your message directs users to one of many blog articles. Each variant includes the article title and the corresponding url.
* You want to refer to, say, a **city** and **state** together in a message. Obviously these inputs can't be combined arbitrarily. Datasets will ensure separate column values only appear together.

## How To Create a Dataset

Within the composer, **Message Settings > Datasets**

* Click **Create Dataset**

<img alt="Dataset Create Pn" />

This will present you with two options

* Create a dataset in Aampe
* Upload a CSV

### Create a Dataset in Aampe

This option is ok for smaller datasets.

* Specify the columns, add values, and insert each new row
* Save

### Upload a CSV

This option is ideal for larger datasets

* Upload the csv
* Inspect the results and save

## How To Use Datasets In a Message

Once a dataset has been created you can add any subset of that dataset to a message.

* When creating a new message, click the Dataset icon near the bottom of the content panel

<img alt="Add Dataset To Message Pn" />

* Choose the dataset you wish to add

<img alt="Select Dataset Pn" />

* Filter down to the specific rows you want to include. Click **Add**.

<img alt="Filter Dataset Pn" />

* To insert elements from the chosen dataset rows into the message, click the dataset icon

<img alt="Insert Dataset Column In Message Pn" />

* Select a column to include in the message

<img alt="Choose Column Pn" />

* The message will now have a variant for every row in the dataset. You can create additional variants by adding message components. You can also add other columns in the dataset.

<img alt="Message With Dataset Added Pn" />

Nice work! You saved a lot of time by using Aampe Datasets to power your content library.

## Advanced Dataset Features

## Alternates and Labels

Dataset Labels let you designate columns within a dataset as **Alternates** and apply corresponding **Labels**, so they can be included in agent learning. This unlocks insights from dataset-driven content, bringing it into learning and analytics.

### **How to create a Dataset with labels**

<img alt="Adding A Label Column" />

* Within a dataset, open the **Dataset Actions** menu and select **Assign Component Type**.
* Choose a **Component type** and select the column you want to use as **Alternates**.
  * If you already have a column containing Labels for those Alternates, select it here.
  * Otherwise, you have the option to add a blank column.
  * *Note: Only existing Component Types and Labels can be used.*

Once configured, the Alternate and Label columns are grouped together. You can assign or modify Labels either manually or by bulk-selecting rows and applying Labels.

<img alt="Modify Labels" />

### **Using Dataset Labels in Messages**

Including dataset content in a message continues as usual.

<img alt="Use In Message" />

* If a dataset is updated, any Messages using that dataset are updated automatically.
* Labels applied to dataset Alternates are visible wherever those Alternates appear in Messages.

This ensures that dataset-driven content stays consistent across your system.

<Warning>
  **Important Considerations when using labels in datasets**

  * If a Label on a dataset Alternate is changed, the change applies everywhere that Alternate is used.
  * A dataset column must have a Component Type assigned before Labels can be applied to its cells.
  * If you unassign a Component Type from a dataset field that’s already being used within Live messages, agents will stop learning on those fields. This can affect how agents choose to schedule or send these Messages.

  This shared behaviour ensures consistency, but also means changes should be made thoughtfully.
</Warning>

## Start and End Dates

If a dataset contains columns named `start_date` and `end_date`, the message will only send within that date window.

Suppose you want to start sending messages one or two days ahead of a holiday. Your dataset would look like the following.

```text theme={null}
name, start_date, end_date
Canadian Thanksgiving, 13/10/2025, 13/10/2025
American Thanksgiving, 25/11/2025, 27/11/2025
```

Note the DD/MM/YYYY date formatting. Any other date formats will fail. \
\
Connect your message to the dataset as shown above and bring elements into the message text.

```text theme={null}
Happy {dataset.name}!
```

Aampe agents would send message variants with "Happy Canadian Thanksgiving!" on Oct 13. On the dates between Nov 25 and Nov 27 (inclusive), agents would send messages with "Happy American Thanksgiving!"


# Syncing Labels for Repeating Components
Source: https://kb.aampe.com/user-guide/using-aampe/tips-and-tricks/label-locking

Ensuring labels remain in sync when components repeat in a message

Aampe allows you to use the **same component more than once** within a single message—for example, a Greeting in both the Header and Body, or a Value Proposition used in both the subject line and title of an email.

While this is not recommended and should only be done with intention, we can ensure the message remains consistent by keeping the labels synced across repeated components. This is done using a feature known as **Label Sync**.

Label Sync is an optional feature that ensures repeated components stay aligned in how they use labels and alternates.

> Note: When you repeat components in a message, labels are always synced **by default**.

## **Why Label Sync Matters**

Using the same component twice can introduce ambiguity for agents if not managed correctly. Imagine you have a message with two Greetings. Without syncing, an agent may send a message in which:

* Greeting 1 uses label `Friendly`
* Greeting 2 uses label `Professional`

  The agent would then struggle to understand whether the Greeting Label `Friendly` or `Professional` drove user behavior

Label Sync prevents this by turning labels into **coherent tracks** — `Casual` alternates always appear together; `Professional` alternates always appear together.

## When should I Sync Labels?

Here are some examples of when syncing labels makes sense:

* **When using the same discount throughout the message** — e.g., when “10% off” appears in two places (subject line + body) and must always match.
* **When you're talking about the same Offering** — e.g., if your email is about “Hotels” you don't want to mention “Flights” out of the blue
* **To keep Tone consistent** — e.g., you don't want to sound Casual in the header but Professional in the body

## Why am I seeing this error?

When you add the same component twice in a message, you may end up seeing an error like this (below) in your editor. Don't panic — here's why it happened, and how you can fix it.

<img alt="Lockerror Pn" />

When components are repeated in the same message, by default they are synced in the UI. This means the system is expecting both components to share the same set of labels. When this doesn't happen, you see this error.

### How you can fix this

1. **Turn off label sync** \
   Click on the lock icon on the bottom right. This will mean agents are now free to mix and match all alternates within both components, across all labels. The components may or may not share the same labels.
2. **Ensure both components have the same labels**\
   If you want to keep label sync on and remove the error, make sure both components are using the same set of labels. For example:\
   \
   Greeting 1 has labels Friendly and Professional\
   Greeting 2 has labels Quirky and Professional\
   \
   You can either 👉 \
   (A) Remove Friendly and Quirky from both Greetings\
   (B) Add Friendly to Greeting 2 and add Quirky to Greeting 1 \
   (C) Replace Quirky in Greeting 2 with Friendly


# Create Variety by Rearranging Components
Source: https://kb.aampe.com/user-guide/using-aampe/tips-and-tricks/rearrange-components

Quickly create variations of the same message without changing copy

One of the fastest ways to scale your message library in Aampe—without writing entirely new content—is to **reorder, omit, or swap components**. Because Aampe messages are modular, every component (Greeting, Value Proposition, Offering, Incentive, CTA, etc.) can be rearranged to test new hypotheses with minimal effort.

This technique is especially useful early on, when you are still exploring ways to give your agents more variations to speak to different types of users. It also multiplies the number of learnable variants your agents can test, dramatically increasing speed to insights.

<img alt="Swapcomp Pn" />

## **Why this matters**

Different users respond to different kinds of content. Some prefer a Value Proposition upfront, others respond more when the Offering leads. Some engage best when the CTA appears earlier, and some prefer not to be explicitly told what to do (i.e. messages without a CTA!)

## **Ways to add variety quickly**

* Move components between Header and Body, or other sections
* Lead with different components (Offering-first, Incentive-first, Value Proposition–first)
* Omit optional components like Incentives or CTAs to create softer variants
* Switch between short structures and more descriptive ones
* Reorder components for slightly different reading flows and sentence structures

These small adjustments dramatically increase the number of combinations agents can personalize with

## **Things to keep in mind**

* Keep each message **single-focus** to preserve clean learnability

  (avoid multiple Value Propositions or multiple Offerings in the same message)
* Ensure each component works even if another is omitted
* Start simple — 2–3 components per message is enough to create large variety


# Why Aampe Agents Learn from Events, Not Attributes
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/agent-help/events-vs-attributes

Causation vs correlation

# Events vs Attributes

Aampe's agents treat every message as an experiment, building causal understanding from events over time rather than statistical guesses from static attributes.

## Observation vs. Intervention

Typical ML systems learn by observing correlations in attributes, past behaviors, and demographics. The problem is that none of this tells you what *caused* anything. It's information without a decision advantage.

Aampe's agents aren't guessing what's likely—they're changing what happens. Every agent intervenes in a user's behavioral stream, then measures how that intervention alters what follows. That change is what the agent learns from.

Attributes like age or device type don't change fast or cleanly enough to provide that signal. Events are timestamped and tied to specific moments before and after an agent acts. That temporal structure makes them the only reliable substrate for causal learning.

## The Logic of Events

An event stream tells a story over time. When an agent intervenes, it inserts a new chapter. The question isn't "Did something happen after I acted?" The question is "Did what happened differ from what would have happened anyway?"

Aampe agents use difference-in-differences reasoning. Each maintains a baseline of normal behavior for its user. When the agent acts, it measures deviation from that baseline. If the deviation exceeds normal fluctuation, the agent infers its action likely caused the change. This structure—observing before, intervening, measuring after—separates coincidence from consequence.

## Why Attributes Fall Short

Predictive models built on attributes operate entirely in correlation. They can tell you that people with certain traits are more likely to convert, but not whether your message caused that response. Knowing someone probably *will* convert doesn't tell you what to *do*.

Attributes also create structural confounds. Geography might correlate with conversion while the true driver is pricing. Device type might stand in for connection speed. Many attributes are proxies for unmeasured factors, and their meaning shifts over time. Without interventions and time-based events, attribute-driven models can predict probabilities but can't guide decisions.

## Many "Attributes" Are Really Events

Much of what teams call attributes are compressed event histories. A "new user" flag points to a specific moment—the first app open. A "high-value user" label summarizes recent purchases. Even a geography change is an event.

Flattening events into attributes erases the timeline that gave them meaning. Events keep temporal structure intact, letting agents measure cause and effect rather than just noting that a change exists.

## Attributes as Boundaries, Not Training Data

Attributes still matter—as constraints, not learning inputs. If content exists only in Spanish, there's no point testing whether English speakers respond. Language preference serves as an eligibility gate before learning begins.

The same applies to geography for location-dependent offers, device type for message formats, and subscription tier for content gating. Attributes narrow the action space to what's possible. Business logic lives in attributes; behavioral learning lives in the event stream.

## Why Attribute-Based Learning Would Fail

Training on attributes would mean freezing users into buckets like "likely buyer" and assuming the same action works for everyone in that bucket. A clothing app targeting all "high income" users with premium products ignores that income isn't intent. A fitness app pushing yoga to everyone over 40 misses that some run marathons. Attributes enable correlation, not reasoning. Personalization dies when the system stops testing what works for each person.

## Intervention Is Ground Truth

Aampe's architecture assumes intelligence lies in acting and observing what happens, not passively summarizing data. The agent doesn't need demographics or clusters; it needs to know whether *this action* moved the needle for *this person* at *this moment*.

Events make that possible. Attributes describe users; events describe change. Only by measuring change can a system learn to make better choices.


# Aampe Agents: One Model Per User
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/agents

Once your content is live with Aampe, your agents begin a continuous cycle of learning. 

## The Modern Approach: Individual AI Agents

In traditional machine learning, companies build one massive model to serve millions of users. Aampe takes a fundamentally different approach: **every user gets their own dedicated AI agent**.

This isn't just a technical difference, it's a paradigm shift that unlocks truly personalized experiences at scale.

## Why One Model Per User Changes Everything

Most personalization systems work by training one large model on all user data, finding patterns that work "on average" across user segments, then applying the same logic to everyone in a segment. The result? Messages optimized for imaginary "average users" that don't actually exist.

With Aampe, each user gets their own AI agent that learns exclusively from their behavior, makes personalized decisions based on their unique preferences, and continuously adapts as their interests evolve over time.

## How Individual Agents Work

When a new user enters your system, Aampe automatically creates a dedicated AI agent for them. This agent starts learning from their very first interaction, observing only their user's actions like app engagement patterns, message interaction history, purchase behaviors, and timing preferences.

The agent continuously optimizes four key dimensions for their specific user

* Content
* Timing
* Frequency
* Channel

Each agent follows a continuous cycle: observe user behavior, learn and update personal preferences, decide on optimal message and timing, deliver the personalized experience, then measure the outcome and feed it back into learning.

## Business Impact of Individual Agents

This approach delivers unprecedented personalization with higher click-through rates from relevant content, increased engagement from optimal timing, and reduced unsubscribes through frequency optimization.

Operationally, this means

* Automated personalization at scale
* Self-optimizing system that improves over time
* No manual segment management required

## The Future of Personalization

Individual AI agents represent the next evolution in personalization technology. Instead of trying to predict what groups of people want, we give each person their own AI assistant that truly understands their unique preferences.

Ready to see how individual agents can transform your user engagement? Explore how agents use [labels](/user-guide/welcome-to-aampe/how-does-aampe-work/labels) to quickly optimize across millions of messages, or read up on the [explore/exploit strategies](/user-guide/welcome-to-aampe/how-does-aampe-work/explore-exploit) agents use to balance learning with performance.

## Agent FAQs

<Accordion title="Are Aampe agents built on LLMs?" icon="sparkles">
  Aampe agents are not based on LLMs. They are tiny causal-inference machines. 

  LLMs are helpful for creating content and are increasingly a part of the Aampe front-end, but the brain of the agent is not a language model. It's a statistical model, which is fitting because an agent's goal is to look at user data and determine which messages are effective.
</Accordion>

<Accordion title="How do agents learn?" icon="sparkles">
  Aampe agents take action with a goal of influencing user behavior. To know if a message was effective, an agent

  * makes a forecast of expected behavior (without a message)
  * sends the message
  * observes the behavior as it really happened (with a message)

  Agents estimate the impact of the message by comparing the observed behavior with the forecast. The agents then update the internal weights for each label associated with the message, which improves the content and timing of future messages. 

  [Read a more detailed explanation of why Aampe agents measure the impact of their interventions using events instead of user attributes.](/user-guide/welcome-to-aampe/how-does-aampe-work/agent-help/events-vs-attributes)
</Accordion>

<Accordion title="What measures are in place to mitigate algorithmic bias in personalization?" icon="sparkles">
  Algorithmic bias often arises when systems generalize insights from a majority population and applies them to minority populations. This happens because traditional machine learning models tend to optimize for statistical averages across broad populations, reinforcing dominant patterns while neglecting individual variations. \
  \
  Aampe's agentic infrastructure avoids this by treating each user as a unique context, learning directly from individual behavior rather than aggregating across groups. With Thompson sampling over networked action sets, the system experiments and adapts at the individual level, ensuring that decisions reflect personal preferences rather than majority-driven trends, thereby reducing the structural basis for discrimination and bias.
</Accordion>

<Accordion title="My company has multiple brands, should they have separate Aampe accounts?" icon="sparkles">
  Maybe! Here are some things to consider...

  * Do the brands have distinct customer bases? 
  * Is it important to cross-sell between brands? 

  With a shared account, agents are aware of all outbound messages. If they just sent a message for Brand A, they will likely wait before sending another message - possibly for Brand B. You share customer touchpoints across brands, which could be a good move for the right company. \
  \
  With separate accounts, a single customer that subscribes to multiple brands will receive messages from multiple agents. The agents cannot coordinate, so it's possible (though unlikely) that they all send messages at the same time. 
</Accordion>


# Components and Labels
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/component_and_labels

The building blocks for Aampe content

## Components

When writing messages, we choose what to say and how to say it, then craft a message accordingly. Take a look at this sample message.

<img alt="Sample Message 1 Pn" />

Any message usually contains multiple components: greetings, value propositions, product or feature offerings, incentives, calls to action, and so forth.

<img alt="Messagewith Components Pn" />

### Why use Components?

Traditional messaging requires writing separate messages for each user type. With components, you write variations of each message part, then let agents combine them to create thousands of unique messages.

For example, instead of writing 10,000 complete messages, you might create:

* 5 greeting variations
* 8 value proposition variations
* 6 offering variations
* 4 call-to-action variations

This creates 960 possible message combinations (5×8×6×4) that agents can test and optimize for individual users. So, what you're writing is not one message, but a group of messages made up of different combinations of alternates. We call these message groups on Aampe.

### How Agents Use Components

Agents test different component combinations to discover what resonates with each user. One user might respond to urgent greetings with discount offers, while another prefers casual greetings with convenience messaging.

Each component combination becomes a learning opportunity. Agents track which combinations drive engagement and conversions for their specific user, then optimize future messages accordingly.

### Component Best Practices

**Include key components in every message.** We recommend adding an Offering and Value Proposition to establish clear purpose and benefit.

**Avoid multiple components of the same type per message.** Using two value propositions makes it impossible for agents to learn which one drove user response.

**Create meaningful variations.** Each component alternate should offer a distinctly different approach, tone, or focus to give agents genuine testing options.

## Labels

Labels are semantic tags that describe what each component represents. They enable agents to learn patterns across different messages and apply successful strategies to new content.

Without labels, agents see each message as completely unique. With labels, agents can learn that a user responds to "urgent" messaging or "discount" offers, then apply this learning to new messages with similar labels.

<img alt="Labels Pn" />

Much like tags on music or video content, labels help the system understand content characteristics and user preferences at a deeper level than individual songs or videos.

Within Aampe, you can create any group of labels you like. We also offer several common label groups by default.

### **Offering**

What you're promoting—products, features, services, or destinations. Examples include "Flights," "Hotels," "Food Delivery," or "Premium Features."

> **Let's do a quick exercise**
>
> Look through your app or product and try to list down your unique offerings. Hint: usually these are the different destinations, tabs or pages on your app.

### <Tooltip>Value Proposition</Tooltip>

Why users should care, focused on core human values rather than product features.

| **Value** | **Description** | **Copy Example** |
| - | - | - |
| Convenience | Making things easy, quick, and hassle-free for users. | "Get what you need, when you need it—effortlessly." |
| Trust | Ensuring reliability, honesty, and integrity in all interactions. | "Built on trust, designed for you." |
| Personalization | Tailoring products, services, or experiences to individual needs. | "Tailor-made just for you—because one size doesn't fit all." |
| Affordability | Ensuring users get value for money with budget-friendly options. | "Great experiences shouldn't break the bank." |
| Quality | Delivering excellence, durability, and high standards in products and services. | "Excellence you can see, feel, and trust." |
| Control | Giving users the ability to manage their experience and outcomes. | "Take charge—you're in full control of every step." |

**Important:** Value propositions should reflect user benefits, not product features. "Instant Delivery" (product feature) vs "Convenience" (user benefit).

### Incentive

How you sweeten the deal to encourage action. Examples include "Percentage Discount," "Dollar Discount," "Free Trial," or "Free Delivery."

Examples of Incentive Labels:

| **Incentive** | **Description** | **Copy Examples** |
| :- | :- | :- |
| Percentage Discount | Offers a % off the price. | "Save 20% on your next order" |
| Dollar Discount | Offers a fixed amount off. | "Enjoy \$10 off your first purchase" |
| Free Trial | Allows users to try before committing. | "Try it free for 30 days—no credit card required!" |
| Free Delivery | Eliminates delivery costs. | "Enjoy free delivery on all orders over \$50!" |

### Greeting

How you grab attention and open the conversation. Examples include "Direct," "Curious," "Question," "Contextual," or "Celebratory."

Examples of Greeting Labels:

| **Greeting** | **Description** | **Copy Example** |
| :- | :- | :- |
| Direct | A widely used, general opener. | "Hey there!" "Hi" |
| Curious | Uses intrigue or a teaser to grab attention. | "Guess what?" "Did you know?" |
| Question | Sparks curiosity by starting with a question. | "Did you know you have a surprise waiting?" |
| Contextual | Acknowledges past activity or context. | "Welcome back! Let's pick up where you left off." |
| Celebratory | Highlights achievements or milestones. | "Congrats! You just unlocked something." |

### Call to Action

How you encourage user action. Examples include "Directive," "Encouraging," "Exploratory," "Social," or "Contextual."

Examples of Call to Action Labels:

| **Call to action** | **Description** | **Copy Examples** |
| :- | :- | :- |
| Directive | Directs users to purchase, subscribe, or commit. | "Subscribe now" |
| Encouraging | Motivates the user to take action with confidence. | "Get started" "Go for it!" "Take the next step" |
| Exploratory | Encourages browsing or discovery. | "Check out our latest features!" "Explore more" "Dive in" |
| Social | Invites users to join or engage socially. | "Join our growing community today!" |
| Contextual | Acknowledges past activity or context. | "Don't forget—complete your setup today!" |

### Tone

The communication style and voice. Examples include "Casual," "Friendly," "Professional," "Reassuring," or "Playful."

Example of Tone Labels:

| **Tone** | **Description** | **Copy Examples** |
| :- | :- | :- |
| Casual | Relaxed and conversational. | "Hey! Thought you'd love this—check it out!" |
| Friendly | Warm and inviting. | "We're so glad you're here! Let's get started." |
| Professional | Clear, polished, and business-like. | "Here's everything you need to know about your account." |
| Reassuring | Builds confidence and credibility. | "Your security is our top priority. Here's how we protect you." |
| Playful | Lighthearted, fun, and sometimes humorous. | "You + this deal = a match made in heaven. ❤" |

### Other

The Other component is for adding variation to anything that doesn't fit into any of the other buckets. Most customers use the Other component to do things like experiment with different emojis.

### Custom Components

Create custom components when your message includes distinct elements that don't fit standard categories. Examples might include "Music Genre," "Cuisine Type," or "Sub-features."

Custom components follow the same rules: distinct alternates with clear, non-overlapping labels that function as modular building blocks.

Use custom components when you need to track performance on unique message aspects or experiment with specialized personalization patterns.

**Best Practices:**

* Avoid creating Custom Components that overlap with existing ones
* Make sure the labels are broad enough to be used in tandem with other components & their labels
* Use consistent labeling to ensure agents can learn effectively

**Examples:**

* **Component: Music Genre**\
  *Labels:* Indie, Hip-hop, Jazz, Pop, Classical
* **Component: Cuisine Type**\
  *Labels:* Italian, Mexican, Thai, Indian, Chinese
* **Component: Sub-features**

  *Labels:* Dashboard, Notifications, Payments, Account Settings, History, Wishlist

## Getting Started

Start with core components that align with your business model and user journey. Focus on creating 3-5 meaningful variations for each component type rather than trying to cover every possibility.

Work with the Aampe team during onboarding to define value propositions that reflect genuine user motivations rather than product features. This foundational work pays off with faster agent learning.

Remember that agents need time to test combinations and learn patterns. Start simple, then expand your component library as you see which approaches work best with your audience.

<Info>
  For more information and Best Practices, check out our [Content Playbook](https://www.figma.com/deck/NmmJFEgoNxsydyaT9Pdv1k/-Shared--Content-Playbook-%7C-aampe?node-id=740-223\&t=ilniAo9WOyqY0UW6-1)
</Info>


# Building a Content Catalog
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/content_catalog



Unlike traditional campaign-based messaging, where each message is tied to a specific event or lifecycle stage, Aampe works differently. Every user has a dedicated agent that learns what resonates by exploring combinations of content over time. Your job is to build a rich catalog for those agents to explore.

### 💍 Getting Married on the First Date?

Think of your content catalog like a relationship-building toolkit.

You wouldn’t ask someone to marry you on a first date. It’s not just bad timing—you simply don’t know enough about the person yet. Do your values align? Are you compatible? What do they care about?

It’s the same with your users. When someone opens your app for the first time, it’s not the right moment to push them to “upgrade now” or “buy premium.” They’re still figuring out if your app fits into their life—and what kind of value it offers *them*.

### 🧠 Why a Content Catalog Matters

Your app likely delivers different kinds of value to different users. Some need **social proof**, others care about **flexibility**, **features**, or **affordability**. The challenge? You don’t know which value matters to which user upfront—and in a traditional system, you can’t create or test enough variations to find out.

That’s where Aampe comes in. Every user has a dedicated agent that learns what works by testing and adapting over time. To do this, your agents need **volume and variety**.

A content catalog gives your agents a modular playground to:

* Experiment with different messages
* Personalize based on real behavior
* Build trust and engagement over time

Just like a real relationship—one message at a time.

### 🔄 Moving Beyond Lifecycle Stages

In traditional CRM, we plan messages based on lifecycle stages—onboarding, activation, retention, etc. But in reality, user behavior rarely follows a clean funnel.

That’s why Aampe doesn’t rely on rigid stages. It responds to **signals**, not assumptions.

Yes, a welcome message makes sense for new users—but a feature tip or testimonial could be relevant anytime. With a good content catalog, your agents can adapt the message to the moment.

***

### 🧠 From Static Strategy to Adaptive Content

As marketers and content teams, we’re used to building static strategies. We A/B test two variants, pick a winner, and roll it out. But what’s right for one segment might flop for another—and by the time your test is over, your users have already changed.

With Aampe, you move from “winner-takes-all” to **continuous learning**. Your strategy becomes dynamic. Your content becomes modular. And your agents adapt on the fly.

***

### 🎨 Limitless Creativity, Structured for Scale

This isn’t about writing more. It’s about writing *smarter*:

* Use **components** (Value Propositions, Offerings, CTAs, etc.)
* Create multiple **alternates** per label
* Make each alternate **single-focused** and mixable

The result? A scalable content system that lets you try different tones, styles, formats, and value angles—without rewriting entire messages every time.

<img alt="Catalog Pn" />

### 📚 What Goes Into a Content Catalog?

Start with a mix of message types, like:

#### 🧠 **Tips & Tricks**

* “Did you know?” nudges
* Feature walkthroughs
* Power user tips

#### 📘 **Educational Content**

* FAQs and how-tos
* Blog summaries
* Onboarding help

#### 💬 **Social Proof**

* App store reviews
* User testimonials
* Community milestones

#### 📦 **Feature Highlights**

* What’s new
* Deep dives
* Use case callouts

#### 🛒 **Standard Campaigns**

* Welcome series
* Cart abandonment
* Promotional nudges
* Upgrade prompts

***

### ✅ Final Tip

Don’t build one message. Build a **system**.

Your catalog should be modular, labeled, and designed for experimentation. With enough variety, your agents will do the heavy lifting—delivering the right message to the right user at the right moment.

Think of it as giving every user a personalized conversation—and letting it evolve over time.


# Explore vs Exploit
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/explore-exploit

How Aampe Agents Balance Learning and Performance

## The Fundamental AI Dilemma

Every AI system faces a critical challenge: **Should I do what I know works, or should I try something new to potentially discover something better?**

This is the explore/exploit tradeoff, and how it's solved determines whether an AI system stays static or continuously improves. Aampe agents have mastered this balance, enabling them to deliver immediate business value while constantly discovering new ways to engage users.

## Understanding Explore vs Exploit

**Exploitation** means leveraging existing knowledge to maximize immediate results by sending messages with historically successful label combinations, using proven timing patterns, and focusing on strategies that deliver predictable outcomes. **Exploration** means testing new approaches to potentially find better solutions by trying untested label combinations, experimenting with different timing patterns, and risking short-term performance for long-term learning.

Pure exploitation leads to stagnant performance and missed opportunities as the system never finds better approaches and fails to adapt as user preferences change. Pure exploration causes poor immediate performance and user frustration through constantly trying unproven approaches while ignoring known successful strategies.

## How Aampe Agents Manage the Tradeoff

Aampe agents dynamically balance exploration and exploitation based on confidence levels. In high-confidence scenarios with well-established user preferences and large amounts of historical data, agents favor exploitation. In low-confidence scenarios with new users, conflicting behavioral signals, or long periods without testing, agents increase exploration.

Each agent treats message selection like a multi-armed bandit problem, where different strategies are "arms" with varying reward rates. If an agent discovers a user responds well to urgent discount messages with a 70% open rate, it might send 70% of messages with this combination while testing other approaches 30% of the time. If a new combination shows promise, the agent increases its allocation accordingly.

## Real-World Applications

Consider an e-commerce example where a user historically clicks on electronics deals. The agent's exploitation strategy focuses on electronics promotions using proven subject lines and timing. The exploration strategy occasionally tests home goods recommendations with different formats and timing variations. Through exploration, the agent might discover the user engages with home goods during weekend mornings, leading to an adapted strategy that includes home goods on weekends while maintaining electronics focus for weekdays.

## Business Impact of Intelligent Explore/Exploit

This approach delivers immediate value from day one as agents start with reasonable baseline strategies and exploit obvious patterns while learning subtle ones. The system provides continuous improvement by discovering better strategies over time, automatically adapting to changing user preferences, and finding novel approaches that humans might miss.

Risk is managed through controlled experimentation within safe boundaries, fallback strategies that return to known winners if experiments fail, and gradual transitions between strategies as learning accumulates.

## The Competitive Advantage

Traditional A/B testing requires testing one thing at a time, waiting for statistical significance, applying results broadly across users, and manual iteration. Aampe's explore/exploit approach enables testing multiple strategies simultaneously per user with continuous statistical learning, individual optimization, and automated discovery and adaptation.

This results in faster optimization than traditional methods, personalized learning rather than segment-based insights, continuous adaptation to changing preferences, and automated intelligence that scales with your user base.

## Getting Started with Explore/Exploit

Define your risk tolerance with exploration rates between 10-40% based on your comfort level. Set success metrics like click-through rates or revenue per message. Monitor discovery rates of new strategies and performance stability during exploration.

Most importantly, trust the process. Allow agents to learn and focus on long-term trends rather than short-term changes.

## The Future of Adaptive AI

The explore/exploit tradeoff isn't just a technical feature—it's what makes AI truly intelligent. By continuously balancing learning with performance, Aampe agents ensure your messaging gets smarter every day, automatically adapting to your users' evolving preferences while delivering consistent business results.

This is how AI should work: **intelligent enough to improve itself, reliable enough to trust with your business.**

***


# How Labels Work
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/how-does-aampe-work/labels

Abstracting messages into learnable concepts

## Learning from Millions of Unique Messages

Imagine trying to personalize messaging when you have thousands of different message variants, each with unique copy, images, offers, and calls-to-action. How can an AI agent learn what works for each user when every message is completely different?

**Labels solve this fundamental challenge** by abstracting millions of unique messages into a small set of learnable concepts that agents can experiment with and optimize.

## What Are Labels?

Labels are conceptual tags that describe the key characteristics of your messages. Instead of trying to learn from raw message content, agents learn which types of message concepts resonate with each user. Examples include tone (casual, urgent, friendly), value proposition (discount, new feature, social proof), call-to-action (shop now, learn more, try free), and urgency level (high, medium, low).

## How Labels Enable Learning

Without labels, an agent sees hundreds of completely different messages about sneaker sales. With labels, the agent just sees \[value, fomo, performance, fashion]. This dramatically simplifies the learning problem, and the agent can quickly identify the labels that align with its user.

Labels allow agents to identify successful patterns across different message variations, generalize learnings to new messages with similar label combinations, make predictions about which label combinations will work best, and optimize systematically rather than randomly.

## The Label-Agent Learning Loop

Every message gets tagged with relevant labels when created through automated content analysis or manual tagging. Each agent then tests different label combinations, observes user responses, and builds personal preference profiles. Agents identify which labels drive engagement, learning patterns like "user responds to urgent plus discount combinations" or "user prefers educational content over promotional."

When sending new messages, agents choose based on learned label preferences, prioritizing messages with high-performing label combinations while avoiding patterns that historically underperformed and balancing exploration of new patterns with exploitation of known winners.

## The Power of Label Combinations

Agents don't just learn individual labels—they learn combinations that work. One user might respond to \[urgent + discount + shop\_now + evening] while another prefers \[educational + new\_feature + learn\_more + morning]. As user preferences evolve, agents dynamically adjust their label preferences, perhaps shifting from promotional to educational content or changing timing preferences over time.

## Business Benefits of Labels

Labels provide a systematic approach to message creation and testing with reusable insights across campaigns. They enable deeper user understanding through behavioral profiles and drive efficient optimization with:

* Faster learning through concept abstraction
* Better predictions for new message performance
* Reduced testing time through intelligent combinations

## Labels in Action: A Real Example

An e-commerce company sends hundreds of product promotion messages. Different products, discounts, urgency levels, and tones. Instead of treating each message as unique, they label them.

A message like "Weekend Flash Sale! 25% off designer handbags - Limited stock!" gets labeled as \[weekend, flash\_sale, discount\_25, accessories, limited\_stock, urgent].

Agents then learn individual preferences:

* User 1: Responds to \[weekend + discount\_25 + urgent]
* User 2: Prefers \[accessories + limited\_stock] regardless of discount
* User 3: Ignores anything with \[urgent] but loves \[weekend] timing

## The Future of Intelligent Messaging

Labels transform messaging from art to science. By abstracting millions of messages into learnable concepts, they enable AI agents to understand not just what you sent, but **why** it worked. This systematic approach ensures that every message sent is informed by learnings from every previous interaction, creating an ever-improving system that gets smarter with scale.


# What is Aampe?
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/what-is-aampe/what-is-aampe

How do you support an entire workforce of agents? Agentic infrastructure. 

Aampe delivers the infrastructure for a newer kind of personalization: one where each customer gets an AI agent that continuously learns their preferences and adapts their marketing and product experience in real time.

## Agentic Infrastructure

Most personalization tools rely on segments, rules, or generalizations. Aampe changes that. Each user — whether there are hundreds or hundreds of millions — has an agent that adapts uniquely. To support this, Aampe provides tools for:

* Creating and maintaining a large and varied content catalog.
* Labeling of content elements (offerings, value propositions, tone, etc.), so learning is built around content components, not individual messages.
* Optimizing over timing, channel, and content for each individual user.

## A New Approach

Rather than building rigid campaigns, you assemble a curated, pre-approved library of content. You apply labels and define eligibility rules for both messages and users. Then agents select, personalize, and adapt. As a manager of these agents, you:

* Monitor performance and replace or refine underperforming content.
* Adjust label priorities to align with shifting goals.
* Run experiments to improve your marketing and product strategy.
* Incorporate user insights from Aampe's data into your internal reporting or ML models.

The outcome is automatically-adapting marketing and product experiences: genuine personalization at any scale.


# What is Agentic Infrastructure?
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/what-is-aampe/what-is-agentic-infrastructure

Tools to effectively support millions of agents

Agentic infrastructure refers to the tools that enable true 1:1 personalization through AI agents—tailoring messages not just by segment or cohort, but to each user individually.

### Core Infrastructure Elements

* **Content**\
  Agents need a rich collection of content so they can learn what resonates best for each user in a wide variety of circumstances. With Aampe, you can generate millions of unique messages in minutes.
* **Labels**\
  To avoid testing millions of options blindly, messages are broken into labeled components (e.g. offerings, value propositions, tone). This lets agents learn what works with fewer interactions.
* **Learning Framework**\
  Agents receive event-streams (like purchases, subscribes, etc.), so they understand which behaviors are desirable and which are not, and can adjust accordingly.
* **Control & Guardrails**\
  You decide the boundaries, eligibility rules, business constraints, and agent priorities. That means agents personalize content decisions, but within the strategic guardrails you set.

### Why It Matters

You no longer have to sacrifice scale for personalization. With this infrastructure, you bring together rich content, intelligent learning, and guided control so every user can receive personalized experiences without overwhelming manual effort.


# Who is Aampe for?
Source: https://kb.aampe.com/user-guide/welcome-to-aampe/what-is-aampe/who-is-aampe-for

Aampe serves teams seeking true personalization at scale.

## CRM Professionals

Go beyond segments and rigid campaigns. Create message collections labeled by features, value propositions, and tone. Let Aampe’s agents learn which combinations perform best for each user, adjusting timing and frequency dynamically. Ideal for onboarding flows, cart abandonment, re-engagement, upgrade nudges, and any communication where personalization matters.

## Product Professionals

Personalization isn’t just about which product to show—it’s how you present it. With simple API calls, tailor descriptions, framing, and messaging to align with each user’s motivations. Build onboarding that adapts to goals, write feature descriptions that resonate, and use contextual help that actually helps.

## Data Professionals

Aampe captures behavioral signals—how users respond to offers, messages, and styles—and feeds that data directly into your data warehouse. You can use that information to improve your own models for segmentation, churn prediction, and recommendation systems.

## Who Benefits Most

* Growth teams looking to scale personalization without adding headcount
* Companies with diverse user bases, including marketplaces, subscription services, and apps
* Works well whether you have thousands or millions of users

## The Bottom Line

Aampe offers infrastructure for true 1:1 marketing and product experiences. Every user gets a personalized experience; you get the tools to make it possible at any scale.