telegram-bot-bash/examples/webhook/README.md

Examples

Bashtbot webhook example

Webhooks

Bashbot default mode is to poll Telegram server for updates but Telegram offers webhook as a more efficient method to deliver updates. If your server is reachable from the Internet you can use the methods described here.

You need a valid SSL certificate or Telegram will refuse to deliever update via webhook. A self signed certificate will not be sufficient.

Setup Apache webhook

Prerequisite: An Apache webserver with a valid SLL certificate chain and php enabled.

Prepare Apache to forward webhook to Bashbot:

• install bashbot as described in Bashbot Installation
• create file data-bot-bash/webhook-fifo-<botname> ( as in botconfig.jssh)
• run bashbot.sh init to setup bashbot to run as same user as Apache (e.g. www)
• go to apache web root and create directory telegram/<your_bot_token>
• copy all files from examples/webhook to new directory and change to it
• write bashbot installation directory as first line to file BASHBOT_HOME
• execute php index.php

Every call to webhook https://<yourservername>/telegram/<your_bot_token>/ will execute index.php and write received JSON to file data-bot-bash/webhook-fifo-<botname>. E.g. the URL https://<yourservername>/telegram/<your_bot_token>/?json={"test":"me"} will append {"test":"me"} to the file data-bot-bash/webhook-fifo-<botname>.

Now your Apache is ready to forward data to Bashbot.

Default webhook processing

To enable update processing delete the file data-bot-bash/webhook-fifo-<botname> after your webhook is working manually. All webhook calls are now forwarded to bin/process_update.sh for processing.

Every incoming Telegram update load Bashbot once for processing one command. Even it seems overkill to load Bashbot on every incoming update, it's more responsive and create less server load than polling Telegram

Default webhook has the following limitations:

• no startup actions
• no background and interactive jobs
• addons and TIMER_EVENTS are not working

Workaround for running new background jobs is to execute ./bashbot.sh resumeback after starting a new background job.

Full webhook processing

Use this method in case you need addons, TIMER or interactive scripts with webhook.

1. Default webook method must work first!
2. Create fifo: mkfifo data-bot-bash/webhook-fifo-botname
3. Start Bashbot in batch mode: bin/process-batch.sh --startbot --watch data-bot-bash/webhook-fifo-<botname>

In batch mode Bashbot read updates from given file instead of Telegram server. --startbot loads the addons, start the TIMER and trigger all startup actions. --watch instructs Bashbot to watch for new updates instead of stop on EOF.

To switch back to default processing delete fifo data-bot-bash/webhook-fifo-<botname> and kill bin/process-batch.sh.

Enable webhook on Telegram side

To get updates via webhook your server must be reachable from the internet and you must instruct Telegram where to deliver updates, this is done by calling bashbot function set_webhook.

Example:

bin/any_command.sh set_webhook "https://myserver.com/telegram"

instruct Telegram to use the URL https://myserver.com/telegram/<your_bot_token>/ to deliver updates. After you enable webhook to deliver Telegram updates it's no more possible to poll updates with bashbot.sh start.

To stop delivering of Telegram updates via webhook run bin/any_command.sh delete_webhook.

Important: Telegram will refuse to deliver updates if your webhook has no valid SSL certificate chain.

Bash webhook

A pure bash webhook implementaition is not possible without additional software because Telegram deliver updates only over secure TLS connections and if a valid SSL certificate chain exists.

socat looks like a tool we can use to listen for Telegram updates from bash scripts, let's see ...

$$VERSION$$ v1.45-dev-55-g5dd24c3