mirror of
https://github.com/octoleo/telegram-bot-bash.git
synced 2024-06-03 10:50:52 +00:00
165 lines
19 KiB
HTML
165 lines
19 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<meta http-equiv="Content-Style-Type" content="text/css" />
|
||
<meta name="generator" content="pandoc" />
|
||
<title>Bashobot Documentation - doc/3_advanced.html</title>
|
||
<style type="text/css">code{white-space: pre;}</style>
|
||
<style type="text/css">
|
||
div.sourceCode { overflow-x: auto; }
|
||
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
|
||
margin: 0; padding: 0; vertical-align: baseline; border: none; }
|
||
table.sourceCode { width: 100%; line-height: 100%; }
|
||
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
|
||
td.sourceCode { padding-left: 5px; }
|
||
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||
code > span.dt { color: #902000; } /* DataType */
|
||
code > span.dv { color: #40a070; } /* DecVal */
|
||
code > span.bn { color: #40a070; } /* BaseN */
|
||
code > span.fl { color: #40a070; } /* Float */
|
||
code > span.ch { color: #4070a0; } /* Char */
|
||
code > span.st { color: #4070a0; } /* String */
|
||
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||
code > span.ot { color: #007020; } /* Other */
|
||
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||
code > span.fu { color: #06287e; } /* Function */
|
||
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||
code > span.cn { color: #880000; } /* Constant */
|
||
code > span.sc { color: #4070a0; } /* SpecialChar */
|
||
code > span.vs { color: #4070a0; } /* VerbatimString */
|
||
code > span.ss { color: #bb6688; } /* SpecialString */
|
||
code > span.im { } /* Import */
|
||
code > span.va { color: #19177c; } /* Variable */
|
||
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||
code > span.op { color: #666666; } /* Operator */
|
||
code > span.bu { } /* BuiltIn */
|
||
code > span.ex { } /* Extension */
|
||
code > span.pp { color: #bc7a00; } /* Preprocessor */
|
||
code > span.at { color: #7d9029; } /* Attribute */
|
||
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div id="header">
|
||
<h1 class="title">Bashobot Documentation - doc/3_advanced.html</h1>
|
||
</div>
|
||
<h4 id="home"><a href="../README.html">Home</a></h4>
|
||
<h2 id="advanced-features">Advanced Features</h2>
|
||
<h3 id="access-control">Access control</h3>
|
||
<p>Bashbot offers functions to check what Telegram capabilities like ‘chat admin’ or ‘chat creator’ the given user has:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># return true if user is admin/owner of the bot</span>
|
||
<span class="co"># -> botadmin is stored in file './botadmin'</span>
|
||
<span class="ex">user_is_botadmin</span> <span class="st">"user"</span>
|
||
|
||
<span class="co"># return true if user is creator or admin of a chat</span>
|
||
<span class="ex">user_is_admin</span> <span class="st">"chat"</span> <span class="st">"user"</span>
|
||
|
||
<span class="co"># return true if user is creator of a chat or it's a one to one chat</span>
|
||
<span class="ex">user_is_creator</span> <span class="st">"chat"</span> <span class="st">"user"</span>
|
||
|
||
<span class="co"># examples:</span>
|
||
<span class="ex">user_is_botadmin</span> <span class="st">"</span><span class="va">${USER[ID]}</span><span class="st">"</span> <span class="kw">&&</span> <span class="ex">send_markdown_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"You are *BOTADMIN*."</span>
|
||
|
||
<span class="ex">user_is_admin</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"</span><span class="va">${USER[ID]}</span><span class="st">"</span> <span class="kw">&&</span> <span class="ex">send_markdown_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"You are *CHATADMIN*."</span></code></pre></div>
|
||
<p>In addition you can check individual capabilities of users as you must define in the file <code>./botacl</code>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># file: botacl</span>
|
||
<span class="co"># a user not listed here, will return false from 'user_is_allowed'</span>
|
||
<span class="co">#</span>
|
||
<span class="co"># Format:</span>
|
||
<span class="co"># user:ressource:chat</span>
|
||
|
||
<span class="co"># allow user 123456789 access to all resources in all chats</span>
|
||
<span class="ex">123456789</span>:*:*
|
||
|
||
<span class="co"># allow user 12131415 to start bot in all chats</span>
|
||
<span class="ex">12131415</span>:start:*
|
||
|
||
<span class="co"># allow user 987654321 only to start bot in chat 98979695</span>
|
||
<span class="ex">987654321</span>:start:98979695
|
||
|
||
<span class="co"># * are only allowed on the right hand side and not for user!</span>
|
||
<span class="co"># the following exaples are NOT valid!</span>
|
||
<span class="ex">*</span>:*:*
|
||
<span class="ex">*</span>:start:*
|
||
<span class="ex">*</span>:*:98979695</code></pre></div>
|
||
<p>You must use the function <code>user_is_allowed</code> to check if a user has the capability to do something. Example: Check if user has capability to start bot.</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"> <span class="kw">case</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span><span class="kw"> in</span>
|
||
<span class="co">################################################</span>
|
||
<span class="co"># GLOBAL commands start here, only edit messages</span>
|
||
<span class="st">'/start'</span>*<span class="kw">)</span>
|
||
<span class="ex">user_is_botadmin</span> <span class="st">"</span><span class="va">${USER[ID]}</span><span class="st">"</span> <span class="kw">&&</span> <span class="ex">send_markdown_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"You are *BOTADMIN*."</span>
|
||
<span class="kw">if</span> <span class="ex">user_is_allowed</span> <span class="st">"</span><span class="va">${USER[ID]}</span><span class="st">"</span> <span class="st">"start"</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="kw">;</span> <span class="kw">then</span>
|
||
<span class="ex">bot_help</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span>
|
||
<span class="kw">else</span>
|
||
<span class="ex">send_normal_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"You are not allowed to start Bot."</span>
|
||
<span class="kw">;;</span>
|
||
<span class="kw">esac</span></code></pre></div>
|
||
<p><strong>See also <a href="6_reference.html">Bashbot User Access Control functions</a></strong></p>
|
||
<h3 id="interactive-chats">Interactive Chats</h3>
|
||
<p>To create interactive chats, write <em>(or edit the ‘exmaples/question.sh’ script)</em> a bash <em>(or C or python)</em> script, make it executable and then use the ‘startproc’ function to start the script. The output of the script will be sent to the user and user input will be sent to the script. To stop the script use the function ‘killprog’</p>
|
||
<p>The output of the script will be processed by ‘send_messages’ to enable you to not only send text, but also keyboards, files, locations and more. Each newline in the output will start an new message to the user, to have line breaks in your message you can use ‘mynewlinestartshere’.</p>
|
||
<p>To open up a keyboard in an interactive script, print out the keyboard layout in the following way:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat? mykeyboardstartshere [ </span><span class="dt">\"</span><span class="st">Yep, sure</span><span class="dt">\"</span><span class="st"> , </span><span class="dt">\"</span><span class="st">No, highly unlikely</span><span class="dt">\"</span><span class="st"> ]"</span></code></pre></div>
|
||
<p>Same goes for files:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat? myfilelocationstartshere /home/user/doge.jpg"</span></code></pre></div>
|
||
<p>And buttons:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat. mybtextstartshere Klick me myburlstartshere https://dealz.rrr.de"</span></code></pre></div>
|
||
<p>And locations:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat. mylatstartshere 45 mylongstartshere 45"</span></code></pre></div>
|
||
<p>And venues:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat. mylatstartshere 45 mylongstartshere 45 mytitlestartshere my home myaddressstartshere Diagon Alley N. 37"</span></code></pre></div>
|
||
<p>You can combine them:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in chat? mykeyboardstartshere [ </span><span class="dt">\"</span><span class="st">Yep, sure</span><span class="dt">\"</span><span class="st"> , </span><span class="dt">\"</span><span class="st">No, highly unlikely</span><span class="dt">\"</span><span class="st"> ] myfilelocationstartshere /home/user/doge.jpg mylatstartshere 45 mylongstartshere 45"</span></code></pre></div>
|
||
<p>Please note that you can either send a location or a venue, not both. To send a venue add the mytitlestartshere and the myaddressstartshere keywords.</p>
|
||
<p>New in v0.6: To insert a linebreak in your message you can insert <code>mynewlinestartshere</code> in your echo command:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="bu">echo</span> <span class="st">"Text that will appear in one message mynewlinestartshere with this text on a new line"</span></code></pre></div>
|
||
<p>New in v0.7: In case you must extend a message already containing a location, a file, a keyboard etc., with additionial text simply add <code>mytextstartshere additional text</code> at the end of the string:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="va">out=</span><span class="st">"Text that will appear mylatstartshere 45 mylongstartshere 45"</span>
|
||
<span class="kw">[[</span> <span class="st">"</span><span class="va">$out</span><span class="st">"</span> <span class="ot">!=</span> *<span class="st">'in chat'</span>*<span class="kw"> ]]</span> <span class="kw">&&</span> <span class="va">out=</span><span class="st">"</span><span class="va">$out</span><span class="st"> mytextstartshere in chat."</span>
|
||
<span class="bu">echo</span> <span class="st">"</span><span class="va">$out</span><span class="st">"</span></code></pre></div>
|
||
<p>Note: Interactive Chats run independent from main bot and continue running until your script exits or you /cancel if from your Bot.</p>
|
||
<h3 id="background-jobs">Background Jobs</h3>
|
||
<p>A background job is similar to an interactive chat, but runs in the background and does only output massages and does not get user input. In contrast to interactive chats it’s possible to run multiple background jobs. To create a background job write a script or edit ‘examples/notify.sh’ script and use the funtion <code>background</code> to start it:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">background</span> <span class="st">"examples/notify.sh"</span> <span class="st">"jobname"</span></code></pre></div>
|
||
<p>All output of the script will be sent to the user, to stop a background job use:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">killback</span> <span class="st">"jobname"</span></code></pre></div>
|
||
<p>You can also suspend and resume the last running background jobs from outside bashbot, e.g. in your startup schripts:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">./bashbot.sh</span> suspendback
|
||
<span class="ex">./bashbot.sh</span> resumeback</code></pre></div>
|
||
<p>If you want to kill all background jobs permantly run:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">./bashbot.sh</span> killback</code></pre></div>
|
||
<p>Note: Background Jobs run independent from main bot and continue running until your script exits or you stop if from your Bot. Backgound Jobs will continue running if your Bot is stopeda and must be terminated, e.g. by <code>bashbot.sh killback</code></p>
|
||
<h3 id="inline-queries">Inline queries</h3>
|
||
<p><strong>Inline queries</strong> allow users to send commands to your bot from every chat without going to a private chat. An inline query is started if the user type the bots name, e.g. <span class="citation">@myBot</span>. Everything after <span class="citation">@myBot</span> is immediatly send to the bot.</p>
|
||
<p>In order to enable <strong>inline mode</strong>, send <code>/setinline</code> command to <span class="citation">[@BotFather]</span>(https://telegram.me/botfather) and provide the placeholder text that the user will see in the input field after typing your bot’s name.</p>
|
||
<p>The following commands allows you to send ansers to <em>inline queries</em>. To enable bashbot to process inline queries set <code>INLINE="1"</code> in ‘mycommands.sh’.</p>
|
||
<p>To send messsages or links through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"article"</span> <span class="st">"Title of the result"</span> <span class="st">"Content of the message to be sent"</span></code></pre></div>
|
||
<p>To send photos in jpeg format and less than 5MB, from a website through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"photo"</span> <span class="st">"A valid URL of the photo"</span> <span class="st">"URL of the thumbnail"</span></code></pre></div>
|
||
<p>To send standard gifs from a website (less than 1MB) through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"gif"</span> <span class="st">"gif url"</span></code></pre></div>
|
||
<p>To send mpeg4 gifs from a website (less than 1MB) through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"mpeg4_gif"</span> <span class="st">"mpeg4 gif url"</span></code></pre></div>
|
||
<p>To send videos from a website through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"video"</span> <span class="st">"valid video url"</span> <span class="st">"Select one mime type: text/html or video/mp4"</span> <span class="st">"URL of the thumbnail"</span> <span class="st">"Title for the result"</span></code></pre></div>
|
||
<p>To send photos stored in Telegram servers through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"cached_photo"</span> <span class="st">"identifier for the photo"</span></code></pre></div>
|
||
<p>To send gifs stored in Telegram servers through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"cached_gif"</span> <span class="st">"identifier for the gif"</span></code></pre></div>
|
||
<p>To send mpeg4 gifs stored in Telegram servers through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"cached_mpeg4_gif"</span> <span class="st">"identifier for the gif"</span></code></pre></div>
|
||
<p>To send stickers through an <em>inline query</em>:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="ex">answer_inline_query</span> <span class="st">"</span><span class="va">${iQUERY[ID]}</span><span class="st">"</span> <span class="st">"cached_sticker"</span> <span class="st">"identifier for the sticker"</span></code></pre></div>
|
||
<p>See also <a href="6_reference.html">mycommands.sh</a> for more information.</p>
|
||
<h4 id="prev-getting-started"><a href="2_usage.html">Prev Getting started</a></h4>
|
||
<h4 id="next-expert-use"><a href="4_expert.html">Next Expert Use</a></h4>
|
||
<h4 id="version-v0.90-dev2-0-gec85636"><br /><span class="math display"><em>V</em><em>E</em><em>R</em><em>S</em><em>I</em><em>O</em><em>N</em></span><br /> v0.90-dev2-0-gec85636</h4>
|
||
</body>
|
||
</html>
|