Skip to main content

Broadcasts

Broadcasts lets an administrator compose a message once and deliver it to many people at once as Microsoft Teams direct messages, sent by one of your AI agents. It is intended for announcements that need to reach a defined group — a maintenance window, a policy change, a service disruption — without anyone assembling a recipient list by hand.

Inside the Beak AI Runtime web app, Broadcasts appears in the left-hand navigation under Engagement — the group for surfaces where the platform reaches out to people. That is the opposite direction from the Runtime's Notifications page, which is the inbox of messages that have reached you.

Access​

Broadcasts is permission-based. The relevant permissions are:

PermissionAllows
broadcasts:readSee the Broadcasts page and its history
broadcasts:createCompose a draft, search directory groups, preview an audience
broadcasts:updateEdit an existing draft
broadcasts:sendSend a test message and schedule a broadcast
broadcasts:deleteDelete a draft or cancel a scheduled broadcast

None of these belong to the default user or viewer roles, so out of the box only administrators can reach the page. To let a wider group broadcast, grant the relevant permissions to a role from Settings → authorization. Because the permissions are separate, you can grant a team the ability to draft and preview (broadcasts:read + broadcasts:create) while reserving the ability to actually send (broadcasts:send) for a smaller group.

Directory lookups are performed with a service principal, so the platform must be configured with GRAPH_TENANT_ID, GRAPH_CLIENT_ID, and GRAPH_CLIENT_SECRET for audience building to work. Without them the audience tabs return a configuration error.

Composing a Broadcast​

Select New broadcast to open the composer.

  • Title — Optional. Internal label used to identify the broadcast in the history list. It is not shown to recipients.
  • Message — The message body, written in Markdown. This is what recipients receive.
  • Target agent — The agent that delivers the message. Recipients see the broadcast as a direct message from that agent, in the same conversation they already use with it.

Choosing an Audience​

The audience builder offers three ways to define who receives the broadcast.

  • Attribute filter — Build one or more conditions against Microsoft Entra user attributes, such as department equals Finance or jobTitle startsWith Engineer. Multiple conditions combine with and, so every condition must match for a user to be included.
  • Group — Search Entra groups by name and select one. Type-ahead returns up to twenty matches, and matching is tokenised, so typing finance will find Corporate Finance Team.
  • CSV — Paste or upload an explicit list of email addresses. Addresses are validated, lower-cased, and de-duplicated.

Previewing the Audience​

Select Preview audience before sending. The preview resolves the audience against the directory and reports how many people currently match, along with a sample of the first several names.

Resolution happens when you preview and again when you schedule — not when the draft is saved. So for a filter-based or group-based audience, someone who joins the department after you save the draft is still picked up, as long as they match at the moment you schedule. Scheduling is the cut-off: see below.

Sending a Test​

Send test delivers the composed message to you alone, as a direct message from the selected agent. The test is a real delivery through the same path a broadcast uses, so it is the reliable way to confirm formatting and that the agent's Teams connection is working before committing to the full audience.

Scheduling​

Schedule locks the broadcast for delivery at a chosen date and time, which must be in the future.

Scheduling is the point at which the audience is frozen: the recipient list is resolved once, written down, and the broadcast moves from draft to scheduled, with content and audience both read-only from then on.

This means delivery uses that stored list, not a fresh directory lookup — someone who joins the matching department after you schedule will not receive the broadcast, and someone who leaves it still will. This is deliberate: once a broadcast is scheduled, what will be sent and who will receive it are both fixed and auditable. To pick up directory changes, cancel the broadcast, edit the draft, and schedule it again.

A background dispatcher picks up broadcasts whose scheduled time has arrived and delivers them recipient by recipient, recording the outcome of each.

Broadcast History​

The history list shows every broadcast for your tenant, newest first.

Finding a Broadcast​

  • Search — Matches the title, the message body, and the author, across every broadcast in the tenant rather than only the page on screen.
  • Status and Time range — Narrow the list to particular statuses, or to broadcasts created in the last 24 hours, 7, 30 or 90 days.
  • Column filters — The row of boxes under the headers refines what is currently loaded, which is useful for a quick scan within a page you have already narrowed to.
  • Sorting — Select a column header to sort by it; select it again to reverse.
  • Columns — Show or hide columns. Your selection is remembered between visits.
  • Refresh — Choose how often the list refreshes (off, 15s, 30s, 1 minute, 5 minutes), or refresh immediately. Useful while a broadcast moves through scheduled → sending → sent.

The count above the table reads "Showing X of N", where N is the number of broadcasts matching your search and filters — not the number on the current page.

Exporting​

Export CSV and Export PDF download the broadcasts matching your current search and filters, not just the visible page, using the columns you have chosen to show. The PDF also records which filters were applied, so an exported report is self-describing.

Each row shows its status and delivery statistics.

StatusMeaning
draftComposed but not scheduled. Editable and deletable.
scheduledLocked with a delivery time set. Can be cancelled before it starts.
sendingCurrently being delivered to recipients.
sentDelivery finished.
cancelledCancelled by an administrator before delivery began.
failedDelivery could not be completed.

Delivery statistics break down per recipient as sent, failed, skipped, and pending, so a partially successful broadcast shows exactly how many people received it.

Skipped Recipients​

A recipient is marked skipped when the platform has no existing Teams conversation with them for the selected agent. Teams does not permit a bot to start a conversation with someone who has never interacted with it, so a broadcast can only reach people who have messaged that agent at least once.

In practice this means a brand-new agent will reach very few people on its first broadcast. If you are rolling out an agent and intend to use broadcasts with it, encourage an initial interaction first. Check the skipped count on the first few broadcasts to see how much of your intended audience is actually reachable.

Editing, Cancelling, and Deleting​

  • Edit — Available while a broadcast is in draft. Once scheduled, editing is refused so the recorded audience and content cannot drift from what will be delivered.
  • Cancel — Available while a broadcast is scheduled and has not begun sending. The broadcast moves to cancelled and is never delivered.
  • Delete — Removes a draft, along with any recipient records associated with it.

Best Practices​

  • Send a test before the real thing — Send test uses the same delivery path as a real broadcast, so it catches a formatting mistake or a broken Teams connection before the message reaches an audience you cannot recall it from.
  • Read the audience count in the preview — A filter that matches far more or far fewer people than expected usually means a directory attribute is spelled or populated differently than assumed.
  • Watch the skipped count on early broadcasts — It tells you how much of your intended audience the agent can actually reach; a high count on a newly deployed agent is expected rather than a fault.
  • Schedule rather than send blind — Scheduling freezes the recipient list, which gives you an auditable record of exactly who a message was addressed to.
  • Keep broadcast permissions narrow — Because the permissions are separate, a team can hold broadcasts:read and broadcasts:create to draft and preview without holding broadcasts:send.