Funções

ShellBot.init

Use essa função para inicializar e definir o conjunto de configurações do bot a partir de uma chave (TOKEN) válida. É retornado um objeto bot em caso de sucesso.

É necessário inciar o bot (ShellBot.init) para obter acesso aos seus métodos.

Uso:

ShellBot.init --token token ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-t, --token <token>	String	Sim	Especificar a chave única de autenticação (TOKEN)
-m, --monitor	nenhum	Não	Ativa o modo monitor do bot. Utilize esse parâmetro para exibir no prompt os eventos do chat, tais como: comandos, mensagens e inicialização de variáveis. Para mensagens é necessário que o bot seja administrador do chat. Veja também: Monitor
-f, --flush	nenhum	Nâo	Limpa a lista offset de atualizações do bot. Se houver registros é retornado o flush_first_id e flush_last_id da lista. Caso contrário seus valores serão iguais a 0 (zero). Quaisquer chamadas, eventos e requisições realizadas serão ignoradas durante o processo de inicialização. Os registros poderão ser recuperados informando o código de deslocamento negativo. Veja: ShellBot.getUpdates para mais informações.
-s, --service	nenhum	Nâo	Cria um Bot Unit Service no sistema de gerenciamento de processos systemd (Nota: requer privilégios de root). Realiza uma chamada em background e habilita o bot na inicialização do sistema. O parâmetro é obrigatório somente se opção -u, --user for informada.
-u, --user <usuario>	string	Não	Define o usuário sob o qual a instância do serviço irá executar. Se o parâmetro for omitido, o usuário atual do sistema será utilizado.
-r, --return <tipo>	String	Nâo	Tipo do dado retornado pelos métodos exceto ShellBot.getUpdates. Tipos suportados: json, map ou value [padrão]. Veja: tipos de retorno
-l, --log_file <arquivo>	string	Nâo	Caminho completo do arquivo de log a ser gerado.
-o, --log_format <formato>	String	Não	Formato padrão de saída do log. Veja: flags de expansão
-d, --delimiter <delimitador>	String	Nâo	Define o delimitador padrão utilizado pela API para intercalação dos valores. (padrão: '|')

Cada bot criado recebe sua chave única de autenticação (TOKEN) para obter privilégios ao invocar seus métodos.

Tipos de retorno

É uma coleção de objetos formatado em um tipo específico de dado e que é retornado após a chamada de um método.

Tipo	Descrição
json	JavaScript Object Notation.
value	Uma coleção de valores separados por um delimitador | [padrão]. Veja o parâmetro: -d, --delimiter
map	Mapeia os valores em um array associativo (não verboso). Inicializa o array com o identificador exclusivo return, cujo o valor é acessado por meio de uma chave utilizando a seguinte sintaxe: ${return[chave]}. Se a mesma chave conter uma coleção de elementos os valores são separados pelo delimitador padrão, exemplo: return[chave]='elemento1|elemento2|elemento3'

Observação: Todos os métodos retornam valores. (exceto: ShellBot.getUpdates)

Exemplo:

ShellBot.sendMessage --chat_id 999999999 --text "mensagem de teste"

Retorno:

• value [padrão]

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

• 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"}}

• map

return[ok]='true'
return[message_id]='36050'
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'

Obs: Modo monitor ativado.

Flags de expansão

A flag de expansão é um identificador único cujo valor dinâmico referente é expandido a cada iteração.

Flag	Descrição
{OK}	Status de retorno do método. (true ou false)
{UPDATE_ID}	Identificador único da atualização.
{MESSAGE_ID}	Identificador exclusivo da mensagem no chat.
{FROM_ID}	Identificador exclusivo do usuário ou bot.
{FROM_IS_BOT}	Se o remetente da mensagem é um bot. (true ou false)
{FROM_FIRST_NAME}	Primeiro nome do usuário ou bot.
{FROM_USERNAME}	Nome do usuário ou bot.
{FROM_LANGUAGE_CODE}	Identificador do idioma do usuário.
{CHAT_ID}	Identificador exclusivo do supergrupo, canal ou grupo.
{CHAT_TITLE}	Título do supergrupo, canal ou grupo.
{CHAT_TYPE}	Tipo do chat. (private, group, supergroup or channel)
{MESSAGE_DATE}	Data em que a mensagem foi enviada no horário do Unix.
{ENTITIES_TYPE}	Tipo da entidade. (mention, hashtag, bot_command, url, email, bold, italic, code, pre, text_link, text_mention)
{BOT_TOKEN}	Chave única de autenticação.
{BOT_ID}	Identificador exclusivo do bot.
{BOT_FIRST_NAME}	Primeiro nome do bot.
{BOT_USERNAME}	Nome do usuário do bot.
{METHOD}	Nome do método chamado.
{RETURN}	Retorno do método.
{BASENAME}	Nome base do script.
{OBJECT_ID}	ID do objeto.
{OBJECT_TYPE}	Tipo do objeto. Pode ser: text, contact, sticker, animation, photo, audio, video, voice, document, venue, location, callback, inline, chosen.
%(FMT)T	Gera a string de data e hora resultante do uso do FMT como um formato string para strftime. ( "Hora atual: %(%H:%M)T" => "Hora atual: 12:30" ).

