Telegram

OpenScouter uses Telegram to notify testers about new studies, remind them of pending tasks, and confirm session outcomes. The integration requires a bot token configured in platform settings.

Endpoints

POST /api/telegram/webhook Webhook

Receive incoming Telegram bot updates

This endpoint is registered as the Telegram webhook URL. Telegram calls it automatically for every bot message, callback query, or inline interaction. You do not call this endpoint directly.

Payload (sent by Telegram)

{
  "update_id": 987654321,
  "message": {
    "message_id": 1,
    "from": {
      "id": 123456789,
      "username": "tester_alex"
    },
    "chat": {
      "id": 123456789,
      "type": "private"
    },
    "text": "/start"
  }
}

Response

Return 200 OK to acknowledge receipt. Any non-2xx response causes Telegram to retry.

{ "ok": true }

POST /api/telegram/job-notify JWT

Send a study availability notification to a tester via Telegram

Notifies a specific tester that a new study matching their profile is available. Requires the tester to have connected their Telegram account.

Request body

{
  "testerId": "user_xyz789",
  "jobId": "job_abc123",
  "message": "A new study matching your profile is available. Tap below to view details."
}

Field	Type	Required	Description
`testerId`	string	Yes	Tester to notify
`jobId`	string	Yes	Study to reference in the notification
`message`	string	No	Custom message text. Defaults to the platform template.

Response

{
  "success": true,
  "data": {
    "testerId": "user_xyz789",
    "telegramChatId": 123456789,
    "messageId": 42,
    "sentAt": "2026-03-16T09:05:00Z"
  },
  "error": null,
  "metadata": null
}

Returns 404 if the tester has not connected a Telegram account.

POST /api/telegram/send-job JWT

Broadcast a study notification to all eligible testers via Telegram

Sends a study notification to all testers who match the study’s targeting criteria and have Telegram connected. Use this to drive recruitment at study launch.

Request body

{
  "jobId": "job_abc123",
  "filterBySegment": true
}

Field	Type	Required	Description
`jobId`	string	Yes	Study to broadcast
`filterBySegment`	boolean	No	When `true`, only notifies testers matching the study’s targeting. Defaults to `true`.

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "eligibleTesters": 48,
    "connectedToTelegram": 31,
    "notificationsSent": 31,
    "failedDeliveries": 0
  },
  "error": null,
  "metadata": null
}

POST /api/telegram/setup JWT

Sets the webhook URL on the Telegram bot. Call this endpoint once during initial setup or whenever the server URL changes.

Request body

{
  "webhookUrl": "https://openscouter.com/api/telegram/webhook",
  "allowedUpdates": ["message", "callback_query"]
}

Field	Type	Required	Description
`webhookUrl`	string	Yes	Publicly accessible URL for Telegram to POST updates to
`allowedUpdates`	array of strings	No	Update types to receive. Defaults to all types.

Response

{
  "success": true,
  "data": {
    "webhookSet": true,
    "url": "https://openscouter.com/api/telegram/webhook",
    "botUsername": "OpenScouterBot",
    "confirmedAt": "2026-03-16T08:00:00Z"
  },
  "error": null,
  "metadata": null
}

GET /api/telegram/check-connection JWT

Verify that the Telegram bot is connected and the webhook is active

Returns the current bot connection status and webhook configuration as reported by the Telegram API.

Response

{
  "success": true,
  "data": {
    "connected": true,
    "botUsername": "OpenScouterBot",
    "webhookUrl": "https://openscouter.com/api/telegram/webhook",
    "pendingUpdateCount": 0,
    "lastErrorDate": null,
    "lastErrorMessage": null
  },
  "error": null,
  "metadata": null
}

When connected is false, check lastErrorMessage for the Telegram-reported reason.