Skip to main content

Emergency Alerts integrations - Payload guidelines

  • Updated

Depending on the external system you will be using to trigger alerts, you may have options to customize the payload sent to Airtame. While it is not possible to provide a one-fits-all configuration, these templates are meant to help you in the process of configuring your system to send compliant messages to Airtame.

API Endpoint

Third-party systems must send either CAP messages or Airtame JSON payloads to the following API endpoint. 

A unique URL will be generated by Airtame Cloud while doing the configuration of external links. 

POST https://airtame.cloud/api/v3.0/cloud/public/emergency-alerts

Authentication

Requests must include an API key (provided by Airtame Cloud) for each URL in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Airtame Payload (JSON) - recommended

JSON schema

Content-type must be application/json

  id: string; // unique value is expected
  status: "Initiated" | "Resolved";
  template: AlertTemplate; // Defaults to "high".
  headline: string; // Will appear as title for the alert on the screen
  description?: string; // Will appear as the description for the alert on the screen
  isDrill?: boolean; // true will show the Drill badge on the screen
  expiresAt?: string; // ISO 8601 with timezone.
}

JSON sample file

{
  "id": "alert12345",
  "status": "Initiated",
  "template": "lockdown",
  "headline": "Lockdown in effect",
  "description": "Please remain indoors and secure all entries.",
  "isDrill": false,
  "expiresAt": "2025-04-03T12:30:00Z"
}

Supported values for AlertTemplate:

type AlertTemplate =
  | "high"
  | "medium"
  | "low"
  | "blank"
  | "all-clear"
  | "hold"
  | "secure"
  | "lockdown"
  | "evacuate"
  | "shelter";

CAP Payload (XML)

These sample files follow the CAP standard as documented here: https://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

When sending XML files, Airtame will strictly check the message against the CAP XSD schema. Invalid messages will be rejected by the Airtame system.

Content-type must be application/xml

Initiate an alert

<?xml version="1.0"?>
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2">
  <identifier>a4dcd71cd4828f9ef1dcfb26460ee304</identifier>
  <sender>External system</sender>
  <sent>2025-05-01T03:18:03-05:00</sent>
  <status>Actual</status>
  <msgType>Alert</msgType>
  <scope>Public</scope>
  <info>
    <category>Safety</category>
    <event>Lockdown</event>
    <urgency>Immediate</urgency>
    <severity>Severe</severity>
    <certainty>Observed</certainty>
    <senderName>John Doe</senderName>
    <headline>Headline of the event</headline>
    <description>Description of the situation</description>
    <instruction/>
    <area>
      <areaDesc></areaDesc>
      <circle></circle>
    </area>
  </info>
</alert>

Stop an alert

<?xml version="1.0"?>
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2">
  <identifier>004e7210b70dc2cadc322ef807ad025c</identifier>
  <sender>External system</sender>
  <sent>2025-05-01T03:18:03-05:00</sent>
  <status>Actual</status>
  <msgType>**Cancel**</msgType>
  <scope>Public</scope>
  <references>**%sender%,a4dcd71cd4828f9ef1dcfb26460ee304,2025-05-01T03:18:03-05:00**</references>
  <info>
    <category>Safety</category>
    <event>Lockdown</event>
    <urgency>Immediate</urgency>
    <severity>Severe</severity>
    <certainty>Observed</certainty>
    <senderName>John Doe</senderName>
    <headline>Headline of the event</headline>
    <description>Description of the situation</description>
    <instruction/>
    <area>
      <areaDesc></areaDesc>
      <circle></circle>
    </area>
  </info>
</alert>

How does Airtame read payloads sent by external systems

AlertTemplates:

  • AlertTemplates determine what is going to be displayed on the screen.
  • For CAP structured messages, we use the <urgency> field from the XML to define what to choose between high, medium and low.
  • If Airtame is unable to determine the template to use, the system will always fall back to the high template

Headline and Description

  • The templates are designed to inject customized headline and description values provided by the external system.
  • The content from the headline and description fields is what is injected in the templates. For the SRP templates, only the description is customizable as the headline is set by the protocol.

AlertTemplates values

Related articles