Padrão: %(%d/%m/%Y %H:%M:%S)T: {BASENAME}: {BOT_USERNAME}: {UPDATE_ID}: {METHOD}: {CHAT_TYPE}: {FROM_USERNAME}: {OBJECT_TYPE}: {OBJECT_ID}: {MESSAGE_TEXT}

ShellBot.token

Retorna o token do bot.

Uso:

ShellBot.token

• Função nao requer parametros.

Retorno:

bot_token

ShellBot.id

Retorna o identificador exclusivo do bot.

Uso:

ShellBot.id

• Função nao requer parametros.

Retorno:

bot_id

ShellBot.username

Retorna o nome de usuario do bot.

Uso:

ShellBot.username

• Função nao requer parametros.

Retorno:

bot_username

ShellBot.first_name

Retorna o primeiro nome do bot.

Uso:

ShellBot.first_name

• Função nao requer parametros.

Retorno:

bot_first_name

ShellBot.regHandleFunction

Registra uma função associando-a a um valor de chamada.

Uso:

ShellBot.RegHandleFunction --function <identificador> --callback_data <valor> ...

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-f, --function <identificador>	String	Sim	Nome da função válida que será executada.
-d, --callback_data <valor>	String	Sim	Valor de chamada. Associa o valor a função especificada.
-a, --args <argumentos>	String	Não	Argumentos a serem passados na chamada da função.

ShellBot.regHandleExec

Registra uma lista de comandos associando-os a um valor de chamada.

Uso:

ShellBot.regHandleExec --command <comandos> --callback_data <valor>

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-c, --command <comandos>	String	Sim	Lista de comandos válidos a serem executados.
-d, --callback_data <valor>	String	Sim	Valor de chamada. Associa o valor a lista especificada.

ShellBot.watchHandle

Use essa função para monitorar e executar as funções registradas por ShellBot.regHandleFunction com os argumentos especificados (se presente).

Uso:

ShellBot.watchHandle --callback_data <valor>

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-d, --callback_data <valor>	String	Sim	Valor associativo a ser monitorado.

ShellBot.TotalUpdates

Retorna o total de atualizações. O valor máximo de resultados é especificado em ShellBot.getUpdates.

Uso:

ShellBot.TotalUpdates

Função não requer parâmetros/argumentos.

ShellBot.ListUpdates

Retorna os índices das atualizações armazenadas. Se o número de atualizações for maior que 1 os resultados são armazenados em um array's indexado.

Uso:

ShellBot.ListUpdates

Função não requer parâmetros/argumentos.

ShellBot.OffsetEnd

Retorna o ID da última atualização. Retorna 0 caso não haja atualizações.

Uso:

ShellBot.OffsetEnd

Função não requer parâmetros/argumentos.

ShellBot.OffsetNext

Retorna o ID da próxima atualização (offset+1)

Uso:

ShellBot.OffsetNext

Função não requer parâmetros/argumentos.

ShellBot.getConfig

Retorna um objeto com as configurações do bot.

Uso:

ShellBot.getConfig

A função não requer parâmetros/argumentos.

ShellBot.ReplyKeyboardMarkup

Use essa função para definir um teclado personalizado a partir da estrutura apontada por variavel. Retorna um objeto ReplyKeyboardMarkup.

Uso:

ShellBot.ReplyKeyboardMarkup --button <variavel>

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-b, --button <variavel>	String	Sim	Variável contendo uma estrutura de um teclado personalizado. Veja também: ShellBot.KeyboardButton
-r, --resize_keyboard <true ou false>	Boolean	Nâo	Solicita aos clientes que redimensionem o teclado verticalmente para um ajuste ideal (por exemplo, faça o teclado menor se houver apenas duas linhas de botões). O padrão é false, caso em que o teclado personalizado é sempre da mesma altura que o teclado padrão do aplicativo.
-t, --one_time_keyboard <true ou false>	Boolean	Nâo	Solicita que os clientes ocultem o teclado assim que ele for usado. O teclado ainda estará disponível, mas os clientes exibirão automaticamente o teclado de letras usual no chat - o usuário pode pressionar um botão especial no campo de entrada para ver o teclado personalizado novamente. O padrão é false.
-s, --selective <true ou false>	Boolean	Nâo	Use esse parâmetro se você quiser mostrar o teclado somente para usuários específicos. Alvos: 1) usuários que são @mencionados no texto do objeto Mensagem; 2) se a mensagem do bot é uma resposta (tem reply_to_message_id), remetente da mensagem original. Exemplo: Um usuário solicita alterar o idioma do bot, bot responde ao pedido com um teclado para selecionar o novo idioma. Outros usuários no grupo não vêem o teclado.

Nota: O array deve ser um array de array.

Estrutura do teclado (KeyboardButton)

A declaração dos elementos no array pode influenciar na forma como os botões são exibidos no Aplicativo. É possível realizar diversas combinações para obter o layout pretendido.

A partir da versão 6.0 a interpretação dos colchetes externos é implícita, ou seja, agora o método ShellBot.ReplyKeyboardMarkup trata o objeto recebido como array de array. Veja também: ShellBot.KeyboardButton

Veja algumas construções válidas:

teclado='["botao1"],["botao2"]'

ou

