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 a Basic Authentication header. The username can be any string, but the password must be your API Key generated by Airtame Cloud.
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>ExternalSystem</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>ExternalSystem</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></event> <urgency>Immediate</urgency> <severity>Severe</severity> <certainty>Observed</certainty> <senderName></senderName> <headline></headline> <description></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.