# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.