teclado=‘[“botao1”],[”botao2”,“botao3”]’

ou

teclado='
["1","2","3"],
["4","5","6"],
["7","8","9"],
["0"]
'

Também é possível determinar a ordem das linhas do teclado especificando o índice de cada elemento no array.

teclado[0]='["1","2"]'    # linha 1
teclado[1]='["3","4"]'    # linha 2

ou

teclado[1]='["1","2"]'    # linha 2
teclado[0]='["3","4"]'    # linha 1

Obs: Esse tipo de implementação não querer o uso de vírgulas para delimitação das linhas.

ShellBot.KeyboardButton

Use essa função para criar um objeto KeyboardButton e definir as opções de cada botão.

Uso:

ShellBot.KeyboardButton --button <variavel> --line <linha> --text <texto> ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-b, --button <variavel>	String	Sim	Identificador de uma variável válida. Anexa na variavel o botão criado.
-l, --line <linha>	Integer	Sim	Número da linha.
-t, --text <texto>	String	Sim	Texto do botão.
-c, --request_contact <status>	Boolean	Não	Opcional. Se for true, o número de telefone do usuário será enviado como contato quando o botão for pressionado. Disponível apenas em bate-papo privado.
-o, --request_location <status>	Boolean	Não	Opcional. Se for true, a localização atual do usuário será enviada quando o botão for pressionado. Disponível apenas em bate-papo privado.
-r, --request_poll <enquete>	KeyboardButtonPollType	Não	Se especificado, o usuário será solicitado a criar uma enquete e enviá-la ao bot quando o botão for pressionado. Disponível apenas em bate-papos particulares.

ShellBot.InlineKeyboardButton

Use essa função para criar um objeto InlineKeyboardButton.

Uso:

ShellBot.InlineKeyboardButton --button <identificador> --callback_data <valor> --line <numero>...

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-b, --button <variavel>	string	Sim	Varíavel onde será anexado a estrutura do objeto.
-t, --text <texto>	string	Sim	Texto do botão.
-c, --callback_data <dados>	String	Sim	Dados a serem enviados em uma consulta de retorno ao bot quando o botão é pressionado, 1-64 bytes
-l, --line <numero>	integer	Sim	Número da linha onde o botão será inserido. Esse valor determina sua posição no array da estrutura. É possível adicionar mais botões a mesma linha; Neste caso a sua posição será determinada pela ordem de declaração.
-u, --url <url>	String	Nâo	Url HTTP a ser aberta quando o botão é pressionado.
-q, --switch_inline_query <texto>	String	Nâo	Se configurado, pressionar o botão solicitará ao usuário selecionar um dos seus bate-papos, abrir esse bate-papo e inserir o nome de usuário do bot e a consulta inline especificada no campo de entrada. Pode estar vazio, caso em que apenas o nome de usuário do bot será inserido.
-s, --switch_inline_query_current_chat <texto>	String	Nâo	Se configurado, pressionar o botão irá inserir o nome de usuário do bot e a consulta inline especificada no campo de entrada do bate-papo atual. Pode estar vazio, caso em que apenas o nome de usuário do bot será inserido.

ShellBot.InlineKeyboardMarkup

Use essa função para definir um teclado embutido a partir da estrutura apontada por variavel. Retorna um objeto do tipo InlineKeyboardMarkup.

Uso:

ShellBot.InlineKeyboardMarkup --button <variavel>

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-b, --button <variavel>	String	Sim	Variável contendo um objeto InlineKeyboardButton válido. Veja também: ShellBot.InlineKeyboardButton

ShellBot.ForceReply

Use essa função para definir um objeto de interface de resposta para o usuário. Retorna um objeto ForceReply.

Uso:

ShellBot.ForceReply

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-s, --selective <status>	Boolean	Não	Opcional. Use este parâmetro se desejar forçar a resposta apenas de usuários específicos.

ShellBot.ReplyKeyboardRemove

Use essa função para remoção de teclado personalizado. Retorna um objeto ReplyKeyboardRemove

Uso:

ShellBot.ReplyKeyboardRemove

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-s, --selective <status>	Boolean	Nâo	Opcional. Use este parâmetro se desejar remover o teclado apenas para usuários específicos.

ShellBot.stickerMaskPosition

Cria um objeto e define sua posição onde uma máscara deve ser colocada por padrão.

Uso:

ShellBot.ShellBot.stickerMaskPosition --point <face> --x_shift <eixo-x> --y_shift <eixo-y> --scale <escala>

São mencionados acima somente os parâmetros obrigatórios da função, tendo o … como extensão para os opcionais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-p, --point <face>	string	Sim	A parte da face em relação à qual a máscara deve ser colocada. Os valores são: "forehead”, “eyes”, “mouth”, ou “chin”.
-x, --x_shift <eixo-x>	Float	Sim	Deslocar pelo eixo X medido em larguras da máscara dimensionadas para o tamanho do rosto, da esquerda para a direita. Por exemplo, escolher -1.0 colocará a máscara apenas à esquerda da posição de máscara padrão.
-y, --y_shift <eixo-y>	Float	Sim	Deslocar pelo eixo Y medido em alturas da máscara dimensionadas para o tamanho do rosto, de cima para baixo. Por exemplo, 1.0 colocará a máscara logo abaixo da posição de máscara padrão.
-s, --scale <escala>	Float	Sim	Coeficiente de escala de máscara. Por exemplo, 2.0 significa tamanho duplo.

