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.

id|username|first_name

Nota: Os valores são seprados pelo delimitador '|' PIPE.

Delimitador '|'

O ShellBot utiliza o caractere '|' PIPE como delimitador padrão, separando os valores retornados pelos métodos. A ordem dos campos é estática e pré-definida pelo método chamador.

Métodos

Todas os métodos disponíveis mantem 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 a função; 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

É retornado um objeto do tipo Message com o seguinte formato.

message_id|update_id|bot_first_name|bot_username|group_id|group_name|message_date|message_text

Nota: O número de objetos pode variar de acordo com o tipo e parâmetros utilizados na execução do método.

Utilize o redirecionador 1>/dev/null no final se deseja omitir o retorno.

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).