Telegram webhook

POST

/wp-json/wp2tutor-bot/telegram/v1/webhook/{bot_id}

const url = 'https://example.com/wp-json/wp2tutor-bot/telegram/v1/webhook/12';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"update_id":1,"message":{"message_id":1,"chat":{"id":123456789},"text":"Hello"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/wp-json/wp2tutor-bot/telegram/v1/webhook/12 \
  --header 'Content-Type: application/json' \
  --data '{ "update_id": 1, "message": { "message_id": 1, "chat": { "id": 123456789 }, "text": "Hello" } }'

Inbound Telegram Bot API webhook. Public URL: no cookie/nonce. PHP reads the raw body, json_decode, takes text and chat.id from message or edited_message, replies via AnswerService (embedding diagnostics) and sendMessage. The secret is not in the query string: header X-Telegram-Bot-Api-Secret-Token must match channel meta (wp2tutor_bot_tg_webhook_secret, fallback wp2tutor_tg_webhook_secret). The same secret_token is sent to Telegram setWebhook (URL …/webhook/{post_id}). Body is {ok} / {ok, error}, not WP_Error {code,message,data}. Disabled channel (quiet) or an update with no text returns 200 {ok: true} so Telegram does not retry.

Parameters

Path Parameters

bot_id

required

integer

WordPress channel post ID, not the Telegram bot id and not the token. Required (path (?P<bot_id>\d+)). Taken from the post ID: the metabox and TelegramSetWebhookService build rest_url( wp2tutor-bot/telegram/v1/webhook/{post_id} ). Allowed CPT: wp2tutor_channel (type telegram) and legacy wp2tutor_tg. <= 0, a foreign post type, or a non-telegram channel — 404 bot_not_found.

Example

Header Parameters

X-Telegram-Bot-Api-Secret-Token

string

Telegram webhook secret. PHP reads x-telegram-bot-api-secret-token. If the channel has no secret — 403 secret_required (header ignored). Empty or mismatch (hash_equals) — 403 forbidden.

Request Body

application/json

Telegram Bot API Update. PHP does not validate the full schema: it needs message or edited_message with non-empty text and chat.id. Empty body or an update without text/chat — 200 {ok: true}. Not JSON — 400 invalid_json.

object

key

additional properties

any

Example

{
  "update_id": 1,
  "message": {
    "message_id": 1,
    "chat": {
      "id": 123456789
    },
    "text": "Hello"
  }
}

Responses

200

Accepted. {ok: true} after a successful reply send, a quiet ack (channel disabled — quiet), empty body, or an update without message/edited_message or without text/chat.id.

application/json

object

required

True — webhook/callback accepted (including a quiet ack). false — see error.

boolean

error

Machine code when ok: false. Telegram/controller: bot_not_found, token_missing, secret_required, forbidden, invalid_json, telegram_api_error. VK JSON: invalid_json, secret_required, forbidden. Not a human message and not a WP_Error object.

string

Example

{
  "ok": true
}

400

token_missing — the channel has no bot token. invalid_json — body is not a JSON object. Body is {ok: false, error} with that code.

application/json

object

required

True — webhook/callback accepted (including a quiet ack). false — see error.

boolean

error

string

Example

{
  "ok": false,
  "error": "token_missing"
}

403

secret_required — webhook secret in channel meta is empty. forbidden — header empty or does not match the secret.

application/json

object

required

True — webhook/callback accepted (including a quiet ack). false — see error.

boolean

error

string

Example

{
  "ok": false,
  "error": "forbidden"
}

404

bot_not_found — no post, not wp2tutor_channel/wp2tutor_tg, telegram driver missing, or wp2tutor_channel type is not telegram.

application/json

object

required

True — webhook/callback accepted (including a quiet ack). false — see error.

boolean

error

string

Example

{
  "ok": false,
  "error": "bot_not_found"
}

500

telegram_api_error — missing token/Telegram\Bot\Api, or sendMessage threw. The webhook was parsed; sending the chat reply failed.

application/json

object

required

True — webhook/callback accepted (including a quiet ack). false — see error.

boolean

error

string

Example

{
  "ok": false,
  "error": "telegram_api_error"
}