Retorno
Retorna um objeto do tipo <MaskPosition> com suas definições.

ShellBot.downloadFile

Use essa função para baixar um arquivo do diretório remoto no servidor do Telegram. Retorna um objeto file em caso de sucesso. É gerado um hash para a nomenclatura do arquivo criado com o seguinte formato: <fileDDMMYYYHHMMSSNNNNNNNNN.ext>.

Uso:

ShellBot.downloadFile --file_path <caminho> --dir <destino>

São mencionados acima somente os parâmetros obrigatórios da função.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-f, --file_path <caminho>	String	Sim	Caminho do arquivo contido nos servidores do Telegram. Veja: ShellBot.getFile
-d, --dir <destino>	String	Sim	Diretório destino onde será salvo o arquivo.

ShellBot.inputMedia

Use este método para criar um objeto InputMedia com uma estrutura de propriedades que represetam o elemento a ser enviado, cujo são: animation, video, photo, audio e document. É possível especificar mais de um elemento para a mesma mídia, caso a variável input já contenha um objeto os demais são anexados ao final da lista criando uma coleção de elementos.

Uso:

ShellBot.inputMedia --input <variavel> --type <tipo> ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-i, --input <variavel>	String	Sim	Identificador de uma variável válida que irá armazenar o objeto.
-t, --type <tipo>	String	Sim	Tipo do objeto media a ser criado. (animation, document, audio, photo e video)
-m, --media <midia>	String	Sim	Arquivo para enviar. Passe um file_id para enviar um arquivo que existe nos servidores Telegram (recomendado), passe um URL HTTP para Telegram para obter um arquivo da Internet ou passe @caminho_do_arquivo para carregar um arquivo local usando multipart/form-data.
-c, --caption <legenda>	String	Não	Legenda do objeto com 0 a 200 caracteres.
-p, --parse_mode <modo>	string	Não	Modo de formatação aplicada ao texto enviado (markdown e html).
-b, --thumb <file>	String	Não	Miniatura do arquivo enviado. A miniatura deve estar no formato JPEG e ter menos de 200 kB de tamanho. A largura e a altura de uma miniatura não devem exceder 90. (Somente para: animation, video, document, audio)
-w, --width <largura>	Integer	Nâo	Largura. (Somente para: animation e video)
-h, --height <altura>	Integer	Nâo	Altura. (Somente para: animation e video)
-d, --duration <tempo>	Integer	Não	Duração. (Somente para: animation, video e audio)
-s, --supports_streaming	Boolean	Não	Suporte a streaming. (Somente para: video)
-f, --performer <artista>	String	Nâo	Artista da faixa. (Somente para: audio)
-e, --title <titulo>	String	Nâo	Título da faixa. (Somente para: audio)

ShellBot.InlineQueryResult

Use essa função para criar um coleção de objetos que representa um resultado de uma consulta inline.

Uso:

