> For the complete documentation index, see [llms.txt](https://developer.relaypro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.relaypro.com/docs/relay-broadcasts-api.md).

# Broadcasts

A broadcast is a message that is played out once on devices within the specified group, and no acknowledgement is needed.

A broadcast can be started through a simple `POST` request to our server into our `/broadcasts` endpoint. This can be done through an API platform like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/), through simple curl commands in the shell, or within your codebase.

### Triggering a Broadcast

The `POST` command to send the broadcast should take the following form:

```http
POST /subscribers/{id}/api/v1/broadcasts
Authorization: RelayApiKey {apikey}
Content-type: application/json

{
   "notification": "hello world",
   "groups": ["mygroup"]
}
```

### Headers and Subscriber ID Path

* `apikey` : you should contact Relay to get your API key, as it is not available via self-service. Your key should be included within the Authorization header. Don’t forget to include “RelayApiKey” before your actual key.
* `id` : your subscriber ID, which can be found on the Relay Dash through **Help** → **Server Details** under **Subscriber**

### Required Content

* `notification` : custom message to be spoken on the group of devices. The Relay server will automatically convert your written text into spoken audio (text-to-speech)
* `groups` : a list containing the group names or URNs to send the broadcast to

### Example

The following example shows a curl command that sends a broadcast request up to our server.

```sh
$ export subscriber_id=yourcustomersID
$ export apikey=myapikey123
$ curl -X POST -H "Authorization: RelayApiKey $apikey" "https://api.relaypro.com/subscribers/$subscriber_id/api/v1/broadcasts" -d '{"notification": "All rounds must be done by 10pm tonight.", "groups": ["security1", "security2"]}' -i
```

This curl command broadcasts the message “All rounds must be done by 10pm tonight” to two different groups, security1 and security2. The message will only be broadcasted one time on all devices that are in either of those groups. See what this broadcast looks like on the device in the video below. Notice how no acknowledgement is needed from the user.

{% embed url="<https://www.youtube.com/watch?v=wFJOVJsZ9zE>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.relaypro.com/docs/relay-broadcasts-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.