Broadcasts API

List broadcasts

List all broadcasts for an account:

GET /broadcasts

Response

Status: 200 OK
[
  {
    "id": 349,
    "sourceID": null,
    "created_at": "2016-05-23T06:06:34-05:00",
    "updated_at": "2016-05-23T06:06:45-05:00"
  },
  {
    "id": 321,
    "sourceID": null,
    "created_at": "2016-05-22T03:20:36-05:00",
    "updated_at": "2016-05-23T04:30:01-05:00"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of broadcasts.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of broadcasts:

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of broadcasts is sorted descending by start_at.

The following fields are accepted by the ?sort= parameter:

Get a single broadcast

GET /broadcasts/:id

Response

Status: 200 OK
{
  "created_at": "2016-05-22T03:20:36-05:00",
  "disabled": false,
  "end_at": null,
  "id": 1,
  "message": "Foo",
  "message_type": "warning",
  "service_instances": [
    {
      "id": 33,
      "name": "Amsterdam Network",
      "localized_name": "Amsterdam Network"
    },
    "..."
  ],
  "source": "web",
  "sourceID": null,
  "start_at": "2014-05-22T08:20:00Z",
  "teams": [

  ],
  "time_zone": "Central Time (US & Canada)",
  "translations": [
    {
      "id": 321,
      "locale": "en-US"
    },
    "..."
  ],
  "updated_at": "2014-05-23T04:30:01-05:00",
  "visibility": "covered_for"
}

The response contains these fields.

Create a broadcast

POST /broadcasts

When creating a new broadcast these fields are available.

Response

Status: 201 Created
{
  "message": "...",
  "...": "..."
}

The response contains all fields of the created broadcast and is similar to the response in Get a single broadcast

Update a broadcast

PATCH /broadcasts/:id

When updating a broadcast these fields are available.

Response

Status: 200 OK
{
  "message": "...",
  "...": "..."
}

The response contains all fields of the updated broadcast and is similar to the response in Get a single broadcast

Fields

created_at
Readonly datetime — The date and time at which the broadcast was created.
disabled
Optional boolean, default: false — The Disabled box is checked when the message should not be broadcasted.
id
Readonly integer — The unique ID of the broadcast.
end_at
Optional datetime — The End field is used to select the end date and time of the broadcast. This field is left empty when the message is to be broadcasted until the Disabled box is checked.

If the broadcast should end at midnight at the end of a day, specify 12:00am or 24:00.

message
Required text (max 64KB) — The Message field is used to enter the information that is to be broadcasted.
message_type
Required enum — The Message type field is used to select the appropriate icon for the message. The selected icon is displayed alongside the message when the broadcast is presented. Valid values are:
  • outage: Outage
  • available: Available
  • warning: Warning
  • info: Information
source
Optional string (max 30) — See source
sourceID
Optional string (max 128) — See source

The message will be stored/displayed as the translation for the locale of the account.

service_instances
Optional array of references to Service Instance — The Service instances table field is used to select the service instances for which the people, who are covered for them by an active SLA, need to see the broadcast. This table field is available only when the “People with coverage for the following service instance(s)” visibility option is selected.

Keep in mind that, when a service instance is selected for which people from other accounts are covered, then these people will also get to see the broadcast.

start_at
Required datetime, default: the current date and time in the timezone of the user — The Start field is used to specify the start date and time of the broadcast.

If the broadcast should start at midnight at the start of a day, specify 00:00.

teams
Optional array of references to Team — The Teams table field is used to select the teams which members need to see the broadcast. This table field is available only when the “Members of the following team(s)” visibility option is selected.

Keep in mind that, when a team is selected which has members from other accounts, then these members will also get to see the broadcast.

time_zone
Required enum, default: the time zone of the account user — The Time zone field is used to select the time zone that applies to the dates and times specified in the Start and End fields.
translations
Optional array of references to Broadcast Translations
updated_at
Readonly datetime — The date and time of the last update of the broadcast. If the broadcast has no updates it contains the created_at value.
visibility
Required enum, default: all_of_account — The Visible for options are used to define the target audience of the broadcast. Valid values are:
  • all_of_account: All people of the account
  • account_specialists: All specialists of the account
  • members_of_teams: Members of the following team(s)
  • covered_for_any: People covered for any of the service instances of the account
  • covered_for: People covered for the following service instance(s)

When the option for the specialists of the account is selected, the message also gets broadcasted for people from other accounts who have the Specialist role of the account.