Frontend Integration

This page covers how the frontend consumes workflow notifications. For enabling and configuring notifications on the worker side, see Notifications.

The in-app notifications surface (for example a bell or inbox) is fed by two complementary paths: a real-time event delivered while the user has the web app open, and a pull endpoint that returns anything missed once the app is reopened.

Real-time web delivery (socket gateway)

For tasks submitted from the website (platform: website), the completion notification is delivered in real time over the socket gateway as an in-app notification, shown while the user has the web app open. The frontend receives it on the user's socket connection as a notification event whose data is a single notification object — the same shape as one entry in the Workflow Notifications API response.

note

This delivery is already implemented and live for the main web app. A separate app only needs to subscribe to the socket gateway on its side to start receiving these events.

Workflow Notifications API

Returns the notifications for tasks that have finished (completed or failed) but not yet been seen by the user. The frontend calls it when the user (re)opens the web app, to retrieve any notifications that arrived while the app was closed and populate the in-app notifications list.

GET /workflow-notifications

Header	Required	Description
user-id	Yes	ID of the user whose notifications are requested
language-code	No	Locale used to localize the notification content
app	No	App requesting notifications; results are scoped to tasks submitted from this app. Defaults to com.picsart.studio when omitted.

Results are scoped to the requesting app: each app sees only the notifications for tasks it submitted (matched on the app the task was submitted with). Send the same app value you use when submitting tasks. If the header is omitted it defaults to com.picsart.studio, matching how submit/execute treat a missing app.

The response contains one entry per unseen notification:

{
    "status": "success",
    "response": [
        {
            "id": "<task_id>",
            "type": "message",
            "event": "task_progress",
            "content": {
                "status": "success",
                "title": "Your images are ready",
                "description": "Generated 4 images",
                "actions": [{
                    "deeplink": "...?task_id=<task_id>",
                    "mobileDeeplink": "...?task_id=<task_id>",
                    "text": "View"
                }]
            },
            "payload": {
                "taskId": "<task_id>",
                "taskName": "...",
                "taskStatus": "COMPLETED",
                "taskPlatform": "...",
            }
        }
    ]
}

• content — the UI-facing part the frontend renders (localized title, description, and CTA actions); status is success or error, and the actions deeplinks are already rewritten to include the task_id query parameter.
• payload — task metadata for the frontend's own logic (not for display), such as the taskId and taskName.

Mark as Seen API

Marks a task's notification as consumed so it no longer appears in the Workflow Notifications API response. Call it once the user has seen (or dismissed) the notification.

PATCH /workflow-notifications/:taskId/seen-status

Parameter	In	Description
taskId	Path	ID of the task whose notification is being marked seen

{
    "status": "success"
}