# GET /api/admin/analysis/chart-data Source: https://docs.dittofeed.com/api-reference/auto/analysis/get-apiadminanalysischart-data get /api/admin/analysis/chart-data Get chart data for analysis dashboard. # GET /api/admin/analysis/journey-stats Source: https://docs.dittofeed.com/api-reference/auto/analysis/get-apiadminanalysisjourney-stats get /api/admin/analysis/journey-stats Get journey editor statistics for a specific journey. # GET /api/admin/analysis/summary Source: https://docs.dittofeed.com/api-reference/auto/analysis/get-apiadminanalysissummary get /api/admin/analysis/summary Get summarized metrics for analysis dashboard. # POST /api/admin/broadcasts/execute Source: https://docs.dittofeed.com/api-reference/auto/broadcasts/post-apiadminbroadcastsexecute post /api/admin/broadcasts/execute Create and trigger a broadcast. # DELETE /api/admin/component-configurations/ Source: https://docs.dittofeed.com/api-reference/auto/componentconfigurations/delete-apiadmincomponent-configurations delete /api/admin/component-configurations/ Delete a component configuration. # GET /api/admin/component-configurations/ Source: https://docs.dittofeed.com/api-reference/auto/componentconfigurations/get-apiadmincomponent-configurations get /api/admin/component-configurations/ Get all component configurations. # PUT /api/admin/component-configurations/ Source: https://docs.dittofeed.com/api-reference/auto/componentconfigurations/put-apiadmincomponent-configurations put /api/admin/component-configurations/ Create or update a component configuration. # DELETE /api/admin/content/templates Source: https://docs.dittofeed.com/api-reference/auto/content/delete-apiadmincontenttemplates delete /api/admin/content/templates Delete a message template. # GET /api/admin/content/templates Source: https://docs.dittofeed.com/api-reference/auto/content/get-apiadmincontenttemplates get /api/admin/content/templates Get message templates # POST /api/admin/content/templates/batch-send Source: https://docs.dittofeed.com/api-reference/auto/content/post-apiadmincontenttemplatesbatch-send post /api/admin/content/templates/batch-send Send messages to a batch of users using a message template. # POST /api/admin/content/templates/test Source: https://docs.dittofeed.com/api-reference/auto/content/post-apiadmincontenttemplatestest post /api/admin/content/templates/test Send a test message for a message template. # PUT /api/admin/content/templates Source: https://docs.dittofeed.com/api-reference/auto/content/put-apiadmincontenttemplates put /api/admin/content/templates Create or update message template # GET /api/admin/deliveries/ Source: https://docs.dittofeed.com/api-reference/auto/deliveries/get-apiadmindeliveries get /api/admin/deliveries/ Search through deliveries. # GET /api/admin/events/ Source: https://docs.dittofeed.com/api-reference/auto/events/get-apiadminevents get /api/admin/events/ Get list of events # GET /api/admin/groups/user-groups Source: https://docs.dittofeed.com/api-reference/auto/groups/get-apiadmingroupsuser-groups get /api/admin/groups/user-groups Get list of groups for a specific user # GET /api/admin/groups/users Source: https://docs.dittofeed.com/api-reference/auto/groups/get-apiadmingroupsusers get /api/admin/groups/users Get list of users for a specific group # DELETE /api/admin/journeys/ Source: https://docs.dittofeed.com/api-reference/auto/journeys/delete-apiadminjourneys delete /api/admin/journeys/ Delete a journey. # GET /api/admin/journeys/ Source: https://docs.dittofeed.com/api-reference/auto/journeys/get-apiadminjourneys get /api/admin/journeys/ Get all journeys. # PUT /api/admin/journeys/ Source: https://docs.dittofeed.com/api-reference/auto/journeys/put-apiadminjourneys put /api/admin/journeys/ Create or update a journey. # POST /api/public/apps/group Source: https://docs.dittofeed.com/api-reference/auto/public-apps/post-apipublicappsgroup post /api/public/apps/group The group call lets you assign or unassign a user to a group, along with optionally adding traits to the group. # DELETE /api/admin/segments/ Source: https://docs.dittofeed.com/api-reference/auto/segments/delete-apiadminsegments delete /api/admin/segments/ Delete a segment. # GET /api/admin/segments/ Source: https://docs.dittofeed.com/api-reference/auto/segments/get-apiadminsegments get /api/admin/segments/ Get all segments. # GET /api/admin/segments/manual-segment/status Source: https://docs.dittofeed.com/api-reference/auto/segments/get-apiadminsegmentsmanual-segmentstatus get /api/admin/segments/manual-segment/status Get the status of a manual segment. # POST /api/admin/segments/manual-segment/clear Source: https://docs.dittofeed.com/api-reference/auto/segments/post-apiadminsegmentsmanual-segmentclear post /api/admin/segments/manual-segment/clear Clear a manual segment. # POST /api/admin/segments/manual-segment/update Source: https://docs.dittofeed.com/api-reference/auto/segments/post-apiadminsegmentsmanual-segmentupdate post /api/admin/segments/manual-segment/update Update a manual segment. # PUT /api/admin/segments/ Source: https://docs.dittofeed.com/api-reference/auto/segments/put-apiadminsegments put /api/admin/segments/ Create or update a user segment. # POST /api-l/sessions/ Source: https://docs.dittofeed.com/api-reference/auto/sessions/post-api-lsessions post /api-l/sessions/ Create a session. # PUT /api/admin/settings/email-providers Source: https://docs.dittofeed.com/api-reference/auto/settings/put-apiadminsettingsemail-providers put /api/admin/settings/email-providers Create or update email provider # PUT /api/admin/settings/sms-providers Source: https://docs.dittofeed.com/api-reference/auto/settings/put-apiadminsettingssms-providers put /api/admin/settings/sms-providers Create or update sms provider # GET /api/admin/subscription-groups Source: https://docs.dittofeed.com/api-reference/auto/subscription-groups/get-apiadminsubscription-groups get /api/admin/subscription-groups/ Get a subscription groups # PUT /api/admin/subscription-groups/assignments Source: https://docs.dittofeed.com/api-reference/auto/subscription-groups/put-apiadminsubscription-groupsassignments put /api/admin/subscription-groups/assignments Create or update user subscription group assignments. This performs a patch update on the user's subscription group assignments. # DELETE /api/admin/user-properties/ Source: https://docs.dittofeed.com/api-reference/auto/user-properties/delete-apiadminuser-properties delete /api/admin/user-properties/ Delete a user property. # GET /api/admin/user-properties/ Source: https://docs.dittofeed.com/api-reference/auto/user-properties/get-apiadminuser-properties get /api/admin/user-properties/ Get all user properties. # PUT /api/admin/user-properties/ Source: https://docs.dittofeed.com/api-reference/auto/user-properties/put-apiadminuser-properties put /api/admin/user-properties/ Create or update a user property. # DELETE /api/admin/users/ Source: https://docs.dittofeed.com/api-reference/auto/users/delete-apiadminusers delete /api/admin/users/ Delete events, and computed properties and segments for specific users. # GET /api/admin/users/subscriptions Source: https://docs.dittofeed.com/api-reference/auto/users/get-apiadminuserssubscriptions get /api/admin/users/subscriptions Get subscriptions for a user # POST /api/admin/users/ Source: https://docs.dittofeed.com/api-reference/auto/users/post-apiadminusers POST /api/admin/users/ Get list of users # DELETE /api-l/admin/workspaces Source: https://docs.dittofeed.com/api-reference/auto/workspace/delete-api-ladminworkspaces delete /api-l/admin/workspaces/ Delete / tombstone a workspace. # GET /api-l/admin/workspaces/ Source: https://docs.dittofeed.com/api-reference/auto/workspace/get-api-ladminworkspaces get /api-l/admin/workspaces/ Get a workspace. # PUT /api-l/admin/workspaces/child Source: https://docs.dittofeed.com/api-reference/auto/workspace/put-api-ladminworkspaceschild put /api-l/admin/workspaces/child Create a child workspace. # POST /api/public/apps/batch Source: https://docs.dittofeed.com/api-reference/endpoints/apps/batch POST /api/public/apps/batch The batch method lets you send a series of identify, group, track, page and screen requests in a single batch, saving on outbound requests. The following is an example of a batch body. ```json example body theme={null} { "batch": [ { "type": "track", "event": "Signed Up", "userId": "1043", "properties": { "plan": "Enterprise" }, "messageId": "1ff51c9c-4929-45de-8914-3bb878be8c4a" }, { "type": "identify", "userId": "532", "traits": { "email": "john@email.com" }, "messageId": "6f5f436d-8534-4070-8023-d18f8b78ed39" } ] } ``` # POST /api/public/apps/identify Source: https://docs.dittofeed.com/api-reference/endpoints/apps/identify POST /api/public/apps/identify The Identify call lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about the user, like their email, name, and more. The following is an example of an identify body. ```json example body theme={null} { "userId": "532", "traits": { "email": "john@email.com" }, "messageId": "6f5f436d-8534-4070-8023-d18f8b78ed39" } ``` # POST /api/public/apps/page Source: https://docs.dittofeed.com/api-reference/endpoints/apps/page POST /api/public/apps/page The page call lets you record whenever a user sees a page of your website, along with any optional properties about the page. The following is an example of a page body. ```json example body theme={null} { "name": "Overview", "userId": "1043", "properties": { "url": "/dashboard/overview" }, "messageId": "1ff51c9c-4929-45de-8914-3bb878be8c4a" } ``` # POST /api/public/apps/screen Source: https://docs.dittofeed.com/api-reference/endpoints/apps/screen POST /api/public/apps/screen The screen call lets you record whenever a user sees a screen, the mobile equivalent of page, in your mobile app, along with any properties about the screen The following is an example of a screen body. ```json example body theme={null} { "name": "Home", "userId": "1043", "properties": { "Feed Type": "private" }, "messageId": "1ff51c9c-4929-45de-8914-3bb878be8c4a" } ``` # POST /api/public/apps/track Source: https://docs.dittofeed.com/api-reference/endpoints/apps/track POST /api/public/apps/track The Track call is how you record any actions your users perform, along with any properties that describe the action. The following is an example of a track body. ```json example body theme={null} { "event": "Signed Up", "userId": "1043", "properties": { "plan": "Enterprise" }, "messageId": "1ff51c9c-4929-45de-8914-3bb878be8c4a" } ``` # PUT /api/public/subscription-management/user-subscriptions Source: https://docs.dittofeed.com/api-reference/endpoints/subscription-management/user-subscriptions PUT /api/public/subscription-management/user-subscriptions Allows users to manage their subscriptions. # POST /api/public/webhooks/segment Source: https://docs.dittofeed.com/api-reference/endpoints/webhooks/segment POST /api/public/webhooks/segment Used to consume segment.io webhook payloads. Must be exposed publicly to the internet. # System Architecture Source: https://docs.dittofeed.com/contributing/architecture This page describes Dittofeed's system architecture. This is great for understanding how Dittofeed works, especially if you intend to [self-host](/deployment/self-hosted), or contribute to Dittofeed. ## Summary Dittofeed encompasses a collection of components that work together to scalably ingest user events, and send those users personalized messages. This is accomplished through a series of steps. ### Steps 1. Clients send User Events to the API from their applications. 2. These events are then written to ClickHouse. Optionally, they're buffered in Kafka first. 3. Dittofeed's worker issues queries to ClickHouse on a short polling period for the following purposes: a. Process new events to update [Segments](/resources/segments) and [User Properties](/resources/user-properties) assignments within Clickhouse. b. Retrieve [Segment](/resources/segments) updates, and signal subscribed [Journeys](/resources/journeys). c. Retrieve [Segments](/resources/segments) and [User Properties](/resources/user-properties) assignments from Clickhouse to persist back into Postgres for rapid, row-wise lookups. 4. User [Journeys](/resources/journeys) are processed by the worker, and progress in response to signals, and the passage of time. 5. Journeys issue requests to Messaging Services, to send messages to end users on one or more [Channels](/integrations/channels). ### Diagram Architecture Diagram # Running Dittofeed Locally Source: https://docs.dittofeed.com/contributing/running-locally To run Dittofeed locally, start docker compose, build the dashboard, and then run the development bootstrap script. ```bash theme={null} docker compose up -d # Builds all of the dashboard dependencies including those required by the # bootstrap script, then runs bootstrap. ./dev-setup.sh ``` Then run the service components in separate terminal windows. ```bash theme={null} yarn workspace dashboard dev yarn workspace api dev # Optionally yarn workspace worker dev ``` ## Admin CLI `yarn admin [args]` invoke's the `admin-cli` package's CLI, located [here](https://github.com/dittofeed/dittofeed/tree/main/packages/admin-cli). The `admin-cli` provides useful commands for local development as well as operational tasks in production. ## Running with Github Codespaces Running Dittofeed with Github Codespaces is an easy way to set up a development environment, as they can help rule out idiosyncratic issues with your local environment. To open a codespace, open vscode, and navigate to the Remote Explorer tab. Then click on the "Open Codespace" button. From here, select the dittofeed repository, and create a codespace. We recommend using the second tier codespace or higher, to ensure you have enough resources to run the application (4 cores, 8 GB RAM, 32 GB storage). Open Codespace ## Running Locally With OpenTelemetry In order to run Dittofeed locally with OpenTelemetry (OTEL), start the API or dashboard with the following environment variables. ```bash dashboard theme={null} START_OTEL=true yarn workspace dashboard dev ``` ```bash API theme={null} START_OTEL=true yarn workspace api dev ``` ```bash worker theme={null} START_OTEL=true yarn workspace worker dev ``` Then run the docker compose dependencies with the otel profile. ```bash theme={null} docker compose --profile otel up -d ``` ## FAQ ### Why don't I see any users in my workspace? Displayed users represent a collection of computed "User Property Assignments" and "Segment Assignments". These are computed by the dittofeed worker, and won't be available until the worker has processed user events. If you aren't seeing users in your workspace, it's likely one of the following is true: * Dittofeed hasn't received any user events. * The configured user properties and segments don't match the provided events. * The worker isn't running the compute properties workflow. Try running the following commands. ```bash theme={null} # Will start the job responsible to computing user events, and create sample events. BOOTSTRAP_WORKER=true BOOTSTRAP_EVENTS=true yarn admin bootstrap # Start the worker. yarn workspace worker dev ``` ### How can I submit events? See the documentation on [Using Dittofeed's REST API as a source](/integrations/sources/api). ### How can I view Dittofeed's local Postgres data? Run `./packages/backend-lib/scripts/local-pg-access.sh` to open a psql shell to Dittofeed's postgres database started from the development `docker-compose.yaml` file. ### How can I view dittofeed's local ClickHouse data? Run `./packages/backend-lib/scripts/local-ch-access.sh` to open a ClickHouse shell to Dittofeed's ClickHouse database started from the development `docker-compose.yaml` file. # Updating Dittofeed's API Docs Source: https://docs.dittofeed.com/contributing/updating-api-docs We maintain a copy of the OpenAPI spec for the production API in the docs package - `packages/docs/open-api.json`. The following page describes how to update this file. This schema is used to generate the API reference docs. ## Updating `packages/docs/open-api.json` Run the following command to copy the OpenAPI / Swagger spec to the docs package: ```bash theme={null} curl "https://app.dittofeed.com/documentation/json" | jq "." > packages/docs/open-api.json ``` Note this command assumes you have [jq](https://stedolan.github.io/jq/) installed, which formats the JSON output from the API server. ## Adding New Endpoints to the Docs Run the following command to add new endpoints to the docs: ```bash theme={null} npx @mintlify/scraping@latest openapi-file packages/docs/open-api.json --outDir packages/docs/api-reference/auto ``` Then add the new endpoints to the [mint.json](https://github.com/dittofeed/dittofeed/blob/main/packages/docs/mint.json) file. ```json mint.json theme={null} { "group": "API Reference", "pages": [ "api-reference/auto/content/get-apiadmincontenttemplates", ... ] } ``` ## Running the Docs Locally cd into docs directory ```bash theme={null} cd packages/docs ``` Run the mintlify dev server. ```bash theme={null} mintlify dev ``` # Using Dittofeed Cloud Source: https://docs.dittofeed.com/deployment/cloud To use Dittofeed Cloud, log in or sign up [here](https://app.dittofeed.com/dashboard). For information on pricing, visit our [pricing page](https://dittofeed.com/pricing) or [book a call](https://calendly.com/d/zy7-8d5-jdq/dittofeed-demo-founders) with us to discuss a custom plan. # Self-hosting Dittofeed Source: https://docs.dittofeed.com/deployment/self-hosted Dittofeed supports self-hosting. Currently, Dittofeed supports Docker Compose based deployments. } href="/deployment/self-hosted/render" > Deploy your Dittofeed instance on Render. Deploy your Dittofeed instance with docker compose. } href="/deployment/self-hosted/kubernetes" > Deploy your Dittofeed instance with Kubernetes using our helm chart. } > *Coming Soon* # Authentication and Authorization in Dittofeed Source: https://docs.dittofeed.com/deployment/self-hosted/auth-modes Dittofeed offers three "Auth Modes", each of which varies in its level of flexibility and ease of use. The three modes are: * [Anonymous](#anonymous): No authentication is required to access the Dittofeed Dashboard or API. * [Single Tenant](#single-tenant): A minimalistic authentication setup that allows you to create a single, shared, password protected user account for your Dittofeed instance. * [Multi Tenant](#multi-tenant): A more complex authentication setup that allows you to integrate with any OIDC compliant identity provider. This allows for multiple users to access your Dittofeed instance, each with their own credentials. ## Anonymous This is the default auth mode for Dittofeed. It requires no configuration and works out of the box. It is not recommended for production use, but is useful for testing and development. This auth mode is visible in our [demo](https://demo.dittofeed.com) instance. ## Single Tenant A minimalistic authentication setup that allows you to create a single, shared, password protected user account for your Dittofeed instance. Currently the `single-tenant` auth mode is only available with dittofeed-lite. This setup can be configured by provide the following environment variables to Dittofeed: ```bash theme={null} AUTH_MODE='single-tenant' # to be shared among users accessing the dashboard PASSWORD= # used to secure user sessions SECRET_KEY= ``` The `SECRET_KEY` should be a 32 byte string. You can generate one using the following script, ```javascript theme={null} const crypto = require('crypto'); function generateSecretKey(bytes = 32) { const buffer = crypto.randomBytes(bytes); // Generate 32 random bytes return buffer.toString('base64'); } randomString = generateSecretKey(); console.log(randomString); // This will be a 64-character hexadecimal string ``` Single Tenant is the default auth mode for Dittofeed's [Render](/deployment/self-hosted/render) deployment. ## Multi Tenant The multi-tenant auth mode allows you to integrate with any OIDC compliant identity provider e.g. auth0. This allows for multiple users to access your Dittofeed instance, each with their own credentials. It also allows you to host multiple workspaces on a single Dittofeed instance. For more information on how to configure the multi-tenant auth mode, please refer to the [multi-tenant Auth Mode](/deployment/self-hosted/auth-modes/multi-tenant) documentation. # multi-tenant Auth Mode Source: https://docs.dittofeed.com/deployment/self-hosted/auth-modes/multi-tenant Enable multi-tenancy in your Dittofeed instance. Multi-tenancy, facilitated by the `multi-tenant` "auth mode", allows you to run multiple Dittofeed workspaces on a single instance of Dittofeed. These workspaces allow you to isolate data for different customers, and can be managed programmatically. The `multi-tenant` auth mode also provides separate workspace member accounts, which can log into Dittofeed using their own credentials and permissions. The `multi-tenant` auth mode is only available in dittofeed-ee, and Dittofeed cloud. See [dittofeed-ee](/deployment/self-hosted/dittofeed-ee) for more information on installing dittofeed-ee. ## Setup Multi-tenancy utilizes OIDC ([OpenID Connect](https://openid.net/developers/how-connect-works/)) for authentication. To enable multi-tenancy, you will need to configure an OIDC provider. ### Auth0 In order to configure Auth0 as an OIDC provider for multi-tenancy, use the following environment variables. ```bash .env theme={null} OPEN_ID_CLIENT_ID='' OPEN_ID_CLIENT_SECRET='' SECRET_KEY='' AUTH_MODE='multi-tenant' AUTH_PROVIDER='auth0' SIGNOUT_URL='/dashboard/signout' # Example: https://dittofeed.us.auth0.com/ OPEN_ID_ISSUER='https://.auth0.com/' OPEN_ID_AUTHORIZATION_URL='https://.auth0.com/authorize' OPEN_ID_TOKEN_URL='https://.auth0.com/oauth/token' OPEN_ID_USER_INFO_URL='https://.auth0.com/userinfo' ``` #### Configuring Auth0 In auth0 create a Regular Web Application. Then in the settings of the application, (`https://manage.auth0.com/dashboard/us//applications//settings`) take the following actions. * Copy the `Client ID` which will be used as the `OPEN_ID_CLIENT_ID`. * Copy the `Client Secret` which will be used as the `OPEN_ID_CLIENT_SECRET`. * Add a callback URL of the form `https:///dashboard/oauth2/callback`. * Add a `Logout URL` of the form `https:///dashboard/signout/complete`. * Add an `Allowed Web Origins` of the form `https://`. * Allow Cross-Origin Authentication. * Click Save Changes. ### AWS Cognito In order to configure AWS Cognito as an OIDC provider for multi-tenancy, use the following environment variables. Note that many of these values can be found on your Cognito user pool's `OpenID Connect` settings page. `https://cognito-idp..amazonaws.com//.well-known/openid-configuration` ```bash .env theme={null} OPEN_ID_CLIENT_ID='' OPEN_ID_CLIENT_SECRET='' SECRET_KEY='' AUTH_MODE='multi-tenant' AUTH_PROVIDER='cognito' SIGNOUT_URL='/dashboard/signout' OPEN_ID_ISSUER=https://cognito-idp.us-east-1.amazonaws.com/ OPEN_ID_AUTHORIZATION_URL='https://.auth..amazoncognito.com/oauth2/authorize' OPEN_ID_TOKEN_URL='https://.auth..amazoncognito.com/oauth2/token' OPEN_ID_USER_INFO_URL='https://.auth..amazoncognito.com/oauth2/userInfo' OPEN_ID_END_SESSION_ENDPOINT='https://.auth..amazoncognito.com/logout' OPEN_ID_RETURN_TO_QUERY_PARAM=logout_uri ``` #### Configuring Cognito * Create a new user pool using a traditional web application. * Create a new App client. * Configure your app client as follows: * Set the "Allowed callback Urls": `https:///dashboard/oauth2/callback` * Set Allowed sign-out URLs: `https:///dashboard/signout/complete` * Select the "OAuth 2.0 grant types": Authorization code grant * Select the "OpenID Connect scopes": Email, OpenID, and Profile ### Keycloak In order to configure Keycloak as an OIDC provider for multi-tenancy, use the following environment variables. ```bash .env theme={null} OPEN_ID_CLIENT_ID='' OPEN_ID_CLIENT_SECRET='' SECRET_KEY='' AUTH_MODE='multi-tenant' AUTH_PROVIDER='keycloak' SIGNOUT_URL='/dashboard/signout' OPEN_ID_ISSUER='https:///realms/' OPEN_ID_AUTHORIZATION_URL='https:///realms//protocol/openid-connect/auth' OPEN_ID_TOKEN_URL='https:///realms//protocol/openid-connect/token' OPEN_ID_USER_INFO_URL='https:///realms//protocol/openid-connect/userinfo' OPEN_ID_END_SESSION_ENDPOINT='https:///realms//protocol/openid-connect/logout' OPEN_ID_RETURN_TO_QUERY_PARAM='post_logout_redirect_uri' ``` #### Configuring Keycloak 1. **Access Keycloak Admin Console** * Navigate to `https://` * Login with admin credentials 2. **Create a Realm** * Click on the dropdown in the top-left corner (likely showing "Master") * Click "Create Realm" * Name it `dittofeed` (or your preferred realm name) * Click "Create" 3. **Create an OpenID Connect Client** * Navigate to **Clients** → **Create client** * **General Settings:** * Client type: `OpenID Connect` * Client ID: `dittofeed-client` (this will be your `OPEN_ID_CLIENT_ID`) * Click **Next** * **Capability config:** * Client authentication: `ON` * Authorization: `OFF` * Standard flow: `ON` * Direct access grants: `OFF` * Click **Next** * **Login settings:** * Valid redirect URIs: * `https:///dashboard/oauth2/callback` * Valid post logout redirect URIs: * `https:///dashboard/signout/complete` * Web origins: * `https://` * Click **Save** 4. **Get Client Secret** * Navigate to **Clients** → Select `dittofeed-client` * Go to the **Credentials** tab * Copy the **Client secret** (this will be your `OPEN_ID_CLIENT_SECRET`) 5. **Configure Client Scopes** * The default scopes (openid, profile, email) should be sufficient * If needed, navigate to **Client scopes** to customize #### Verifying the Configuration You can verify your Keycloak OIDC configuration by accessing the discovery endpoint: ``` https:///realms/dittofeed/.well-known/openid-configuration ``` This endpoint will show all available OIDC endpoints for your realm. #### Notes * The `AUTH_PROVIDER` environment variable should be set to `keycloak` for proper provider identification * The `OPEN_ID_RETURN_TO_QUERY_PARAM` for Keycloak is `post_logout_redirect_uri`. * Ensure your Keycloak instance is accessible from your Dittofeed application * For production deployments, always use HTTPS for all URLs ### Generating a Secret Key See our documentation on [Authentication Modes](/deployment/self-hosted/auth-modes) for instructions on how to generate a new `SECRET_KEY`. ### Enabling PKCE If your OIDC provider requires PKCE (e.g., strict Keycloak setups), enable it with the environment variable below: ```bash .env theme={null} ENABLE_PKCE='true' ``` PKCE is disabled by default. When enabled, Dittofeed will generate PKCE code challenges for `/dashboard/login` and include the matching verifier on `/dashboard/oauth2/callback`. # Blob Storage Source: https://docs.dittofeed.com/deployment/self-hosted/blob-storage Learn how to configure Dittofeed to use a custom blob storage. Dittofeed optionally utilizes an s3 compatible blob storage to support features which require storing files. This includes: * File attachments * [View in browser](/guide/view-in-browser) functionality for emails * Image hosting (coming soon) ## Configuration ```bash theme={null} ENABLE_BLOB_STORAGE=true # The endpoint of the blob storage e.g. s3 endpoint BLOB_STORAGE_ENDPOINT=http://localhost:9010 # The access key id for the blob storage BLOB_STORAGE_ACCESS_KEY_ID=admin # The secret access key for the blob storage BLOB_STORAGE_SECRET_ACCESS_KEY=password # The bucket to use for the blob storage BLOB_STORAGE_BUCKET=dittofeed # The region of the blob storage BLOB_STORAGE_REGION=us-east-1 ``` We recommend creating a dedicated bucket for Dittofeed to use. # Self-Host with AWS Cloudformation Source: https://docs.dittofeed.com/deployment/self-hosted/cloudformation *Coming Soon* # dittofeed-ee Source: https://docs.dittofeed.com/deployment/self-hosted/dittofeed-ee The dittofeed-ee application is a closed source extension of Dittofeed that includes additional features, like support for [multi-tenancy](/deployment/self-hosted/auth-modes/multi-tenant). ## Installation To install dittofeed-ee, contact the Dittofeed team at [support@dittofeed.com](mailto:support@dittofeed.com) in order to receive a personal access token for our private docker image registry. Once you have the token, you can install dittofeed-ee using our docker compose file or helm chart. The dittofeed-ee image currently requires that you run it in [multi-tenant mode](/deployment/self-hosted/auth-modes/multi-tenant). ### Docker Compose First, login to the docker registry using your Dittofeed issued personal access token. ```bash theme={null} docker login -u -p ``` Create a .env file in the root directory with the environment variables described in the [multi-tenant auth mode docs](/deployment/self-hosted/auth-modes/multi-tenant). ```bash .env theme={null} OPEN_ID_CLIENT_ID='' OPEN_ID_CLIENT_SECRET='' SECRET_KEY='' AUTH_PROVIDER='auth0' # Example: https://dittofeed.us.auth0.com/ OPEN_ID_ISSUER='https://.auth0.com/' OPEN_ID_AUTHORIZATION_URL='https://.auth0.com/authorize' OPEN_ID_TOKEN_URL='https://.auth0.com/oauth/token' OPEN_ID_USER_INFO_URL='https://.auth0.com/userinfo' ONBOARDING_URL='/dashboard-l/onboarding' ``` You will also need to set the environment variables described in the [multi-tenant auth mode docs](/deployment/self-hosted/auth-modes/multi-tenant) in your .env file. Then, run our docker-compose.ee.yaml file. ```bash theme={null} docker-compose -f docker-compose.ee.yaml up -d ``` ### Helm Chart Likewise, you can install dittofeed-ee using our helm chart. First, login to the docker registry using your Dittofeed issued personal access token. ```bash theme={null} docker login -u -p ``` First set the following values in your values.yaml file. ```yaml theme={null} ee: enabled: true image: repository: dittofeed/dittofeed-ee tag: v0.23.0-ee.1 env: ... - name: ONBOARDING_URL value: "/dashboard-l/onboarding" - name: SIGNOUT_URL value: "/dashboard/signout" - name: AUTH_PROVIDER value: "auth0" # Example: https://dittofeed.us.auth0.com/ - name: OPEN_ID_ISSUER value: "https://.auth0.com/" - name: OPEN_ID_AUTHORIZATION_URL value: "https://.auth0.com/authorize" - name: OPEN_ID_TOKEN_URL value: "https://.auth0.com/oauth/token" - name: OPEN_ID_USER_INFO_URL value: "https://.auth0.com/userinfo" - name: OPEN_ID_CLIENT_ID valueFrom: secretKeyRef: name: dittofeed-ee-auth0-client-id key: value - name: OPEN_ID_CLIENT_SECRET valueFrom: secretKeyRef: name: dittofeed-ee-auth0-client-secret key: value - name: SECRET_KEY valueFrom: secretKeyRef: name: dittofeed-ee-secret-key key: value ``` Then, install the helm chart. ```bash theme={null} helm install dittofeed dittofeed/dittofeed --values values.yaml ``` ### Render We support deployment of dittofeed-ee on [Render](https://render.com). To do so, you will need to add your Docker Hub credentials to your Render account settings. 1. Log in to your Render account and navigate to the Dashboard. 2. Go to "Account Settings" in the left sidebar. 3. Click on "Registry Credentials" in the Account Settings menu. 4. Click the "Add Credential" button. 5. In the "Add Registry Credential" modal: * Select "Docker Hub" as the registry type * Name the credential `dittofeed` * Enter your Docker Hub username * Enter your Docker Hub password or personal access token * Give the credential a name for easy reference 6. Click "Add Credential" to save. Then install the dittofeed-ee service from the render-ee branch. Deploy To Render # Self-Host with Docker Compose Source: https://docs.dittofeed.com/deployment/self-hosted/docker-compose This section outlines the necessary steps to run Dittofeed with docker compose. Watch the following video walkthrough to see how to set up Dittofeed with docker compose. ``` ### Journey Table The journey table displays all of the journeys for the child workspace. It provides a way to create new journeys, and view existing ones. Embedded Journey Table ```html theme={null} ``` ### Broadcast Editor The broadcast editor allows you to create and edit broadcasts. Embedded Broadcast Recipients Embedded Broadcast Configuration ```html theme={null} ``` #### Broadcast Configuration The broadcast editor supports configuration to customize which steps, providers, and UI elements are available. ```typescript theme={null} interface BroadcastConfiguration { // Discriminator field - must be "Broadcast" for this configuration type type: "Broadcast"; // Controls which steps/tabs are visible in the broadcast editor workflow. // If not specified, all steps are shown. // Options: // - "RECIPIENTS": The segment selection step where users choose who receives the broadcast // - "CONTENT": The message template editing step where users compose the broadcast content // - "CONFIGURATION": The settings step for scheduling, rate limiting, and provider selection // - "DELIVERIES": The deliveries table showing sent messages after the broadcast is triggered // - "EVENTS": The events log showing delivery events (opens, clicks, bounces, etc.) stepsAllowList?: ("RECIPIENTS" | "CONTENT" | "CONFIGURATION" | "DELIVERIES" | "EVENTS")[]; // Restricts which email providers can be selected as overrides for this broadcast. // If not specified, all configured workspace providers are available. // Options: "SendGrid", "AmazonSes", "Resend", "PostMark", "Smtp", "Test", "MailChimp", "Gmail" emailProviderOverrideAllowList?: ("SendGrid" | "AmazonSes" | "Resend" | "PostMark" | "Smtp" | "Test" | "MailChimp" | "Gmail")[]; // When true, hides the email provider override dropdown selector. // Use this to force broadcasts to use the workspace default provider. hideOverrideSelect?: boolean; // When true, hides the scheduling options (send now vs. schedule for later). // Use this to simplify the UI when scheduling is not needed. hideScheduledSelect?: boolean; // When true, hides the rate limiting configuration options. // Rate limiting controls how many messages are sent per time period. hideRateLimit?: boolean; // When true, hides the side drawer that shows additional broadcast details. // Use this for a more streamlined, focused editing experience. hideDrawer?: boolean; // When true, hides the user properties panel in the template editor. // This panel shows available user properties for personalization (e.g., {{user.name}}). hideTemplateUserPropertiesPanel?: boolean; // When true, shows advanced error handling options for message delivery failures. // Includes retry configuration and failure notification settings. showErrorHandling?: boolean; // Restricts which email editor types are available when creating/editing templates. // Options: // - "Code": Raw HTML/MJML code editor for full control // - "LowCode": Visual drag-and-drop editor for easier template creation allowedEmailContentsTypes?: ("Code" | "LowCode")[]; // Sets the default template type when creating new emails in the low-code editor. // Options: // - "Informative": Starts with a pre-built informational email template // - "Empty": Starts with a blank canvas lowCodeEmailDefaultType?: "Informative" | "Empty"; } ``` ### Broadcasts Table The broadcasts table displays all of the broadcasts for the child workspace. It provides a way to create new broadcasts, view existing ones, and archive them. Embedded Broadcasts Table ```html theme={null} ``` ### Template Editor The template editor allows you to create and edit message templates. #### SMS Editor The SMS editor allows you to create and edit SMS templates. Embedded SMS Editor ```html theme={null} ``` #### Email Editor The email editor allows you to create and edit email templates. Embedded Email Editor ```html theme={null} ``` #### Template Editor Configuration The template editor supports configuration to customize which editor types are available. ```typescript theme={null} interface MessageTemplateConfiguration { // Discriminator field - must be "MessageTemplate" for this configuration type type: "MessageTemplate"; // Restricts which email editor types are available when creating/editing templates. // Options: // - "Code": Raw HTML/MJML code editor for full control over email markup. // Best for developers who want precise control over the HTML structure. // - "LowCode": Visual drag-and-drop editor for easier template creation without coding. // Best for non-technical users who want to build emails visually. // If not specified, both editor types are available. allowedEmailContentsTypes?: ("Code" | "LowCode")[]; // Sets the default starting template when creating new emails in the low-code editor. // Options: // - "Informative": Starts with a pre-built template containing example sections // (header, content area, footer) - good for getting started quickly // - "Empty": Starts with a completely blank canvas - good for building from scratch // If not specified, defaults to "Informative". lowCodeEmailDefaultType?: "Informative" | "Empty"; } ``` ### Templates Table The templates table displays all of the message templates for the child workspace. Embedded Templates Table ```html theme={null} ``` ### Segment Editor The segment editor allows you to create and edit segments. Embedded Segment Editor ```html theme={null} ``` ### Segments Table The segments table displays all of the segments for the child workspace. It provides a way to create new segments, view existing ones, and archive them. Embedded Segments Table ```html theme={null} ``` ### Deliveries Table The deliveries table displays all of the message deliveries for the child workspace e.g. for sent emails, and SMS. Embedded Deliveries Table ```html theme={null} ``` #### Deliveries Table Configuration The deliveries table supports configuration to customize which columns are displayed and how to link to resources in your application. ```typescript theme={null} interface DeliveriesTableConfiguration { // Discriminator field - must be "DeliveriesTable" for this configuration type type: "DeliveriesTable"; // Controls which columns are visible in the deliveries table. // If not specified, all columns are shown. // Options: // - "preview": Shows a preview button to view the full message content // - "from": The sender address (email from address or SMS phone number) // - "to": The recipient address (email to address or SMS phone number) // - "userId": The Dittofeed user ID of the recipient // - "snippet": A short preview of the message content // - "channel": The delivery channel type (Email, SMS, etc.) // - "status": The delivery status (Sent, Delivered, Bounced, etc.) // - "origin": The source that triggered this delivery (journey name or broadcast name) // - "sentAt": Timestamp when the message was sent // - "template": The name of the message template used // - "updatedAt": Timestamp when the delivery record was last updated columnAllowList?: ("preview" | "from" | "to" | "userId" | "snippet" | "channel" | "status" | "origin" | "sentAt" | "template" | "updatedAt")[]; // URI template for generating links to user detail pages in your application. // Use {userId} as a placeholder that will be replaced with the actual user ID. // Example: "/app/users/{userId}" would become "/app/users/abc123" userUriTemplate?: string; // URI template for generating links to template detail pages in your application. // Use {templateId} as a placeholder that will be replaced with the actual template ID. // Example: "/app/templates/{templateId}" would become "/app/templates/def456" templateUriTemplate?: string; // URI template for generating links to the origin resource (journey or broadcast) in your application. // Use {originId} as a placeholder that will be replaced with the journey or broadcast ID. // Example: "/app/campaigns/{originId}" would become "/app/campaigns/ghi789" originUriTemplate?: string; } ``` ### Analysis Chart The analysis chart provides time-series insights into your messaging performance. It supports grouping (e.g., by journey, template, channel, provider, and message state), flexible date ranges, percentage view, quick downloads, and a summary panel. ```html theme={null} ``` #### Analysis Chart Configuration The analysis chart supports extensive configuration to customize filters, grouping options, and how to link to resources in your application. ```typescript theme={null} interface AnalysisChartConfiguration { // Discriminator field - must be "AnalysisChart" for this configuration type type: "AnalysisChart"; // Pre-set filters that are always applied and cannot be changed by users. // Use this to scope the analysis to specific resources (e.g., show only data for a specific journey). hardcodedFilters?: { // Filter to show only data from specific journeys (by journey ID) journeyIds?: string[]; // Filter to show only data from specific broadcasts (by broadcast ID) broadcastIds?: string[]; // Filter to show only data from specific channels: "Email", "Sms", "MobilePush", "Webhook" channels?: string[]; // Filter to show only data from specific providers: "SendGrid", "AmazonSes", "Twilio", etc. providers?: string[]; // Filter to show only specific message states: "Sent", "Delivered", "Opened", "Clicked", "Bounced", etc. messageStates?: string[]; // Filter to show only data from specific templates (by template ID) templateIds?: string[]; // Filter to show only data for specific users (by user ID) userIds?: string[]; }; // Controls which filter dropdowns are available in the UI for users to modify. // If not specified, all filters are available. // Use this to simplify the UI by only showing relevant filters. allowedFilters?: ("journeyIds" | "broadcastIds" | "channels" | "providers" | "messageStates" | "templateIds" | "userIds")[]; // Controls which grouping options are available in the chart. // Grouping determines how data is segmented in the visualization. // Options: // - "journey": Group metrics by journey // - "broadcast": Group metrics by broadcast campaign // - "messageTemplate": Group metrics by message template // - "provider": Group metrics by delivery provider // Note: "channel" and "messageState" groupings are always available and cannot be disabled. allowedGroupBy?: ("journey" | "broadcast" | "messageTemplate" | "provider")[]; // Restricts which channel types appear in channel-related filters and groupings. // Options: "Email", "MobilePush", "Sms", "Webhook" // Use this if your application only uses certain channels. allowedChannels?: ("Email" | "MobilePush" | "Sms" | "Webhook")[]; // Controls which columns are visible in the deliveries drill-down table. // This table appears when users click on a data point in the chart. // Uses the same column options as DeliveriesTableConfiguration. columnAllowList?: ("preview" | "from" | "to" | "userId" | "snippet" | "channel" | "status" | "origin" | "sentAt" | "template" | "updatedAt")[]; // URI template for generating links to template detail pages in your application. // Use {templateId} as a placeholder that will be replaced with the actual template ID. // Example: "/app/templates/{templateId}" would become "/app/templates/def456" templateUriTemplate?: string; // URI template for generating links to the origin resource (journey or broadcast) in your application. // Use {originId} as a placeholder that will be replaced with the journey or broadcast ID. // Example: "/app/campaigns/{originId}" would become "/app/campaigns/ghi789" originUriTemplate?: string; } ``` ## 5. Configure Your Embedded Components (Optional) You can customize the behavior and appearance of embedded components by creating **Component Configurations**. This allows you to tailor each component to your application's specific needs—for example, hiding certain UI elements, restricting available options, or linking to your own user/template detail pages. ### Why Use Component Configurations? * **Simplify the UI**: Hide features your users don't need (e.g., scheduling options, rate limiting) * **Restrict options**: Limit which email providers, editor types, or workflow steps are available * **Integrate with your app**: Use URI templates to link users, templates, and campaigns back to pages in your application * **Pre-filter data**: Show only relevant data by hardcoding filters on analysis charts ### How to Create a Configuration Use the [PUT /api/admin/component-configurations/](/api-reference/auto/componentconfigurations/put-apiadmincomponent-configurations) endpoint to create or update a configuration. **Important:** The `name` field must match the component type you want to configure. Each workspace can have one configuration per component type. | Component | Configuration Name | | ---------------- | ------------------ | | Broadcast Editor | `Broadcast` | | Template Editor | `MessageTemplate` | | Deliveries Table | `DeliveriesTable` | | Analysis Chart | `AnalysisChart` | Example creating a Broadcast configuration: ```bash theme={null} curl -X PUT \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "", "name": "Broadcast", "definition": { "type": "Broadcast", "hideScheduledSelect": true, "hideRateLimit": true } }' \ https://app.dittofeed.com/api/admin/component-configurations/ ``` ### How Configurations Are Applied Configurations are automatically applied when loading an embedded component. When your server renders an embedded component page, it fetches the configuration matching the component type for that workspace. For example, when loading the Broadcast Editor for a workspace, the server will automatically fetch and apply the configuration named `"Broadcast"` for that workspace (if one exists). ### Supported Components The following components support configurations. See the configuration options for each component in their respective sections above. * **Broadcast Editor** — `BroadcastConfiguration` (name: `"Broadcast"`) * **Template Editor** — `MessageTemplateConfiguration` (name: `"MessageTemplate"`) * **Deliveries Table** — `DeliveriesTableConfiguration` (name: `"DeliveriesTable"`) * **Analysis Chart** — `AnalysisChartConfiguration` (name: `"AnalysisChart"`) # Glossary Source: https://docs.dittofeed.com/glossary ## Action A type of step in a [journey](#journey) which carries out pre-defined work. Most commonly, actions send messages to users on some [channel](#channel) e.g. email. ## Campaign In the context of a customer engagement platform like Dittofeed, "campaign" is an umbrella term used to describe a program for automating customer engagement. Growth and marking teams use the low-code interfaces commonly provided by customer engagement platforms to create campaigns. Campaigns can be used to send messages on different [channels](#channel). [Journeys](#journey) are a type of campaign, modeled as a sequence of steps. ## CDP An acronym for “customer data platform”. CDPs are services which provide a centralized store of user data for business applications. These business applications include CRM's, marketing tools, business intelligence tools, and more. Popular CDP's include [segment.com](segment.com), and [rudderstack.com](rudderstack.com). ## Channel A messaging outlet. Some commonly used channels include email, SMS, mobile push notifications, and in-app messaging. Customer engagement platforms which are "omni-channel" provide tools that allow messaging to be sent across all channels. ## ESP An acronym for "email service provider". ESPs provide email infrastructure like servers, IP addresses, authentication protocols, list management tools, content filtering, and deliverability to ensure that email campaigns can be reliably delivered. ## Event A discrete unit of user activity within an application or on a website. Examples might include: * A user visiting a page. * A user placing items in a shopping cart. * A user logging in or registering. ## In-app Messaging Messaging that is rendered within an application. For example, an app might render a carasoul of personalized product recommendations for a user. Companies will often deploy this type of messaging to remind users of features they aren’t using or to expose users to new products. ## Integration Dittofeed integrates with third party applications and services for several purposes. * Data Source Integration: Imports user data into Dittofeed. * Destination Integration: Exports user data from Dittofeed. * Channel Integration: Used to message users. ## Journey A sequence of triggers and actions which automate the process of sending well-timed, relevant messaging to users. Journeys allow companies to automatically split users into segments, add time delays to messages, send different messaging templates based on user behavior, and much more. Journeys automate communicating with users about things like: * Onboarding * Promotions * Cart abandonment * Loyalty programs * Newsletters * New feature rollouts Journeys are a kind of [campaign](#campaign). Various customer engagement platforms call journeys by different names, including: "sequences", "workflows", "automations" or just plainly "campaigns". ## Reverse ETL "ETL" stands for "extract, transform, load”, and refers to the process of exporting warehoused data to business applications, like Dittofeed, CRM's, and more. Popular data warehouses include Snowflake, Amazon Redshift, and Google BigQuery. Popular data destinations include Salesforce, Tableau, and Amplitude. ## Segment A subset of users defined by specific parameters like demography, app usage metrics, and message responses. For example, Company X has users across the world who use their app to varying degrees, but the company only wants to send a particular message to its North American users who don't use the app very often. Segmentation could be used to identify these users in order to message them. ## Template A standardized messaging layout, often with a visual design and variable input fields which can be programmatically altered to personalize messages. ## Webhook Webhooks allow producer applications to "push" data into consumer applications' API's, rather than "pull" that data from a conventional synchronous API. Webhooks allow consuming applications to receive live updates from the sending application, while avoiding polling. Webhooks are frequently used to synchronize data sources across applications and services. For example, Dittofeed is capable of consuming [segment.com](segment.com)'s webhooks in order to receive updates to its user data. ## Workflow Another term for a journey. Workflows are sequences of triggers and actions. ## Workspace Member Someone who has access to a Dittofeed workspace. # Accessing the Admin API Source: https://docs.dittofeed.com/guide/accessing-admin-api The Admin API allows you to manage your Dittofeed workspace programmatically. These endpoints are prefixed with the path `/api/admin`. Unlike public `/api/public` endpoints, Admin API endpoints require an Admin API key. ## Creating an Admin API Key Admin API keys can be created from the settings page [`/dashboard/settings#admin-api-key`](https://app.dittofeed.com/dashboard/settings#admin-api-key). Admin API key Once an Admin API key is created, its value can't be read again. Make sure to write it down and store it securely. ## Using an Admin API Token To authenticate with the Admin API, include the Admin API key in the `Authorization` header of your requests. ``` Authorization: Bearer ``` # Creating Journeys Source: https://docs.dittofeed.com/guide/creating-journeys The following is a demo where we set up Dittofeed end to end, and create a simple onboarding journey.