Developer documentation

From Channel creation to first smart message

Build a Universal Message visually, export an exact OpenAPI 3.1 contract, and integrate it from your server without guessing payload fields.

1. Create a Channel

Generate a scoped API key and store the secret only on your server.

2. Pair a recipient

Request a single-use QR for your own external user ID.

3. Send a V2 Stage Set message

Publish the validated Stage Set, then send its immutable publication ID with a stable idempotency key.

Quickstart request

curl -X POST https://api.alertchannels.com/v1/messages \
  -H "Authorization: Bearer aru_live_<key-id>.<secret>" \
  -H "Idempotency-Key: order-84571-shipped-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "bG8mx",
    "external_user_id": "customer-1001",
    "language_code": "en",
    "stage_set_publication_id": "mss_<validated-publication-id>",
    "title": "Order shipped",
    "description": "Order #84571 is on the way.",
    "priority": "normal",
    "client_reference": "order-84571-status-shipped"
  }'

API key scopes

Know exactly what every API key scope allows

Choose the smallest scopes your server needs, review their protected operations, and copy an example in your preferred language.

OpenAPI 3.1 workflow

Generate the contract from the message you already designed

Compose validates every Atomic View, Atomic Interaction, reusable block, Ready Message, group, and Stage against the same V2 contract used by Web, Android, iOS, and PDF before producing OpenAPI YAML.

Open API generator

Compose the real message

Choose the Channel, recipient, Atomic content, reusable blocks, Ready Message, and delivery options your integration needs.

Select OpenAPI 3.1

Open Developer integration in Compose and select OpenAPI. The contract updates from the current draft immediately.

Download and import

Download the YAML, then import it into Postman, Insomnia, Swagger tooling, or OpenAPI Generator.

Call from your server

Set the API key as a Bearer token and send a unique Idempotency-Key for every logical message.

How V2 composition maps to OpenAPI

Atomic Views are typed content leaves. Each has a stable node identity, registered type, and schema-validated data. V2 does not expose variants.

Interactions are typed recipient actions and inputs. Groups determine layout and semantics while the Stage Set determines lifecycle and transitions.

The generated contract includes the complete request envelope, Bearer authentication, Idempotency-Key, path parameters, response codes, and the concrete payload shape of the current draft.

Keep API keys on your server. Never embed them in Web, Android, or iOS client code.

V2 composition example

"root_group": {
  "kind": "group",
  "node_id": "order_status",
  "semantic_role": "content",
  "layout": {
    "mode": "stack",
    "gap": "spacing.md",
    "align": "stretch",
    "justify": "start",
    "direction": "logical",
    "compact_behavior": "stack"
  },
  "children": [
    {
      "kind": "view",
      "node_id": "message_body",
      "view": {
        "block_id": "message_body",
        "type": "text",
        "data": { "content": "Order #84571 is on the way." }
      }
    }
  ]
}

Canonical registries

Every supported V2 Atomic type, in one place

Use these identifiers in Atomic leaves. Composer provides schema-safe fields and samples for every type, while reusable blocks and Ready Messages expand into the same V2 composition tree.

View types

Interaction types

Browse all Atomic View types18 types

text

list

key_value

table

metric

chart

progress

time_counter

image

media

document

barcode

verification_code

timeline

map

schedule

math

diagram

Browse all Atomic Interaction types14 types

action

choice

text_input

otp_input

number_input

date_time_input

form_submit

upload

location_capture

scan

signature_capture

authentication

navigation

utility