# Notifications ## Notification API Documentation ### Overview The notification mechanism in our API is a crucial component for tracking the progress and outcomes of **Image Generation Tasks**. Notifications are essential for receiving feedback on task statuses and ensuring seamless communication between the API and client applications. #### Why Notifications Are Important inNotification channels are vital because they provide feedback on the results of image generation tasks. Before using the API, at least one notification channel must be configured from the available types (webhook or RabbitMQ). Among these, **webhook is recommended**, as it aligns with our internal solutions. Without an active notification channel, a client application **cannot initiate any image generation requests** and will encounter the following error: ```json { "errors": { "engine: Active": [ "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f." ], "business: Active": [ "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404, "detail": null, "instance": null, "extensions": { "traceId": "00-ac4f3a19e10981f5f4b5aa22ffd0d0f4-60f1194e0090da68-00" } } ``` #### Notification Channel Features When defining notification channels, it is optional to include the generated image data in the notification message content. Alternatively, the notification can simply provide task completion updates. * **Important**: If the parameter `includeImageData` is set to `true`, the generated image data will be included in the notification message content. Otherwise, the notification will provide only task completion updates without including the image data. A client application can define multiple notification channels of different types (webhook, RabbitMQ). #### Task Notifications The API sends two types of notifications: 1. An **"Image Generation Task Completed"** message when an individual task is finished. 2. An **"Image Generation Progress"** message when all tasks are completed. #### Creating, Updating, and Managing Notifications Using the provided endpoints, a client application can: * Create notification channels * Update notification channels * Delete notification channels * List all or active notification channels defined for the client application #### Authentication Requirements Each request made by a client application to the API must include: * A valid JWT token * `x-api-key` and `x-api-secret` values defined by AdCreative and provided to the client application. These values also carry information about the API usage credits. If these authentication values are missing, the following error will be returned: ```json { "errors": { "business:": [ "Token is missing, invalid or ApplicationId is not found in the token." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 401, "detail": null, "instance": null, "extensions": { "traceId": "00-fc878634896257c5991ac5399ab6c46c-416e4be3606fdbaa-00" } } ``` This section provides a foundational understanding of how the notification mechanism operates and the prerequisites for its effective use. The next section will detail the available endpoints, including their request and response structures. ### Notification Query Endpoints #### 1. Get All Notification Channel Configurations **Endpoint** `GET /api/v1/Notification/ChannelConfiguration/All` **Description** Retrieves a list of all notification channel configurations associated with a specific application. **Request** ```http GET /api/v1/Notification/ChannelConfiguration/All?applicationId={applicationId} HTTP/1.1 Host: localhost:9061 Accept: application/json ``` **Query Parameters** * `applicationId` (required): The unique identifier of the application. **Example Request** ```http GET /api/v1/Notification/ChannelConfiguration/All?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f ``` **Example Response** ```json [ { "id": "e12fb790-ab01-4ae8-9a5a-f996579aaabf", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 2, "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test/\",\"Username\":\"guestRabbit\",\"Password\":\"2w3e3e4r5t\",\"QueueName\":\"queueTest\"}", "notificationChannelConfiguration": { "isActive": false, "includeImageData": true, "notificationChannel": 2 }, "isActive": false, "includeImageData": true, "createdAt": "2024-07-17T09:25:58.642536Z", "updatedAt": "2024-07-17T09:25:58.642537Z" } ] ``` *** #### 2. Get Active Notification Channel Configurations **Endpoint** `GET /api/v1/Notification/ChannelConfiguration/Active` **Description** Retrieves a list of active notification channel configurations for a specific application. **Request** ```http GET /api/v1/Notification/ChannelConfiguration/Active?applicationId={applicationId} HTTP/1.1 Host: localhost:6061 Accept: application/json ``` **Query Parameters** * `applicationId` (required): The unique identifier of the application. **Example Request** ```http GET /api/v1/Notification/ChannelConfiguration/Active?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f ``` **Example Response (Active Notification Found)** ```json { "$id": "1", "$values": [ { "id": "c8409979-12ae-4608-8b2c-70c1d7eae696", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 0, "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}", "notificationChannelConfiguration": { "isActive": true, "includeImageData": true, "notificationChannel": 0 }, "isActive": true, "includeImageData": true, "createdAt": "2024-12-20T18:24:23.141247Z", "updatedAt": "2024-12-20T18:24:23.141432Z" } ] } ``` **Example Response (No Active Notification Found)** ```json { "errors": { "engine: Active": [ "No active notification channel configurations found for Application d5eabbb8-c0f6-4640-94fd-3566edad499f." ], "business: Active": [ "Error getting active notification channel configurations for Application: d5eabbb8-c0f6-4640-94fd-3566edad499f" ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more errors occurred.", "status": 404 } ``` *** #### 3. Get Specific Notification Channel Configuration **Endpoint** `GET /api/v1/Notification/ChannelConfiguration` **Description** Retrieves a specific notification channel configuration by its configuration ID. **Request** ```http GET /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1 Host: localhost:6061 Accept: application/json ``` **Query Parameters** * `applicationId` (required): The unique identifier of the application. * `configurationId` (required): The unique identifier of the configuration. **Example Request** ```http GET /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696 ``` **Example Response** ```json { "id": "c8409979-12ae-4608-8b2c-70c1d7eae696", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 0, "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://example.com/webhook\",\"RetryCount\":3,\"ExponentialBackoffFactor\":2.0}", "notificationChannelConfiguration": { "isActive": true, "includeImageData": true, "notificationChannel": 0 }, "isActive": true, "includeImageData": true, "createdAt": "2024-12-20T18:24:23.141247Z", "updatedAt": "2024-12-20T18:47:12.438504Z" } ``` *** #### 4. Delete Notification Channel Configuration **Endpoint** `DELETE /api/v1/Notification/ChannelConfiguration` **Description** Deletes a specific notification channel configuration by its configuration ID. **Request** ```http DELETE /api/v1/Notification/ChannelConfiguration?applicationId={applicationId}&configurationId={configurationId} HTTP/1.1 Host: localhost:6061 Accept: application/json ``` **Query Parameters** * `applicationId` (required): The unique identifier of the application. * `configurationId` (required): The unique identifier of the configuration. **Example Request** ```http DELETE /api/v1/Notification/ChannelConfiguration?applicationId=d5eabbb8-c0f6-4640-94fd-3566edad499f&configurationId=c8409979-12ae-4608-8b2c-70c1d7eae696 ``` **Example Response** ```json true ``` *** This section provides detailed documentation for the RabbitMQ and WebHook notification configuration endpoints. These endpoints allow client applications to configure notification channels for receiving task completion updates. *** ### **RabbitMQ Endpoints** **POST /api/v1/Notification/ChannelConfiguration/RabbitMQ** **Description**\ Creates a new RabbitMQ notification channel configuration for a specified application. **Request** * **URL**:\ `/api/v1/Notification/ChannelConfiguration/RabbitMQ` * **Query Parameters**: ```json { "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099" } ``` * **Headers**: ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "" } ``` * **Body** *(form-data)*: ```json { "isActive": true, "password": "securePassword123", "queueName": "TaskQueue", "username": "admin", "url": "amqp://localhost/Test", "includeImageData": true } ``` **Example Response** ```json { "id": "4d082fcb-2632-47c3-ac16-b92081801c2c", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 2, "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}", "isActive": true, "includeImageData": true, "createdAt": "2024-12-20T18:44:43.278369Z", "updatedAt": "2024-12-20T18:44:43.278369Z" } ``` *** **PUT /api/v1/Notification/ChannelConfiguration/RabbitMQ** **Description**\ Updates an existing RabbitMQ notification channel configuration. **Request** * **URL**:\ `/api/v1/Notification/ChannelConfiguration/RabbitMQ` * **Query Parameters**: ```json { "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099", "configurationId": "4d082fcb-2632-47c3-ac16-b92081801c2c" } ``` * **Headers**: ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "" } ``` * **Body** *(form-data)*: ```json { "isActive": true, "password": "securePassword123", "queueName": "TaskQueue", "username": "admin", "url": "amqp://localhost/Test", "includeImageData": true } ``` **Example Response** ```json { "id": "4d082fcb-2632-47c3-ac16-b92081801c2c", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 2, "notificationChannelConfigurationJSON": "{\"Url\":\"amqp://localhost/Test\",\"Username\":\"admin\",\"Password\":\"securePassword123\",\"QueueName\":\"TaskQueue\"}", "isActive": true, "includeImageData": true, "createdAt": "2024-12-20T18:44:43.278369Z", "updatedAt": "2024-12-20T18:46:09.637558Z" } ``` *** ### **WebHook Endpoints** **POST /api/v1/Notification/ChannelConfiguration/WebHook** **Description**\ Creates a new WebHook notification channel configuration for a specified application. **Request** * **URL**:\ `/api/v1/Notification/ChannelConfiguration/WebHook` * **Query Parameters**: ```json { "applicationId": "4e2d4910-d39f-f887-6ec4-b3c82e3c0099" } ``` * **Headers**: ```json { "Authorization": "Bearer ", "x-api-key": "", "x-api-secret": "" } ``` * **Body** *(form-data)*: ```json { "isActive": true, "retryCount": 5, "webHookUrl": "https://webhook.site/example", "exponentialBackoffFactor": 2.0, "includeImageData": true } ``` **Example Response** ```json { "id": "d8382f6f-fc70-42aa-99a9-06c1948cd36a", "applicationId": "d5eabbb8-c0f6-4640-94fd-3566edad499f", "channel": 0, "notificationChannelConfigurationJSON": "{\"WebHookUrl\":\"https://webhook.site/example\",\"RetryCount\":5,\"ExponentialBackoffFactor\":2.0}", "isActive": true, "includeImageData": true, "createdAt": "2024-07-30T20:35:26.4982017Z", "updatedAt": "2024-07-30T20:35:26.4982468Z" } ``` *** > **Notes:** All API requests must include valid JWT tokens in the header, along with `x-api-key` and `x-api-secret` values. > > #### Enum Values in Responses > > In the responses, the `NotificationChannel` property represents the type of notification channel used. This property corresponds to the following enum values: | Enum Value | Integer Representation | Description | | ---------- | ---------------------- | ---------------- | | `WebHook` | 0 | Webhook channel | | `SignalR` | 1 | SignalR channel | | `RabbitMQ` | 2 | RabbitMQ channel | > Please use these mappings to interpret the `NotificationChannel` values in the API responses. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://api-docs.adcreative.ai/docs/getting-started/notifications.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.