Introdução a API

Todos os métodos descritos na documentação são equivalentes ao métodos publicados na API original do telegram. (veja: Telegram métodos). As nomenclaturas dos métodos, funções e variáveis são case sensitive. Ou seja, havendo diferenciação entre caracteres maiúsculos e minúsculos.

Antes de começar é preciso criar um bot por meio do @BotFather seguindo os simples passos. (veja: Criar bot). Após a criação é retornado um id único e exclusivo denominado de token com o qual irá fornecer acesso aos métodos e atualizações do mesmo.

Importando API

Para a utilização dos recursos é necessário importar a API em seu script por meio do comando source ou .

$ source ShellBot.sh

Nota: Caso o arquivo esteja em um diretório diferente do seu projeto, será preciso informar o caminho completo do arquivo. Nâo é necessário aplicar permissão de execução a API.

Inicializando bot

Após importar a API é necessário a inicialização do bot por meio do método ShellBot.init. A inicialização faz com que todos os demais métodos sejam declarados e atrelados ao TOKEN informado, caso contrário uma mensagem de erro será apresentada.

$ ShellBot.init --token <seu_token>

Certifique-se que o bot foi inicializado corretamente consultando suas informações utilizando o método ShellBot.getMe. Este método retorna as informações básicas referentes ao bot. São elas: id, username e first_name.

status|id|username|first_name

Nota: Os valores são separados pelo delimitador especificado.

Delimitador

O ShellBot utiliza o caractere '|' PIPE como delimitador padrão para intercalação dos valores atribuídos e retornados pelos métodos. É possível alterá-lo utilizando o parâmetro -d, --delimiter no método ShellBot.init (versão 5.5 ou superior).

A ordem dos campos é estática e pré-definida pelo método chamador.

Métodos

Todas os métodos disponíveis mantém a mesma nomenclatura dos métodos da API Telegram, precedendo apenas o nome da API antes de cada nome.

Exemplo:

ShellBot.metodo

Cada método possui seus parâmetros, valores e tipos que devem ser passados juntamente com o método; Mantendo a metodologia de comandos Unix/Linux.

Exemplo:

ShellBot.metodo --param1 arg --param2 arg ...

Nota: O argumento é obrigatório quando o parâmetro é informado ou quando há parâmetros obrigatórios.

Os métodos suportam parâmetros longos e curtos. Parâmetros longos são precedidos de -- antes do nome, enquanto os curtos são precedidos de - seguido de um caractere único.

Exemplos:

ShellBot.metodo --param1 arg1 --param2 arg2 ...

ou

ShellBot.metodo -p arg1 -p arg2 ...

É possível mesclar ambos parâmetros.

Exemplo:

ShellBot.metodo -p1 arg1 --param2 arg2

Retorno

Os métodos retornam um valor de status após a sua execução, que pode ser acessado através da variável $?. Esse valor indica se um processo teve êxito ou não. Em caso de êxito o mesmo retorna uma coleção de objetos referentes ao método chamador e o valor de $? será igual 0, caso contrário será igual à 1.

Exemplo:

Verificando se a mensagem foi enviada com sucesso para um determinado usuário.

if ShellBot.sendMessage --chat_id 9999 --text "Mensagem de teste."; then
    echo 'Mensagem enviada com sucesso.'
else
    echo 'Falha ao enviar a mensagem.'
fi

É possível especificar o tipo de retorno de cada método (exceto: ShellBot.getUpdates) através do parâmetro -r, --return no método ShellBot.init (versão 5.5 ou superior) cujo tipo pode ser: json, map ou value.

Exemplo:

Enviando mensagem.

source ShellBot.sh

# Inicializando
# TIPO: json, value ou map
ShellBot.init --token <TOKEN> --return <TIPO>

# Enviando mensagem
ShellBot.sendMessage --chat_id 999999 --text 'mensagem de teste'

Retornos:

• json

{"ok":true,"result":{"message_id":36050,"from":{"id":111111111,"is_bot":true,"first_name":"BotExemplo","username":"botex_bot"},"chat":{"id":999999999,"first_name":"SHAMAN","username":"x_SHAMAN_x","type":"private"},"date":1523386608,"text":"Mensagem de teste"}}

• value (padrão)

true|36052|111111111|true|BotExemplo|botext_bot|999999999|SHAMAN|x_SHAMAN_x|private|1523386825|Mensagem de teste

• map

# /* Nâo verboso */
return[ok]='true'
return[message_id]='36054'
return[from_id]='111111111'
return[from_is_bot]='true'
return[from_first_name]='BotExemplo'
return[from_username]='botex_bot'
return[chat_id]='999999999'
return[chat_first_name]='SHAMAN'
return[chat_username]='x_SHAMAN_x'
return[chat_type]='private'
return[date]='1523386927'
return[text]='Mensagem de teste'

O modo map não retorna dados na saída padrão. (somente modo monitor)

Para acessar o valor retornado é necessário especificar o nome da chave desejada.

Exemplo:

echo ${return[chat_first_name]}

Saída:

SHAMAN

Utilize o redirecionador 1>/dev/null no final se deseja omitir o retorno (modo verboso).