ShellBot.InlineQueryResult --input <variavel> --type <tipo> ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-i, --input <variavel>	String	Sim	Identificador de uma variável válida que irá armazenar os objetos criados.
-t, --type <tipo>	String	Sim	Tipo do objeto a ser criado. Suporta: audio, document, gif, mpeg4gif, photo, sticker, video, voice, article, contact, location, venue.
-r, --id <identificador>	String	Sim	Identificador exclusivo para este resultado, 1-64 Bytes.
-k, --reply_markup <teclado>	InlineKeyboardMarkup	Não	Interface do teclado personalizado.
-p, --parse_mode <modo>	String	Não	Modo de formatação aplicada ao texto enviado (markdown ou html).
-l, --title <titulo>	String	?	Título do resultado.
-c, --caption <legenda>	String	?	Legenda do objeto.
-d, --description	String	?	Breve descrição do resultado.
-m, --input_message_content <conteudo>	InputMessageContent	?	Conteúdo da mensagem a ser enviada. Veja: InputMessageContent.
-b, --address <local>	String	?	Endereço do local.
-s, --audio_duration <duracao>	Integer	?	Duração de áudio em segundos.
-x, --audio_file_id <identificador>	String	?	Um identificador de arquivo válido para o arquivo de áudio.
-w, --audio_url <url>	String	?	Um URL válido para o arquivo de áudio.
-v, --document_file_id <identificador>	String	?	Um identificador de arquivo válido para o arquivo.
-z, --document_url <_url>	String	?	Um URL válido para o arquivo.
-q, --foursquare_id <quadrante>	String	?	Identificador do quadrante do local, se conhecido.
-a, --foursquare_type <tipo>	String	?	Tipo quadrangular do local. (Por exemplo: arts_entertainment/default, arts_entertainment/aquarium ou food/icecream.)
-f, --gif_duration <duracao>	Integer	?	Duração do GIF.
-u, --gif_file_id <identificador>	String	?	Um identificador de arquivo válido para o arquivo GIF.
-o, --gif_url <url>	String	?	Um URL válido para o arquivo GIF. O tamanho do arquivo não deve exceder 1 MB.
-g, --gif_height <altura>	Integer	?	Altura da GIF.
-n, --gif_width <largura>	Integer	?	Largura da GIF.
-h, --hide_url <status>	Boolean	?	Passe 'true' se você não quiser que o URL seja exibida na mensagem.
-y, --first_name <nome>	String	?	Primeiro nome do contato.
-j, --last_name <sobrenome>	String	?	Último nome do contato.
-S, --vcard <info>	String	?	Dados adicionais sobre o contato na forma de um vCard 0-2048 bytes
-N, --live_period <periodo>	Integer	?	O período em segundos para o qual o local pode ser atualizado deve estar entre 60 e 86400.
-e, --latitude <coordenada>	Float	?	Latitude de localização em graus.
-R, --longitude <coordenada>	Float	?	Longitude de localização em graus.
-D, --mime_type <tipo>	String	?	Tipo MIME do conteúdo do arquivo. Suporta: application/pdf ou application/zip.
-A, --mpeg4_duration <duracao>	Integer	?	Duração do vídeo.
-X, --mpeg4_file_id <identificador>	String	?	Um identificador de arquivo válido para o arquivo MP4.
-G, --mpeg4_height <altura>	Integer	?	Altura de vídeo.
-C, --mpeg4_url <url>	String	?	Uma URL válida para o arquivo MP4. O tamanho do arquivo não deve exceder 1 MB.
-Q, --mpeg4_width <largura>	Integer	?	Largura de vídeo.
-L, --performer <artista>	String	?	Artista do áudio.
-Y, --photo_file_id <identificador>	String	?	Um identificador de arquivo válido da foto.
-V, --photo_url <url>	String	?	Um URL válido da foto. A foto deve estar no formato jpeg. O tamanho da foto não deve exceder 5 MB.
-E, --photo_height <altura>	Integer	?	Altura da foto.
-H, --photo_width <largura>	Integer	?	Largura da foto.
-Z, --sticker_file_id <identificador>	String	?	Um identificador de arquivo válido do adesivo.
-F, --thumb_url <url>	String	?	URL da miniatura do resultado.
-T, --thumb_height <altura>	Integer	?	Altura da Miniatura.
-U, --thumb_width <largura>	Integer	?	largura da miniatura.
-M, --url <url>	String	?	URL do resultado.
-O, --video_duration <duracao>	Integer	?	Duração do video.
-I, --video_file_id <identificador>	String	?	Um identificador de arquivo válido para o arquivo de vídeo.
-K, --video_height <altura>	Integer	?	Altura do vídeo.
-B, --video_url <url>	String	?	Um URL válido para o player de vídeo incorporado ou o arquivo de vídeo.
-P, --video_width <largura>	Integer	?	Largura do vídeo.
-J, --voice_duration <duracao>	Integer	?	Duração do áudio.
-W, --voice_file_id	String	?	Um identificador de arquivo válido para a mensagem de voz.
--voice_url <url>	String	?	Um URL válido para a gravação de voz.
--phone_number <telefone>	String	?	Número do telefone.

Obs: Os campos assinados com ? são requeridos pelo tipo do objeto especificado em -t, --type. Para mais informações consulte: InlineQueryResult

ShellBot.InputMessageContent

Use essa função para criar um objeto que representa o conteúdo de uma mensagem a ser enviada como resultado de uma consulta inline. A função retorna um objeto InputMessageContent.

Uso:

ShellBot.InputMessageContent ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-t, --message_text <texto>	String	?	Texto da mensagem a enviar, 1-4096 caracteres.
-p, --parse_mode <modo>	String	?	Modo de formatação aplicada ao texto enviado (markdown ou html).
-w, --disable_web_page_preview <status>	Boolean	?	Desativar visualizações de link para links na mensagem enviada.
-l, --latitude <coordenada>	Float	?	Latitude de localização em graus.
-g, --longitude <coordenada>	Float	?	Longitude de localização em graus.
-f, --foursquare_id <quadrante>	String	?	Identificador do quadrante do local, se conhecido.
-q, --foursquare_type <tipo>	String	?	Tipo quadrangular do local. (Por exemplo: arts_entertainment/default, arts_entertainment/aquarium ou food/icecream.)
-v, --live_period <periodo>	Integer	?	O período em segundos para o qual o local pode ser atualizado deve estar entre 60 e 86400.
-e, --title <titulo>	String	?	Título do resultado.
-a, --address <local>	String	?	Endereço do local.
-m, --first_name <nome>	String	?	Primeiro nome do contato.
-s, --last_name <sobrenome>	String	?	Último nome do contato.
-d, --vcard <info>	String	?	Dados adicionais sobre o contato na forma de um vCard 0-2048 bytes
-n, --phone_number <telefone>	String	?	Número do telefone.

Obs: Os campos assinados com ? são requeridos pelo tipo do objeto. Para mais informações consulte: InputMessageContent

ShellBot.ChatPermissions

Uso:

ShellBot.ChatPermissions ...

