Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# About the Notifications API

> This feature is not yet available to all users.

The Notifications API enables you to trigger the sending of predefined notifications to Wix site owners and contributors.

With Notifications, you can trigger notifications that Wix users can receive:

+ In the site feed on the Dashboard.
+ In the Wix Owner app notification center.
+ As a mobile push notification from the Wix Owner app.

## Before you begin

It's important to note the following points before starting to code:

+ You need to [create a notification template](https://dev.wix.com/api/rest/wix-notifications/notifications/creating-a-notification-template) in the Wix Dev Center before you can send notifications with the Notifications API. A notification template specifies the text and recipients for notifications. It can include both standard text and placeholders for dynamic values you provide when you send notifications using the Notifications API.
+ An app can call the [Notify](https://dev.wix.com/api/rest/wix-notifications/notifications/notify) endpoint up to 100,000 times per month for each site.

## Sample Use Cases 

+ [Notify a Wix site owner when a customer makes a new room reservation using your app](https://bo.wix.com/wix-docs/rest/wix-notifications/notifications/sample-flows).


## Terminology

+ **Notification template:** Specification of standard text, placeholders, and recipients for a particular type of notification. Created in the Wix Dev Center.
+ **Dynamic values:** Text that replaces a notification template's placeholders when sending notifications from your code.
+ **Notification:** An individual message sent to a Wix user by the Notifications API as part of a notification batch.
+ **Notification batch:** All the notifications triggered by a single call to the Notify endpoint.


# Creating a Notification Template

> This feature is not yet available to all users.

Create a notification template in the Wix Dev Center to specify the standard text, placeholders, and recipients of notifications.
You can then call the [Notify](https://dev.wix.com/api/rest/wix-notifications/notifications/notify) endpoint from your code to trigger sending notifications based on the template you defined.

## Accessing notifications in your app's dashboard

1. Sign in to the Wix Dev Center, then click "My Apps" in the navigation menu.

2. Click on the app you want to create a notification template for. This opens the app's dashboard.

3. Click "Notifications" in the sidebar menu. This opens the Notifications page for your app, where you can find all previously defined notification templates.

4. Click "Create Notification". This opens the form for defining a new notification template.

## Defining a notification template

Fill out the notification template creation form to define a new notification template, then click "Save" to enable it. The form includes the following sections:

### 1. Basic info

Give your notification template an internal name and description for managing it in the Wix Dev Center.
These are visible only to you.

Choose a name and description that make clear what the notification is about and who receives it.
For example, you might choose a name like "New reservation" and a description like "Sent to the site owner when a customer makes a new reservation."

Here you can also find the **notification template ID**. You need this ID to identify your notification template in API calls.

### 2. Recipients

Define who receives notifications of this type and where they receive them.

Choose whether all site contributors or only site owners receive notifications.

Choose where recipients receive notifications: in the site feed on the Dashboard, in the Wix Owner mobile app, or in both.
Recipients who receive notifications in the mobile app receive push notifications on their mobile device and can see the notifications in the app's notification center.

### 3. Message

Create the notification content.

If you enable notifications to the mobile app in the Recipients section, a "Title" field appears here. Enter a notification title that recipients will see.

In the "Message" field, enter the text of your notification.

The message and the title can include placeholders for dynamic values you provide each time you send an HTTP request to trigger notifications. For example:

> **Title:** Item delivered: {{itemType}}.
>
> **Message:** {{customerName}} has received a {{itemType}} delivery.

When triggering a notification with the [Notify](https://dev.wix.com/api/rest/wix-notifications/notifications/notify) endpoint in your code, you pass values for `itemType` and `customerName`, so a recipient sees a customized notification like this:

> **Title:** Item delivered: television.
>
> **Message:** Sally Jones has received a television delivery.


### 4. API consumption

Remember your notification template ID and the names of placeholders for dynamic values in your message and title, as you'll need them to invoke the API and trigger notifications.
But don't worry if you forget them - you can always return to the Wix Dev Center to look these details up.

Press "Save" to generate your notification template. You can now trigger notifications with the [Notify](https://dev.wix.com/api/rest/wix-notifications/notifications/notify) endpoint!

# Notifications: Sample Use Cases & Flows 

This article shares some possible use cases your app could support, as well as
a sample flow that could support each use case. This can be a helpful jumping
off point as you plan your app's implementation.

## Notify a Wix site owner when a customer makes a new room reservation using your app

When a customer makes a new reservation, notify the Wix site owner with the customer name, room type, and the day of the week. 

To notify a Wix site owner:

1. [Create a notification template](https:dev.wix.com/api/rest/wix-notifications/notifications/creating-a-notification-template) in the Wix Dev Center with the Wix site owner as the recipient.

For example:

> **Title:** New {{roomType}} reservation.
>
> **Message:** {{customerName}} just made a new {{roomType}} reservation for {{dayOfWeek}}.


Save the given notification template ID and note the dynamic values.


2. A customer makes a new room reservation. For example, Sally Jones reserves the studio for Friday.

3. Pass the given notification template ID and the dynamic values to the [Notify](https://dev.wix.com/api/rest/wix-notifications/notifications/notify) endpoint to trigger the notification based on the notification template.

  ```json
  {
    "notificationTemplateId": "<GIVEN_NOTIFICATION_TEMPLATE_ID>",
    "dynamicValues": {
      "roomType": {
        "text": "studio"
      },
      "customerName": {
        "text": "Sally Jones"
      },
      "dayOfWeek": {
        "text": "Friday"
      }
    }
  }
  ```

4. The Wix site owner receives the notification defined in the Wix Dev Center:

> **Title:** New studio reservation.
>
> **Message:** Sally Jones just made a new studio reservation for Friday.

items

ArrayDynamicValue

downloadUrl

fileName

AttachmentDynamicValue

ChannelsContent

ChannelsData

DynamicValue

Text to be integrated into the notification.

text

ofType

shoutoutActionConfig

EmailData

audienceKey

ExcludedAudiences

MapDynamicValue

body

title

MobileContent

Notification

appDefId

dynamicValues

notificationTemplateId

templateTenant

NotifyByAppRequest

notificationBatchId

NotifyByAppResponse

Each key is a placeholder name you specify when [creating a notification template](https://dev.wix.com/api/rest/wix-notifications/notifications/creating-a-notification-template).
The value is an object containing the text to replace the placeholder in the notifications.

Notification template ID. A notification template specifies the text and recipients for notifications.
To obtain a notification template ID, [create a notification template](https://dev.wix.com/api/rest/wix-notifications/notifications/creating-a-notification-template) in the Wix Dev Center.

NotifyRequest

ID of the batch of notifications triggered by one request.

NotifyResponse

excludedChannels

Overrides

TemplateChannel

values

ListValue

NullValue

value

StringValue

fields

Struct

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

Money.
Default format to use. Sufficiently compliant with majority of standards: w3c, ISO 4217, ISO 20022, ISO 8583:2003.

Currency code. Must be valid ISO 4217 currency code (e.g., USD).

currency

Monetary amount. Decimal string in local format (e.g., 1 000,30). Optionally, a single (-), to indicate that the amount is negative.

formattedValue

Monetary amount. Decimal string with a period as a decimal separator (e.g., 3.99). Optionally, a single (-), to indicate that the amount is negative.

Money

Sends notifications based on the template and dynamic values provided.

> This feature is not yet available to all users.

An app can call this endpoint up to 100,000 times per month for each site.

When you [create a notification template](https://dev.wix.com/api/rest/wix-notifications/notifications/creating-a-notification-template) in the Wix Dev Center, you are given a notification template ID.
Call the Notify endpoint with this ID as `notificationTemplateID` to trigger notifications based on the notification template.
If the notification template contains placeholders for dynamic values, provide those values as key-value pairs in the `dynamicValues` array.
The values you specify are incorporated seamlessly in the notifications sent out.

Manage Notifications

Send notifications (with dynamic values)

Notify

Notify

Permission Scopes