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 Universal Message

Send the canonical Universal Message document 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",
    "universal_message": {
      "contract_id": "alertchannels.universal-message-authoring.v1",
      "version": 1,
      "target_contract_id": "alertchannels.universal-message-document.v1",
      "target_document_version": 1,
      "message": {
        "title": "Order shipped",
        "description": "Order #84571 is on the way.",
        "priority": "normal"
      },
      "views": [],
      "interactions": [],
      "policies": {
        "security": {},
        "privacy": {},
        "delivery": {},
        "presentation": {}
      },
      "fallback": { "text": "Order #84571 shipped" },
      "metadata": { "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 is the safest API designer: every selected View and Interaction is validated against the same frozen registries used by Web, Android, and iOS before the OpenAPI YAML is produced.

Open API generator

Compose the real message

Choose the Channel, recipient, Views, Interactions, and delivery options that 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 Views and Interactions map to OpenAPI

Views are rendered content blocks. Each block has a stable id, registry type, supported variant, and schema-validated data.

Interactions are recipient actions or inputs. They use the same four-field block shape, so generated clients can model both arrays consistently.

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.

Universal Message block example

"views": [
  {
    "id": "message_body",
    "type": "text",
    "variant": "default",
    "data": { "text": "Order #84571 is on the way." }
  }
],
"interactions": [
  {
    "id": "open_tracking",
    "type": "link",
    "variant": "open_url",
    "data": { "target_ref": "https://example.com/orders/84571" }
  }
]

Canonical registries

Every supported type and variant, in one place

Use these identifiers in Universal Message blocks. The Compose toolboxes provide the schema-safe fields and samples for every pair, while the OpenAPI generator packages your selected pairs into an integration-ready contract.

View types

125

View variants

Interaction types

Interaction variants

Browse all View types and variants48 types

text

default · highlighted · compact · badge

rich_text

default · article · compact · html

markdown

default · documentation

code

default · diff · terminal

quote

default · testimonial

list

simple · grouped · ranked

key_value

compact · card · financial

table

compact · responsive · comparison

grid

cards · tiles

checklist

static · progress

status

default · success · warning · danger · banner

progress

bar · steps · circular

gauge

radial · linear

time_counter

countdown · elapsed · deadline

verification_code

challenge_time · one_time_display · pairing

metric

card · delta · compact · summary · distribution

chart

bar · line · area · pie · donut

comparison

side_by_side · before_after

trend

sparkline · timeline

image

single · hero

gallery

grid · carousel

video

inline · poster

audio

player · voice_note

document

preview · summary

attachment

downloadable · bundle

barcode

qr · code128

timeline

vertical · compact

workflow

steps · status_map

profile

person · organization

contact

person · business

location

address · coordinates

map

pin · route

calendar

event · schedule

receipt_summary

retail · restaurant

transaction_summary

debit_credit · transfer · card_payment

invoice_summary

default · overdue

line_items

retail_compact · invoice_table

ticket_summary

event · travel · boarding_pass

prescription_summary

default · refill

bill_summary

utility · telecom · medical · government_fee

appointment_summary

healthcare · service · government

claim_summary

insurance · warranty

shipment_summary

parcel · delivery

credential_summary

certificate · permit · membership · identity

attendance_summary

school · workforce

order_summary

retail · delivery · service

statement_summary

financial · usage

reservation_summary

hotel · restaurant · service

Browse all Interaction types and variants20 types

link

open_url · deep_link · open_record · open_directions

download

single_file · document · bundle

copy

value · code · reference

share

message · document · receipt

contact_action

call · email · message

calendar_action

add_event · update_event · remove_event

decision

approve_decline · yes_no · accept_reject · multi_option

poll

single_choice · multiple_choice · ranked_choice

rating

stars · numeric · emoji · nps

reaction

emoji · acknowledgement

confirmation

confirm_cancel · acknowledge

form

inline · dynamic · wizard · survey

upload

single_file · multiple_files · photo_capture · document_scan

signature

draw · type · confirm

otp

challenge_input · totp_verify

location_input

current_location · select_on_map · address_input

date_time_input

date · time · date_time · time_range

workflow_trigger

internal · approval_workflow · automation

callback

https_post · https_put · signed_webhook

command

internal_command · protected_command