Retorna um objeto do tipo ChatPermissions que define as ações que um usuário não administrador tem permissão para realizar em um bate-papo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-m, --can_send_messages	Boolean	Não	True, se o usuário tiver permissão para enviar mensagens de texto, contatos, locais e locais.
-d, --can_send_media_messages	Boolean	Não	True, se o usuário tiver permissão para enviar áudios, documentos, fotos, vídeos, anotações em vídeo e anotações de voz, isso implica em can_send_messages.
-l, --can_send_polls	Boolean	Não	True, se o usuário tiver permissão para enviar pesquisas, isso implica em can_send_messages.
-o, --can_send_other_messages	Boolean	Nâo	True, se o usuário tiver permissão para enviar animações, jogos, adesivos e usar bots em linha, isso significa can_send_media_messages.
-w, --can_add_web_page_previews	Boolean	Nâo	True, se o usuário tiver permissão para adicionar visualizações de páginas da Web às suas mensagens, isso significa que can_send_media_messages.
-c, --can_change_info	Boolean	Não	True, se o usuário tiver permissão para alterar o título do bate-papo, a foto e outras configurações. Ignorado em supergrupos públicos.
-i, --can_invite_users	Boolean	Não	True, se o usuário tiver permissão para convidar novos usuários para o bate-papo.
-p, --can_pin_messages	Boolean	Não	True, se o usuário tiver permissão para fixar mensagens. Ignorado em supergrupos públicos.

ShellBot.KeyboardButtonPollType

Uso:

ShellBot.KeyboardButtonPollType --type <tipo>

Retorna um objeto que representa o tipo de pesquisa que pode ser criado e enviado quando o botão correspondente é pressionado.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-t, --type <tipo>	String	Sim	Cria pesquisa com o tipo especificado. (Suportados: quiz ou regular).

ShellBot.BotCommand

Use essa função para definir um array de BotCommands.

Uso:

ShellBot.BotCommand --command <comando> --description <descricao>

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-c, --command <comando>	String	Sim	Texto do comando, 1-32 caracteres. Pode conter apenas letras minúsculas, dígitos e sublinhados em inglês.
-d, --description <descricao>	String	Sim	Descrição do comando, 3-256 caracteres.

ShellBot.setMessageRules

Use essa função para definir um conjunto de regras de ação em mensagens enviadas pelo usuário em um grupo, super-grupo ou bate-papo privado. Veja também: ShellBot.manageRules.

Uso:

ShellBot.setMessageRules --name <regra> ...

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-s, --name <nome>	String	Sim	Nome da regra. Define um nome de identificação para o conjunto de regras cujo caracteres suportados são: [a-zA-Z0-9_].
-a, --action <funcao>	String	Não	Identificador de uma função válida. Define a função de ação para as regras estabelecidas.
-z, --action_args <argumentos>	String	Não	Lista de argumentos passados na chamada da função de ação. Se o parâmetro for omitido assume como padrão argumentos posicionais.
-c, --command <comando>	String	Não	Comando do bot. O comando deve sempre começar com o símbolo / e não pode ter mais de 32 caracteres cujo suportados são: [a-zA-Z0-9_]. (Nota: Somente comandos de inicio de linha são considerados)
-i, --user_id <identificador>	Integer	Nâo	Identificador exclusivo do usuário. Suporta grupo de captura.
-u, --username <nome>	String	Não	Nome do usuário. Suporta grupo de captura.
-h, --chat_id <identificador>	Integer	Não	Identificador exclusivo do bate-papo. Suporta grupo de captura.
-v, --chat_name <nome>	String	Não	Nome exclusivo do grupo. Suporta grupo de captura.
-y, --chat_type <tipo>	String	Não	Tipo do bate-papo. (Tipos: private, group, supergroup). Suporta grupo de captura.
-l, --language_code <code>	String	Não	IETF language tag do idioma do usuário. Suporta grupo de captura.
-m, --message_id <identificador>	Integer	Não	Identificador exclusivo da mensagem. Suporta grupo de captura.
-b, --is_bot <valor>	Boolean	Não	Se o usuário é um bot. Suporta grupo de captura.
-t, --text <padrao>	String	Nâo	Um padrão ou uma sequência de caracteres contidos no corpo da mensagem. Suporta expressão regular.
-n, --entitie_type <entidade>	String	Nâo	Tipo da entidade da mensagem. (Entidades: mention, hashtag, bot_command, url, email, bold, italic, code pre, text_link, text_mention, cashtag e phone_number). Suporta grupo de captura.
-f, --file_type <tipo>	String	Não	Tipo do arquivo enviado. (Tipos: photo, document, sticker, gif, video, audio, voice, contact e location)
-p, --mime_type <nome>	String	Não	Identificador do formato do arquivo transmitido. Suporta grupo de captura.
-q, --query_data <valor>	String	Nâo	Dados associados ao botão de retorno de chamada. Suporta grupo de captura.
-r, --query_id <identificador>	Integer	Não	ID exclusivo do teclado. Suporta grupo de captura.
-g, --chat_member <status>	String	Não	Status do usuário em um grupo. (Status: left e new).
-o, --num_args <nargs>	Integer	Não	Número de argumentos contidos na mensagem, cuja sequência de caracteres é delimitada por ' ' (espaço). Suporta grupo de captura.
-e, --time <hora>	String	Não	Período entre hora inicial e final. (Formato: HH:MM-HH:MM ou HH:MM)
-d, --date <data>	String	Nâo	Período entre data inicial e final. (Formato: %d/%m/%Y-%d/%m/%Y ou %d/%m/%Y)
-w, --weekday <dia>	Integer	Nâo	Dia da semana (1..7). 1 é segunda-feira. Suporta grupo de captura
-j, --user_status <status>	String	Não	Status do usuário em um grupo ou super-grupo. (creator, administrator, member, restricted, left ou kicked). Suporta grupo de captura.
-x, --message_status <status>	String	Não	Status da mensagem: edited, pinned, forwarded, reply, callback, inline, chosen e poll
-T, --auth_file <arquivo, ...>	String	Não	Base de usuários para autenticação. O arquivo deve conter apenas um usuário por linha; comentários ou linhas comentadas são ignoradas. O arquivo é lido dinâmicamente, ou seja, o usuário pode ser adicionado em tempo de execução sem requerer a reinicialização do bot para atualização da autenticação da regra. É possivel especificar mais de um arquivo delimitado-os por vírgula (,). Suporta grupo de captura
-R, --bot_reply_message <texto>	String	Não	Envia automaticamente uma mensagem de resposta ao usuário. Suporta expansão de variáveis.
-S, --bot_send_message <texto>	String	Nâo	Envia automaticamente uma mensagem ao usuário. Suporta somente expansão de variáveis.
-F, --bot_forward_message <identificador>	Integer	Não	Encaminha a mensagem para o identificador do bate-papo especificado.
-K, --bot_reply_markup <teclado>	ReplyKeyboardMarkup	Nâo	Interface do teclado personalizada. Veja: ShellBot.ReplyKeyboardMarkup
-P, --bot_parse_mode <modo>	String	Nâo	Modo de formatação. Define a formatação do texto para --bot_reply_message e --bot_send_message'. Suporta somente formatação markdownehtml`
-B, --bot_action <acao>	String	Não	Tipo da ação a ser enviada. São elas: typing, upload_photo, record_video, upload_video, record_audio, upload_audio, upload_document, find_location, record_video_note, upload_video_note.
-E, --exec <comandos>	String	Nâo	Lista de comandos. Executa os comandos em um shell não interativo no host local e envia uma mensagem automática ao remetente contendo o retorno do comando (se presente). Se o retorno for superior a 4096 caracteres o mesmo será divido em blocos menores até que todo contéudo seja enviado. O PIPE | é suportado somente em declarações explícitas, caso contrário será interpretado como um caractere literal. Suporta expansão de variáveis e argumentos posicionais. (ATENÇÃO: Utilize esse parâmetro com prudência vinculando-o somente à regras restritas.)
-A, --author_signature <autor>	String	Não	Assinatura do autor da postagem para mensagens em canais.
-C, --continue	Nenhum	Não	Aplica a ação e continua a verificação das regras subsequentes.