Exemplo:

ShellBot.sendMessage --chat_id 9999 --text 'Mensagem de teste.' 1>/dev/null

Nota: O código de status não é omitido.

Erros

O tratamento de erros é aplicado em dois níveis. Sendo o primeiro pela API interna do ShellBot onde são mapeados erros de sintaxe, parâmetros ou argumentos inválidos. No segundo são tratados os erros gerados pela API do Telegram.

Valores:

Status	Descrição
0	Sucesso
1	Erro

TAG	Ação
API	Trata-se o erro interno, retornando o status 1 e o script ou thread é finalizado.
TG	Trata-se o erro externo, retornando o status 1, porém o script não é finalizado.

Threads

Thread que dizer encadeamento de execução, é uma forma que permite um processo dividir a si mesmo em duas ou mais tarefas que podem ser executadas simultaneamente. O ShellBot permite tratar múltiplas requisições, fazendo com que o bot responda a diversos destinatários e assim evitando o empilhamento de solicitações e por consequência o atraso nas respostas. Para isso é necessário a aplicação correta do operador & no bloco do script. O & faz com que o shell execute uma tarefa em background sem ter que esperar o sinal de termino do processo, criando uma nova instancia para continuar a execução.

Criar thread

Para criar uma ou mais thread's é necessário inserir o bloco de instruções a serem executadas entre parenteses (...) seguido do operador &.

Exemplo:

(
comandos1...
comandos2...
comandos3...
) &

Nota: As instruções são executadas sequencialmente em background até a finalização do processo, retornando ao fluxo do processo pai. Em caso de erro uma mensagem é retornada e a thread é finalizada.

Aplicação

O código abaixo demonstra a criação de thread's e a forma como o bloco de instruções deve ser inserido em seu projeto. O bloco deverá ser constituído de conjunto instruções para tratamento das mensagens, comandos, chamadas à funções ou métodos do bot.

#!/bin/bash

# Importando API
source ShellBot.sh

# Token do bot
bot_token='<TOKEN_AQUI>'

# Inicializando o bot
ShellBot.init --token "$bot_token"

while :
do
    # Obtem as atualizações
    ShellBot.getUpdates --limit 100 --offset $(ShellBot.OffsetNext) --timeout 30

    # Lista as atualizações.
    for id in $(ShellBot.ListUpdates)
    do
    # bloco de instruções
    (
        <COMANDOS AQUI> ...
    ) &  # Criando thread
    done
done

Nota: Remova o operador & se deseja que as requisições sejam tratadas em fila (uma por vez).

Bot Unit Service (systemd)

systemd é um sistema de init usado em distribuições Linux para inicializar o espaço do usuário e gerenciar todos os processos. Utilizando o parâmetro -s, --service na chamada do método ShellBot.init, permite ao usuário criar um Bot Unit Service para gerenciamento posterior do processo via systemd.

Criando serviço.

O procedimento de criação é relativamente simples e rápido. Primeiro é necessário acrescentar o parâmetro -s ou --service ao método ShellBot.init declarado em seu script. Veja o exemplo abaixo:

#!/bin/bash
# bot_script
...

ShellBot.init --token <TOKEN_AQUI> --service --user <usuario>

...

Parâmetro --user é opcional.

Salve as alterações e execute o script como root. O processo de criação e linkagem requer privilégios administrativos.

$ sudo ./bot_script

Nota: Este procedimento deve ser realizado uma única vez.

Atenção: Certifique-se que o script não esteja em execução, caso contrário finalize o processo antes de continuar.

Se o processo tiver êxito será exibido as informações abaixo, caso contrário uma mensagem de erro é retornada.

$ sudo ./bot_script.sh
bot_script.service foi criado com sucesso !!
Habilitando...[OK]
Iniciando...[OK]
● bot_script.service - bot_script.sh - (SHELLBOT)
   Loaded: loaded (/lib/systemd/system/bot_script.service; enabled; vendor preset: enabled)
   Active: active (running) since Thu 2017-09-28 23:53:17 -03; 21ms ago
 Main PID: 8816 (bash)
    Tasks: 7 (limit: 4915)
   CGroup: /system.slice/bot_script.service
           ├─8816 /bin/bash bot_script.sh
           └─8827 curl --silent --request GET https://api.telegram.org/bot123456789:XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXX

set 28 23:53:17 doom systemd[1]: Started bot_script.sh - (SHELLBOT).

Uso: sudo systemctl bot_script.service {start|stop|restart|reload|status}

Nota: Após a criação o parâmetro [-s, --service] e [-u, --user] são removidos automaticamente do script.

A partir de agora o Bot possui um Unit Service rodando em background e qualquer chamada ao mesmo deverá ser realizada via systemd com a seguinte sintaxe:

$ sudo systemctl <comando> <nome.service>

Comando	Descrição
status	Exibe o status do serviço.
stop	Interrompe a execução do serviço.
start	Inicia o serviço.
restart	Reinicia o serviço.
enable	Habilita o serviço na inicialização.
disable	Desativa o serviço.

Para mais informações consulte a documentação do comando man systemctl.