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:
- Sending an announcement to the feed (the bare minimum)
- Sending to a modality (Phone Call/SMS/Email)
- Using Pre-Translated Content
- Using Pre-Recorded Phone Content
- 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
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.
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
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.
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.
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.
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.
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.
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.
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.