# 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` : 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 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>" %}


---

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