API Documentation

REST API for notifications via Telegram and Max. Subscribers, OTP, broadcasts, forms, helpdesk.

POST /v1/send

Send a personal notification to a specific subscriber.

Parameters

subscriber_id string (UUID)

Subscriber UUID (from subscriber list)

text string

Message text (up to 4000 characters). Required if template is not specified

format string

Text format: plain (default), markdown, or html

media object

Media object: {type, url}. Types: photo, video, document

buttons array

Array of button rows: [[{text, url}]] or [[{text, callback_data}]]

template string

Template slug instead of text

vars object

Template variables: {key: value}

permission string

Filter by permission: send only to subscribers with this key

segment string

Filter by segment (tag)

Request example

POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"text": "Order #1042 shipped!",
"format": "markdown",
"buttons": [[{
"text": "Track",
"url": "https://example.com/track/1042"
}]]
}

Response

{
"ok": true,
"message_id": "msg_abc123"
}

Templates

Templates let you reuse text with variables. Created in the dashboard or via API.

Usage: pass template and vars instead of text in /v1/send.

Variables in templates use {{name}} syntax. Example: "Order {{order_id}} delivered".

POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"template": "order_delivered",
"vars": {
"order_id": "1042",
"customer": "John"
}
}

Media & buttons

Attach media files and inline buttons to notifications.

Media types: photo, video, document. Pass the file URL.

Buttons are a 2D array: outer array = rows, inner array = buttons in a row.

  • URL button: {"text": "Open", "url": "https://..."}
  • Callback button: {"text": "Yes", "callback_data": "confirm_123"}
POST /v1/send
 
{
"subscriber_id": "550e8400-e29b-41d4-a716-446655440000",
"text": "Your order is ready",
"media": {
"type": "photo",
"url": "https://example.com/photo.jpg"
},
"buttons": [[
{"text": "Details", "url": "https://..."},
{"text": "Cancel", "callback_data": "cancel_123"}
]]
}

1 media + buttons — supported. Multiple media + buttons — not supported (Telegram limitation). Caption with media: up to 1024 characters (Telegram) / up to 4000 (Max). Text without media — up to 4000 characters.

Related sections

Quick start
First message in 2 minutes: obtain a key, subscribe via deep link, send via curl.
Authentication
How to authenticate API requests with a project-scoped Authorization: Bearer zn_… key.
OTP — confirmation codes
Generate and verify 6-digit codes. Dedicated flow for users without a subscription.