Key Concepts

Routeon is an omnichannel messaging platform. This section explains the domain model behind the API: the entities you create and read, the statuses they move through, and how they connect. All examples focus on SMS (channel 1); the same model applies to the other channels.

Every API call goes to https://client.routeon.io/api/v1, authenticates with the X-API-Key header, and (for OMNI endpoints) returns the standard envelope {"error": <bool>, "data": ...}.

Entity map

Sending

  • Message — a single send to one recipient over one channel. Created with POST /messages; identified by messageId.
  • Omnimessage — an ordered multi-channel fallback cascade to one contact (POST /omnimessages); identified by omniTransactionId plus one messageId per step.
  • Channel — the delivery medium, an integer enum on every send (1 = SMS, 8 = Telegram Gateway, and more).
  • Delivery status — the lifecycle of a message after acceptance (sent, delivered, failed, …), reported via webhooks and via EDR records (GET /edrs).

Identity and access

  • API key and scopes — the credential (X-API-Key) created in the client portal; scopes control which API surfaces the key can call.
  • Sender ID — the approved name or number your messages are delivered from. Bound to one channel; must be Active to send.

Campaigns

  • Broadcast — a bulk campaign launched from a template to an audience; reports campaign-level statuses (CREATED, STARTED, FINISHED, …).
  • Broadcast template — the reusable, pre-approved definition of a campaign: flow steps, content pattern with variables, audience selectors.
  • Content template — a stored message body you can reference from POST /messages instead of an inline payload.

Audience

  • Recipient — a contact record (phoneNumber, optional name, tags, attributes) managed via the Recipients API.
  • Attribute — a typed property on recipients; also the source of {{attribute.<name>}} variables in templates.
  • Tag and Filter — the two ways to define a broadcast audience.

Billing

  • Balance — your prepaid amount per agreement (GET /balance); each delivered message reports its cost, rate, and finalCost.

Verification

  • OTP — one-time-password sends: the isOtp flag for SMS, and the dedicated verify/revoke endpoints for Telegram Gateway.

How the entities relate

API key (scopes) ──authorizes──► POST /messages ──uses──► Sender ID (Active, per channel)
                                      │                        │
                                      ▼                        ▼
                                  messageId ──lifecycle──► Delivery statuses
                                                           (webhooks / GET /edrs)

API key (Broadcasts) ──► Broadcast template ──launch──► Broadcast ──fans out──► Messages
                              │  audience from
API key (Recipients) ──► Recipients (tags, filters, attributes)
  • A message must reference an Active Sender ID registered for its channel.
  • A broadcast launches from a broadcast template, whose audience comes from tags, filters, and explicit recipient lists; its contentPattern is personalized from recipient attributes.
  • Every executed send produces delivery statuses (pushed to your webhook, queryable via EDRs) and a billed cost drawn from your balance.

See the API Reference for the full endpoint catalog.