Broadcast & Topic Notifications

Viafoura supports sending broadcast notifications to all users through the notification tray. 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:

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"
}