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 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_type

Required.
Options are "broadcast" or "topic".
Defaults to "broadcast".

description

Required.
Descriptive text of the content.

title

Required.
The title text of content or type of content.

url

Required.
The URL that the user will be directed to upon clicking notifications. Tracking query strings are recommended to be added.

image_url

Required.
HTTPS hosted thumbnail image that will be included in the news feed and browser push notifications.

topic_id

Optional.
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_live

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

Did this page help you?