Overview

Some generative tools may require several minutes to complete processing, which can negatively impact the user experience. To improve usability, this feature allows users to close the tool and receive a notification once the generation is complete.

Enabling Notifications

Notifications are enabled per task in your worker's application.yaml:

tasks:
  - name: example-task
    notification:
      enabled: true

Refer to the Notification Configs section for the full set of options (titles, descriptions, etc).

Notifications options

An optional notification object can be passed when submitting a task via the Async API:

"notification": {
    "enabled": true,
    "actions": [{
        "deeplink": "...",
        "mobileDeeplink": "..."
    }],
    "data": {
        "title": "...",
        "description": "...",
        "cta_label": "...",
        "error_title": "...",
        "error_description": "...",
        "error_cta_label": "...",
        "avatar_url": "..."
    }
}

enabled - whether the client opts in to receive a notification for this task (see Per-client opt-in below)
projectId - the ID of the project from which the task was triggered
miniappPackageId - the ID of the miniapp from which the task was triggered
actions - call-to-action (CTA) deeplinks
data - optional client-supplied notification content (see Client-supplied content below)

note

The deeplink(s) specified in the actions will be updated by the backend to include the task_id as a query parameter, enabling the miniapp to correctly restore its state.

Client-supplied content

A client can override the notification copy per request via notification.data. All fields are optional and mirror the static Notification Configs: title, description, cta_label, and their error_* counterparts for the failure case, plus avatar_url (the avatar image shown in the push notification, shared by the success and failure cases).

Each field is resolved independently with the precedence client request > worker runtime override > static task config. The mandatory description falls back to a built-in default when none is provided — Your result is ready to view on success and Failed to generate on failure.

Per-client opt-in

The task's notification.enabled (see Notification Configs) is the default; the client's notification.enabled, when present, overrides it per request:

Task `notification.enabled`	Client `notification.enabled`	Result
`true`	omitted / `true`	✅ sent (default)
`true`	`false`	❌ client opted out
`false` / omitted	omitted / `false`	❌ not sent
`false` / omitted	`true`	✅ client opted in

So enabled: true notifies every client (each can opt out); anything else is opt-in — sent only when the client passes notification.enabled: true, which works even for a task with no notification block.

Routing push notifications to the originating app

A task can be triggered from different applications (for example the Picsart app or the Portfolio app). When such a task completes, its push notification is routed back to the app it was triggered from, so the user is notified in the right place.

Routing is driven by the app header sent when the task is submitted (it defaults to com.picsart.studio when omitted). The backend derives a project_key from that header — by convention the app header with dots replaced by underscores (e.g. com.picsart.studio → com_picsart_studio) — and hands it to the engagement systems facade , which uses it to deliver the push to the correct app.

warning

Push delivery to a given app only works once the engagement / CleverTap setup is completed for that app's project_key. Until that setup is done, mobile push notifications for that app will not be delivered.

Dynamic Notifications

Static notification config may not always be sufficient — you may want to tailor the notification title, description, or CTA label based on the request, error, or any other context available during execution.

You can override notification content at runtime from within your executor using flow.meta().configureNotification(). Dynamic overrides take precedence over the static application.yaml config.

flow.meta().configureNotification({
    title: "Your images are ready",
    description: `Generated ${result.count} images`,
});

note

Requires pluggable-worker-core version 6.16.0 or higher.

All fields are optional — only specify the ones you want to override. Unset fields fall back to the static config.

Field	Used When	Description
`title`	Task succeeded	Notification title
`description`	Task succeeded	Notification description
`cta_label`	Task succeeded	Call-to-action button text
`error_title`	Task failed	Notification title on failure
`error_description`	Task failed	Notification description on failure
`error_cta_label`	Task failed	Call-to-action button text on failure

Frontend integration

For how the frontend consumes these notifications — the real-time socket delivery, the Workflow Notifications API, and the Mark as Seen API — see Notifications: Frontend Integration.

Enabling Notifications​

Notifications options​

Client-supplied content​

Per-client opt-in​

Routing push notifications to the originating app​

Dynamic Notifications​

Frontend integration​