> 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-alerts-api/triggering-an-alert.md).

# Triggering an Alert

An alert is a message that is played out on devices within a specified group every 30 seconds until it is acknowledged.

An alert can be started through a simple `POST` request to our server into our `/alerts` endpoint. 

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

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

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

### Headers and Subscriber ID Path

* `apikey` : If you are on the enterprise plan, you can create an API key by navigating to **Help** → **API Keys** in [Relay Dash](https://dash.relaypro.com/api-keys). 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 [Relay Dash](https://dash.relaypro.com/diagnostic-logs) through **Help** → **Diagnostic Logs** → **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 alert to.

### Example

The following example is a curl command that sends an alert 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/alerts" -d '{"notification": "Cleanup needed in the lounge", "groups": ["housekeeping"]}' -i

HTTP/2 200 
date: Mon, 11 Dec 2023 14:31:36 GMT
content-type: application/json
content-length: 38
server: nginx/1.20.0
location: /subscribers/xxx/api/v1/alerts/P9CThKfTsEbJx23trAArHCD

{"task_id":"P9CThKfTsEbJx23trAArHCD"}
```

This curl command alerts the group “housekeeping” that there is “Cleanup needed in the lounge”. The alert will continue to sound on a user’s device every 30 seconds until it is acknowledged by the user tapping the talk button. Once the user taps the talk button, the alert will stop sounding on the device. If the user does not acknowledge the alert after 5 minutes, the alert will timeout and cease playing. See what this alert looks like on the device in the video below.

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