Create subscriptions

You can subscribe to any agent that supports messaging delivery channels using any HTTP client to receive real-time notifications.

Currently, Ocelloids supports Telegram as a messaging delivery channel, with Discord, Email, and Element coming soon.

In the examples below, we’ll use curl as the HTTP client. To create a subscription, send a POST request to the /subs endpoint with the appropriate authorization header.

For details on the full data structure, see the Subscription schema .

Example Request

This example subscribes to the OpenGov API and delivers notifications to a Telegram chat.

Please replace <YOUR_API_KEY>¹, <YOUR_TELEGRAM_CHAT_ID>² and <YOUR_TELEGRAM_BOT_TOKEN> with your own values.

curl \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
    "agent": "opengov",
    "id": "my-opengov-telegram-sub",
    "args": {
      "networks": ["urn:ocn:polkadot:0"]
    },
    "channels": [{
      "type": "telegram",
      "chatId": "<YOUR_TELEGRAM_CHAT_ID>",
      "token": "<YOUR_TELEGRAM_BOT_TOKEN>"
    }]
}' \
https://api.ocelloids.net/subs

On success, the server returns HTTP 201, and the Telegram bot will start delivering messages to your chat.

Templates

For Telegram, the default message formatting is MarkdownV2. You can also choose HTML or Markdown in your subscription settings if preferred.

Ocelloids allows you to define custom templates to transform notification messages before delivery. Templates are processed using Handlebars , giving you full flexibility to access and format payload data.

If no template is provided, the agent’s default template will be applied (if available). For example, the OpenGov agent has the following default template:

*Referendum {{payload.id}}*
{{#if payload.content.title}}
_{{escapeMarkdownV2 payload.content.title}}_
{{/if}}

*{{payload.humanized.status}}*

{{chain payload.chainId}}
{{~#if payload.info.origin.value.type}}
 · {{payload.info.origin.value.type}}
{{/if}}

{{~#if payload.timeline.willExecuteAtUtc}}
Execute at {{date payload.timeline.willExecuteAtUtc}}
{{/if}}

{{#if payload.content.link}}
[Open in Subsquare]({{payload.content.link}})
{{/if}}