Notify API

Send a Telegram notification to one chat. This is a server-to-server API.

HTTPS no CORS token required

POST https://notify.mohsenfathipour.com/api/v1/

One request sends one text message. HTML formatting is optional.

Try it

Paste an app token and send a real message. The token stays in this page only.

Idle No request sent yet.
The response will appear here.

A separate full-page test form is at /test.

Authentication

Send the token for your app in one of these headers:

Authorization: Bearer <token>

or

X-Api-Key: <token>

Each app has its own token. Ask the notify owner to add a token for your app. There is no self-service key API.

Request body

Content-Type: application/json

Field Type Required Notes
message string yes 1 to 4096 characters. Plain text by default.
parse_mode string no HTML or MarkdownV2. Omit for plain text.
message_type string no Only text is supported. Default: text.
disable_notification boolean no Send silently. Default: false.

Examples

Plain text

curl -s -X POST https://notify.mohsenfathipour.com/api/v1/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Deploy finished on rates.boodje.com"}'

HTML

curl -s -X POST https://notify.mohsenfathipour.com/api/v1/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"<b>Deploy finished</b>\n<a href=\"https://rates.boodje.com\">Open rates</a>","parse_mode":"HTML"}'

HTML must be valid Telegram HTML. A bad tag returns 502.

Silent

{
  "message": "Nightly report is ready",
  "disable_notification": true
}

Success

200

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

Errors

Status Meaning Body
400Body is not valid JSON.{"ok":false,"error":"..."}
401Token is missing or invalid.{"ok":false,"error":"..."}
404Path is not /api/v1/.{"ok":false,"error":"Not found"}
405Method is not POST.{"ok":false,"error":"Method not allowed"}
422Missing message, too long, wrong type, or wrong parse_mode.{"ok":false,"error":"..."}
502Telegram rejected the message or was unreachable.{"ok":false,"error":"Telegram delivery failed"}

Health

GET /health

{"ok":true,"service":"notify"}

Notes

Adding an app

Ask the notify owner to add a token to .env:

NOTIFY_TOKENS=rates:<token>,uptime:<token>,app3:<token>

App names use lowercase letters, digits, _, and -.