Broadcast & Topic Notifications

This feature allows you to create a message that can be delivered to all users through Browser Notifications and Viafoura's Notification Tray, even if the user isn't logged in or doesn't have an account on your site.

Viafoura supports sending broadcast notifications to all users through the notification tray and via browser-based push notifications for users who have opted in. We do not provide a GUI to send broadcast messages at this time, so implementation requires the use of our notification APIs.

🚧

Broadcast Notification Time To Live

A broadcast notification will live in the tray for 3 days, this is not configurable. If you wish to remove it sooner you can call the delete notification API

Broadcast Notifications Instructions

Step 1: Obtain Credentials
Encrypted credentials are needed to use the APIs. A client ID and secret pair with the appropriate permission levels will be provided to you by your client success representative. (please contact our support team).

With these credentials, you can follow the next steps to launch broadcast notifications.

Step 2: Create a JWT
Use the Client ID and Secret to create a JWT to use as authorization for the API calls:(https://documentation.viafoura.com/reference/authorizeclient).

📘

Note:

  1. Each JWT is only valid for 5 minutes.
  2. You will need to provide the section_uuid that identifies the site you want to send the notification to as the "scope". If you don't know the section_uuid of the site, please [reach out to our support team].(https://documentation.viafoura.com/page/create-a-new-case).
  3. For this endpoint, the authentication header when passing your credentials should be BASIC.

Step 3: Send broadcast
Use the newly created JWT as your authorization header in the broadcast endpoints.
Here are our Broadcast API endpoint reference docs: https://documentation.viafoura.com/reference/sendbroadcasttosite or https://documentation.viafoura.com/references/sendbroadcasttositeform.

📘

Note:

  1. You will need to provide the section_UUID that identifies the site you want to send the notification to. If you don't know the section_UUID of the site, please reach out to our support team.
  2. For this endpoint, the authentication header when passing your JWT token should be BEARER.

Topic Notifications

Topic Notifications, also known as notifications for Custom Topic & Author Follows make use of the same Broadcast API, with an exception: you must include the topic_id that you've created for the topic your users will subscribe to (or author, podcast, etc) and you must specify that the broadcast_type is "topic".

This will send notifications to only the users who have subscribed to get notified about this topic. Without specifying the topic_id, the notification is treated as a Broadcast Notification, which then goes to all users on the site.

Parameters & Request Examples

These are the parameters to include in the body of the API call:

broadcast_typeRequired.
Options are "broadcast" or "topic".
Defaults to "broadcast".
descriptionRequired.
Descriptive text of the content.
titleRequired.
The title text of content or type of content.
urlRequired.
The URL that the user will be directed to upon clicking notifications. Tracking query strings are recommended to be added.
image_urlRequired.
HTTPS hosted thumbnail image that will be included in the news feed and browser push notifications.
topic_idOptional.
The topic identifier you've given to a specific topic.

NOTE: This only applies in the case of sending a Topic Notification. If not sending this type of notification, please omit this field entirely.
push_time_to_liveOptional.
The time in seconds that a push notification will be retained until the browser is available. ie, the user's computer is turned on. If blank, 4 weeks is the default value

Here is an example of a Broadcast API request with placeholder text and the section_UUID is "00000000-0000-0000-0000-xxxxxxxxxxxx":

curl --request POST \
     --url https://notifications.viafoura.co/v5/notifications/00000000-0000-0000-0000-xxxxxxxxxxxx/broadcast \
     --header 'Accept: application/json' \
     --header 'Authorization: JWT Goes Here' \
     --header 'Content-Type: application/json' \
     --data '
{
     "broadcast_type": "site",
     "description": "Test Broadcast",
     "image_url": "https://thumbnailimage.jpg",
     "title": "This is a test",
     "url": "https://whatever-url-you-want.html"
}

Here is an example of a Topic Notification request using the Broadcast API endpoint with placeholder text and the section_UUID is "00000000-0000-0000-0000-xxxxxxxxxxxx".
Note that this includes "broadcast_type": "topic" and adds "topic_id":

curl --request POST \
     --url https://notifications.viafoura.co/v5/notifications/00000000-0000-0000-0000-xxxxxxxxxxxx/broadcast \
     --header 'Accept: application/json' \
     --header 'Authorization: JWT Goes Here' \
     --header 'Content-Type: application/json' \
     --data '
{
     "broadcast_type": "topic",
     "description": "Test Topic Notification",
     "image_url": "https://thumbnailimage.jpg",
     "title": "This is a test with topic",
     "url": "https://whatever-url-you-want.html",
     "topic_id": "your topic identifier"
}