Audio Messages API

Play pre-recorded audio messages through security system speakers at customer sites.

Endpoints Overview

Get Audio Messages List

Retrieve all available audio messages for a site.

Endpoint

GET /ext/v1/sites/{site_id}/audio-messages

Request Example

curl -X GET "https://api.chektdev.com/ext/v1/sites/site_123abc/audio-messages" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "data": {
    "audio_messages": [
      {
        "audio_message_id": "audio_001",
        "name": "Alarm Warning",
        "description": "Alarm system warning message",
        "duration_seconds": 15,
        "language": "en-US",
        "category": "alarm"
      },
      {
        "audio_message_id": "audio_002",
        "name": "Entry Announcement",
        "description": "Front door entry announcement",
        "duration_seconds": 5,
        "language": "en-US",
        "category": "announcement"
      },
      {
        "audio_message_id": "audio_003",
        "name": "System Test",
        "description": "System test message",
        "duration_seconds": 10,
        "language": "en-US",
        "category": "test"
      }
    ],
    "total_count": 3
  }
}

Play an Audio Message

Play a specific audio message through the site's speakers.

Endpoint

POST /ext/v1/sites/{site_id}/audio-messages/{audio_message_id}/play

Request Body

{
  "volume": 80,
  "repeat": 1,
  "target_devices": ["speaker_main", "speaker_kitchen"]
}

Request Fields

Request Example

curl -X POST "https://api.chektdev.com/ext/v1/sites/site_123abc/audio-messages/audio_001/play" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "volume": 80,
    "repeat": 1
  }'

Response (200 OK)

{
  "data": {
    "playback_id": "play_789",
    "audio_message_id": "audio_001",
    "status": "playing",
    "started_at": "2025-01-15T10:30:00Z",
    "volume": 80,
    "repeat": 1,
    "devices": [
      {
        "device_id": "speaker_main",
        "name": "Main Speaker",
        "status": "playing"
      },
      {
        "device_id": "speaker_kitchen",
        "name": "Kitchen Speaker",
        "status": "playing"
      }
    ]
  }
}

Audio Message Categories

Playback Status Values

Use Cases

• Alarm Deterrence: Play warning messages when sensors triggered
• Entry Announcements: Announce entry/exit events
• System Testing: Test audio system functionality
• Custom Alerts: Play custom messages for specific events

Alternative Endpoints

Using Reference ID

GET /ref/v1/sites/{account_reference_id}/audio-messages
POST /ref/v1/sites/{account_reference_id}/audio-messages/{audio_message_id}/play

Next Steps

• Arming API - Control system arming
• Zones API - Manage security zones
• Sites API - View site information