Triggering Announcements

Announcements provide a flexible way to reach the district community. Signal Kit currently provides two separate endpoints you can use to send announcements. If your announcement must include attachments (for example, a PDF document), you’ll need to use the Announcements v2 endpoint. Otherwise, the Bulk Import endpoint will be a faster, more flexible option.

In this article, we’ll show you a few examples of how you can utilize the Signal Kit API. If you want to skip ahead to something specific, here’s what we’ll be going over:

  1. Sending an announcement to the feed (the bare minimum)
  2. Sending to a modality (Phone Call/SMS/Email)
  3. Using Pre-Translated Content
  4. Using Pre-Recorded Phone Content
  5. Adding Attachments

Sending Many Announcements In One API Call

Other than not being able to send file attachments, the main thing that differentiates Bulk Import from Announcements v2 is that Bulk Import has support for mail-merge functionality via the merge_variables field. Using a content template and providing the information that changes per announcement to be created is the preferred way to use Bulk Import.

Sending An Announcement To The Feed (the bare minimum)

Using a combination of the content_templates and merge_variables fields, you can perform a simple mail merge. Let’s take look at how we could use these fields and the announcement_type field to send a simple attendance alert.

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token

Sending To A Modality (Phone Call/SMS/Email)

The example above showed how to send an announcement to a user’s Signal Kit announcement feed - the bare minimum combination of delivery_method and language values in the content_templates array required to create an announcement. That probably isn’t going to be quite enough to get their attention though. Let’s send them something a bit more noticeable. In the example below, we’re going to add a few more objects to the content_templates array to send a phone call, SMS, and an email. Each of these objects identifies that we are wanting to send to that modality.

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token
English Feed Content Is Required

Don’t forget! If you’re going to create an announcement, you must include a content_template with a language of English and a delivery method of web.

Pre-Translated Content

You can optionally provide pre-translated content should you have it available. Let’s add another parent to the announcement and provide custom translations for all of their content. Similar to the English/web content above, the Language Name/web content template in the content_templates array is the starting point for anything within Signal Kit. As a result, we can just send the translation once if we want it to be the same for each modality.

Shared Pre-Translated Content
Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token

In the request above, we added a content template for a delivery_method of web and a language of Spanish. Since there were other content templates with delivery_method values for all of the supported modalities, the Spanish recipients will also get emails, phone calls, and text messages. To put it another way, if you provide content for a delivery_method on any language in the content_templates array, all of the recipients of the announcement will receive their appropriate content on that delivery_method. As a result, the recipients will all get the same Spanish content for each modality.

In some cases, though, we may want to customize the content per modality just like we did for English. Following the logic from above, we can simply add the corresponding content_templates that we want to provide custom content for.

Modality-Specific Pre-Translated Content
Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token

Adding Pre-Recorded Phone Content

Lastly, we can override machine generated text-to-speech audio with pre-recorded audio content. This content must be a static, language-specific recording to be heard by the recipients in this request. In the following request, we’ll send web/email/sms/phonecalls in English and Spanish.

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token
Where's the Spanish/SMS content template?

Don’t forget the rules from above. The entire content_templates array has an entry for sms on any language AND there is a Spanish/web content template. As a result, the text message content will be the same as the web content.

Sending Announcements One At A Time/Adding Attachments

If you’re needing to send an attachment with your announcement, you’ll have to jump through some additional hoops. The first hoop being uploading the attachment itself.

Unfortunately, we can’t show you how to upload a file on this page, but it’s the same endpoint we use for linking to an external URL below. You just pass the file to the upload_file field as part of a multipart/form-data request instead of upload_url field we’re using here.

Create a link to a file
Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
access_token

Once you’ve uploaded your files, you’ll need to find the user and group Signal Kit IDs. We walked through these in Finding A User and Finding A District Or School. Once you gather the IDs, plug them into the Settings table below.

Create The Announcement
Send requests directly from the browser (CORS must be enabled)
$$.env
6 variables not set
group_id
parent1_id
parent2_id
student_id
upload_id
access_token
target_users and referring_to_users structures are required to limit the scope of your announcement

Pay close attention to the target_users and referring_to_users structures in the v2/announcements endpoint! Without those populated, you risk sending an announcement for a single family to the entire community. These structures are not technically required on this endpoint so you will not get a warning if you forget to include target_users and referring_to_users.