Nota: São suportados múltiplos parâmetros na mesma regra. (exceto: -c, --command, -t, --text, -a, --action, --exec, --bot_reply_message, --bot_send_message, --bot_parse_mode e --bot_reply_markup)

O parâmetro -a, --action possui precedência na execução em relação ao --exec caso ambos sejam especificados na mesma regra.

Utilize somente aspas simples (') nos parâmetros --bot_reply_message, --bot_send_message e --exec para evitar a expansão prematura.

Observação:

A função oferece uma gama de variações na construção de regras nas quais são suportados padrões de lista e expressões regulares que permitem uma flexibilidade no tratamento e validação do padrão, contudo essa interface não realiza checagem de tipos/formato já que os mesmos podem estar em um conjunto finito e/ou infinito de combinações, ou seja, não estão explicitamente declarados.

Na descrição a seguir, uma lista de padrões é uma lista de um ou mais padrões separados por um '|. Padrões compostos podem ser formados usando um ou mais dos seguintes sub-padrões:

	?(lista de padrões)
		Corresponde a zero ou uma ocorrência dos padrões fornecidos.
	*(lista de padrões)
		Corresponde a zero ou mais ocorrências dos padrões fornecidos.
    +(lista de padrões)
		Corresponde a uma ou mais ocorrências dos padrões fornecidos.
	@(lista de padrões)
		Corresponde a um dos padrões fornecidos.
    !(lista de padrões)
		Corresponde a qualquer coisa, exceto um dos padrões fornecidos.

Grupo de captura

O grupo de captura é um conjunto contendo uma lista de elementos a serem verificados e que retorna verdadeiro se um elemento for encontrado. Os elementos podem ser delimitados por uma vírgula ,, PIPE | ou nova linha \n e deve respeitar a seguinte sintaxe:

Grupo

item1,item2,item3,... 

ou 

item1|item2|item3|...

ou

item1
item2
item3
...

Grupo (negado)

Essa sintaxe aplica uma verificação antagônica aos elementos da lista.

!(item1,item2,item3,...)

ou

!(item1|item2|item3|...)

Obs: não pode conter espaços entre os elementos.

Exemplo:

Liberando o comando /totalmembros somente para administradores específicos.

# Modo: --return value (ShellBot.init)
ShellBot.setMessageRules    --name 'comando_admins'	        \
                            --entitie_type bot_command	        \
			    --command '/totalmembros'	        \
			    --chat_type '!(private)'	        \	# Qualquer chat. (exceto: privado)
			    --user_status 'administrator'       \	# Somente admnistradores
			    --username 'admin3,admin6,admin8'	\	# Somente 'admin3', 'admin6' e 'admin8'
			    --exec 'ShellBot.getChatMembersCount --chat_id ${message_chat_id} | cut -d"|" -f2'

# Obs: remova os comentários antes de usar.

Expansão de variáveis

O recurso de expansão permite acessar o valor de uma determinada variável por meio do seu identificador único, exemplo: ${var}.

Exemplo:

Criando um comando chamado /meuid que retorna o id do usuário.

ShellBot.setMessageRules    --name 'retornar_id' 	                                \
			    --entitie_type bot_command	                                \
		            --num_args 1		                                \
			    --command '/meuid'                                          \
			    --bot_send_message '*O seu id é:* ${message_from_id}' 	\
			    --bot_parse_mode markdown

Argumentos posicionais

O argumento posicional é análogo ao recurso de expansão, porém permite acessar elementos específicos da mensagem enviada pelo usuário informando o ${N} elemento, onde N é um inteiro que representa sua posição e que é delimitada por um espaço ( ). Utilize os metacaracteres @ ou * para capturar todos os argumentos, para mais detalhes: $ man bash.

É possível construir uma linha de comando dinâmica com os argumentos fornecidos na mensagem.

Exemplo 1:

Criando uma regra que simula a função do comando egrep.

Sintaxe: /egrep padrao arquivo

ShellBot.setMessageRules	--name 'cmd_egrep' 			\
				--entitie_type bot_command	        \
				--chat_type	private			\
				--username 'admin'			\
				--command '/egrep'			\
				--num_args 3				\
				--exec 'grep -E "$2" $3'

Observação: Para evitar que o retorno seja enviado ao usuário basta suprimir a saída do mesmo inserindo &>/dev/null ao final do comando, exemplo: comandos .... &>/dev/null

Exemplo 2:

Implementando um shell linux que executa qualquer comando enviado pelo usuário. (Nota: Esse exemplo é somente para fins ditáticos, dada as circustâncias e riscos aplique somente em regras restritivas.)

Sintaxe: /shell commandos...

# Aceita a requisição no privado e executa o comando somente
# para o usuário especificado.
#
# Obs: Substitua os campos <...> pelas informações do seu usuário (Telegram).
ShellBot.setMessageRules	--name 'shell_linux'		\
				--entitie_type bot_command	\
				--command '/shell'		\
				--chat_type private		\
				--user_id <ROOT_ID>		\
				--username '<ROOT_NAME>'	\
				--exec '${@:2}'			# Executa os argumentos. (exceto: '/shell')

ATENÇÃO: Caso seja necessário acessar os elementos da mensagem é altamente recomendado o uso do argumento posicional, pois o valor é acessado por referência e não por substituíção como ocorre na expansão da variável, ou seja, se o valor de ${message_text} conter a sintaxe de um comando válido o mesmo é executado prematuramente. Se deseja acessar todos os elementos da mensagem, utilize $@ou $* ao invés ${message_text}.

Verificação

As regras são verificadas sequêncialmente na ordem em que foram definidas e, se a mensagem enviada satisfazer os critérios estabelecidos a ação é aplicada (se presente) e salta para a próxima requisição (exceto se --continue for especiifcado). Se um determinado parâmetro for especificado mais de uma vez a regra é aplicada se pelo menos um dos argumentos for válido.

Ignorando/Negando requisições.

Além da permissiva é possível definir uma regra que funcione como uma negativa de critérios, omitindo o parâmetro -a, --action ou --exec. Uma regra sem ação vinculada é útil quando precisamos simplesmente ignorar uma requisição ao invés de tratá-la. Para esse tipo de implementação é recomendado que precedam as regras de ação, ou seja, não se pode proibir o que já foi permitido. :D

Exemplo:

Ignorando a requisição do comando /botcmd para um determinado grupo de usuários, seja ele enviado em um super-grupo ou privado. Veja exemplo: ManageRules.sh

# Negar
ShellBot.setMessageRules	--name 'negar_commando_usuarios' 		\
				--command '/botcmd' 								\
				--chat_type 'supergroup,private'					\
				--username 'usuario1,usuario2,usuario3,usuario4'

# Permitir (executa a ação em: "funcao_cmd")
ShellBot.setMessageRules	--name 'executar_comando'	\
				--command '/botcmd'		\
				--action 'funcao_cmd'

ShellBot.manageRules

Use essa função para gerenciar/executar as regras definidas para mensagens de usuários. Executa a função/comandos (se presente) somente se a mensagem satisfazer o conjunto de regras a qual está vinculada. Retorna true se uma regra for aplicada, caso contrário false. Veja também: ShellBot.setMessageRules.

Uso:

ShellBot.manageRules --update_id <id>

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
-u, --update_id <id>	Integer	Sim	ID da atualização a ser gerenciada. Veja também: ShellBot.ListUpdates

Se o modo monitor estiver ativado é retornado as informações referentes a regra aplicada no seguinte formato:

[ShellBot.manageRules]: <num_msg>: <data>: <tipo>: <grupo>: <usuario>: <arquivo>: <linha>: <regra>: <acao>: <comandos>