Вебхук Telegram

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":"Привет"}}'
};

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": "Привет" } }'

Входящий вебхук Telegram Bot API. Публичный URL: cookie/nonce не нужны. PHP берёт сырой body, json_decode, из message или edited_message читает text и chat.id, отвечает через AnswerService (embedding diagnostics) и sendMessage. Секрет не в query: заголовок X-Telegram-Bot-Api-Secret-Token должен совпасть с meta канала (wp2tutor_bot_tg_webhook_secret, фоллбэк wp2tutor_tg_webhook_secret). Тот же secret_token уходит в Telegram setWebhook (URL …/webhook/{post_id}). Тело — {ok} / {ok, error}. Это не WP_Error {code,message,data}. Канал выключен (quiet) или апдейт без текста — 200 {ok: true} (чтобы Telegram не ретраил).

Parameters

Path Parameters

bot_id

required

integer

ID поста канала в WordPress, не Telegram bot id и не token. Обязателен (path (?P<bot_id>\d+)). Берётся из ID записи: метабокс и TelegramSetWebhookService подставляют rest_url( wp2tutor-bot/telegram/v1/webhook/{post_id} ). Допустимы CPT wp2tutor_channel (тип telegram) и устаревший wp2tutor_tg. <= 0, чужой post type или канал не telegram — 404 bot_not_found.

Example

Header Parameters

X-Telegram-Bot-Api-Secret-Token

string

Секрет вебхука Telegram. PHP читает x-telegram-bot-api-secret-token. Если у канала секрет не задан — 403 secret_required (заголовок не смотрят). Пустой или не совпал (hash_equals) — 403 forbidden.

Request Body

application/json

Telegram Bot API Update. PHP не валидирует полную схему: нужны message или edited_message с непустым text и chat.id. Пустой body или апдейт без текста/chat — 200 {ok: true}. Не JSON — 400 invalid_json.

object

key

additional properties

any

Example

{
  "update_id": 1,
  "message": {
    "message_id": 1,
    "chat": {
      "id": 123456789
    },
    "text": "Привет"
  }
}

Responses

200

Принято. {ok: true} после успешной отправки ответа, тихого ack (канал выключен — quiet), пустого body, апдейта без message/edited_message или без текста/chat.id.

application/json

object

required

True — вебхук/callback принят (в том числе тихий ack). false — смотри error.

boolean

error

Машинный код при ok: false. Telegram/контроллер: bot_not_found, token_missing, secret_required, forbidden, invalid_json, telegram_api_error. VK JSON: invalid_json, secret_required, forbidden. Не человеческое сообщение и не объект WP_Error.

string

Example

{
  "ok": true
}

400

token_missing — у канала нет bot token. invalid_json — body не JSON-объект. Тело {ok: false, error} с этим кодом.

application/json

object

required

True — вебхук/callback принят (в том числе тихий ack). false — смотри error.

boolean

error

string

Example

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

403

secret_required — секрет вебхука в meta канала пустой. forbidden — заголовок пустой или не совпал с секретом.

application/json

object

required

True — вебхук/callback принят (в том числе тихий ack). false — смотри error.

boolean

error

string

Example

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

404

bot_not_found — нет поста, не wp2tutor_channel/wp2tutor_tg, драйвер telegram недоступен, или у wp2tutor_channel тип не telegram.

application/json

object

required

True — вебхук/callback принят (в том числе тихий ack). false — смотри error.

boolean

error

string

Example

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

500

telegram_api_error — нет token/Telegram\Bot\Api или sendMessage бросил исключение. Вебхук уже разобран; ответить в чат не удалось.

application/json

object

required

True — вебхук/callback принят (в том числе тихий ack). false — смотри error.

boolean

error

string

Example

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