SomosChat Script - paulocorcino/SomosChat GitHub Wiki

Documentação SomosChat Script

[texto]

Variáveis

[texto explicativo]

%variavel% - Variável tipo sessao campo Texto ou Número
$variavel$ - Variável do sistema Texto ou Número
@@msg[n] - Retorna com mensagem template
@@arq[n] - Arquivo Galeria
@@img[n] - Arquivo Galeria
@@aud[n] - Arquivo Galeria
@@gim[n] - Agrupamento de Arquivos da Galeria
@@gaq[n] - Agrupamento de Arquivos da Galeria
@@vcd[uid] - Obtem o cartão do usuário

Quando é iniciado uma sessão o sistema cria 2 tipos de memórias:

  1. A memória permanente que armazena todas respostas do usuário;
  2. A memoria da cena, que armazena em tempo de execução da cena atual, na cena subsequente ela é recriada.

Variáveis do Sistema

$session_id$ - Id da sessao 1337,
$service_id$ - Id do Serviço 1,
$user_id$ - User ID 3,
$service_tipo$ - tipo do serviço "W1",
$bot_name$ - Nome do Bot "Perbras Bot",
$bot_username$ - Nome do Bot "Perbras Bot",
$session_seq$ - Sequencia 3,
$story_ref$  - Story em execução "MNU"
$seq_cena$ - Cena atual 1,
$nome_cena$ - Nome da Cena atual Teste,
$nome_roteiro$ - Nome do roteiro atual Teste,
$count_repeat$ - Número de repetições na mesma cena,
$user_from$ - Username do aplicativo "[email protected]",
$user_name$ - Nome original do comunicador "Paulo Corcino",
$user_username$ - Usuário do aplicativo de comunicação "[email protected]"
$user_ban$ - Se o usuario foi banido
$count_repeat$ - Numero de repetições da cena
$input$ - Valor de entrada
$data$ - Data de hoje em formato ISO 18/07/2020
$datahora$ - Data de hoje em formato ISO 18/07/2020 12:00
$dataiso$ - Data de hoje em formato ISO 20200718
$horaiso$ - Hora e minuto no formato 0712
$hora$ - Hora no formato 07
$diasemana$ - Dia da semana em formato númerico - 1 domingo a 7 sabado
$periododia$ - Infoma a saudação do dia em formato númerico - 1 manhã, 2 tarde e 3 noite
$user_data$ - Data de hoje em formato ISO 18/07/2020
$user_datahora$ - Data de hoje em formato ISO 18/07/2020 12':00
$user_dataiso$ - Data da ultima mensagem usuário em formato ISO 20200718
$user_horaiso$ - Hora e minuto do usuário no formato 0712
$user_hora$ - Hora do usuário no formato 07
$user_diasemana$ - Dia da semana do usuário em formato númerico - 1 domingo a 7 sabado
$user_periododia$ - Infoma a saudação do dia em formato númerico - 1 manhã, 2 tarde e 3 noite

Variáveis de memória - Padrão

%user_id% - User ID 3,
%user_username% - Usuário do aplicativo de comunicação "[email protected]",
%user_name% - Nome original do comunicador "Paulo Corcino"
%user_sessionid% - Id da sessao
%user_ban% - Se o Usuario foi Banido
%user_phone% - Telefone do usuario (whatsapp)

Variáveis de memória - Tipo objeto

%binario% - Variaveis do tipo binário terão como conteúdo [objeto];[arquivo binário]

Caso utilize uma variável binário em uma saída, o objeto será enviado na mensagem.

%data% - Variaveis do tipo data terão o formato ISO [ano]-[mes]-[dia]T[hora]:[minuto]:[segundo]

Variáveis - Extrair valor de atributos de textos em formato JSON

%variavel@atributo% - Permite obter valor de uma chave json armazenado em uma variavel, pode-se tambem gravar informação em estrutura json em memoria

Exemplo

Considerando uma variável chamada %filme% onde foi atribuído o JSON no exemplo abaixo.

{
     "titulo": "JSON James",
     "resumo": "a história de uma lenda do velho oeste",
     "ano": 2012,
     "info": { "tempo": 120, "estilo": "ação" }
}

Para obter o valor de "ano" utilize a seguinte sintaxe.

%filme@ano% 

# para obter uma subchave

%filme@info:tempo%

Variáveis Texto - Formatação

:unescape - Remove caracteres especiais
:1 .. :[n] - retorna o primeira palavra, [n] posição

Variáveis - Extrair dados de datas

%data:data% - Obtem em formato iso inteiro 
%data:datahora% - Obtem em formato iso inteiro 
%data:dataiso% - Obtem em formato iso inteiro 
%data:dia% - Obtem o dia
%data:mes% - Obtem o mes
%data:ano% - Obtem o ano
%data:horaiso% - Obtem hora e minuto em inteiro
%data:hora% - Obtem hora
%data:diasemana% - Obtem dia da semana
%data:periododia% - Infoma a saudação do dia em formato númerico - 1 manhã, 2 tarde e 3 noite

[Exemplo]

Variáveis de atendimento

[texto]

%atend_id% - Id do atendimento
%atend_sit% - Situação do Atendimento
%atend_grpnome% - Nome do Grupo de Atendentes
%atend_posicao% - Número de pessoas na fila
%atend_nome% - Nome da Atendente, apenas quando inicia o atendimento
%atend_username% - usuario atendente

[exemplo]

Operando Variáveis

Armazena valor na memória da sessão

::mem("nome variavel","Valor")

Armazena valor na memória da cena

::var("nome variavel","Valor")

Limpa a memória da sessão

::clm()

Funções

Operação Matemática

::mth([formula],[variavel memoria - opcional])

Resultado da operação é armazenado na variável $mthretorno$ Em caso de erro no cálculo a variável $mthretorno$ tem o valor erro

Se utilizar uma variável na fórmula e a mesma não possuir valor, assume o valor padrão 0

Mensagens

Envia mensagem de texto ao receptor.

::msg("Texto")

Exemplo com variáveis.

::msg("%var1% $varsis$ $input$")

Exemplo com mensagem do repositório.

::msg(@@msg12)

Envio de arquivos.

::msg("[mensagem]",[variavel memoria - binário])

Envio de localização.

::msg("[mensagem]",[lat],[lon])

Saída

Permite encerrar o processamento da cena imediatamente redirecionando para outra cena.

::out("Mensagem (Opcional)",{acoes})

Ações

{end} - Finaliza a sessão
{false} - Repete a entrada
{true} - Segue proxima sequencia
{#[cena]} - Salta para cena
{[storyboard]#[cena]} - Salta para Storyboard / Cena
{@[canal]} - Salta para atendimento

Decisão (SE)

::se([variavel / valor ][operador][variavel / valor]?[se verdadeiro];[se falso])

Operadores Lógicos

= - Igualdade

> ou >=`` - maior ou maior igual

< ou <= - menor ou menor igual

<> - diferente

ou - ou

e - e

Ignorar valores em validação

[TEXTO]

::ign("[valor1]";"[valor 2]";...)

Esquerda

Mostra sequencia de caracteres

:esq([variavel],[texto / variavel],[quantidade caracteres])

  • [variavel] - Informe uma variável que armazenará o resultado
  • [texto / variavel ] - Texto ou variável
  • [quantidade caracteres] - Quantidade de caracteres a capturar.

Controle de Acesso

Registrar

Registrar o usuário na plataforma e armazena as variáveis de memória para utilização nos próximos logins.

::reg([chave1],[chave2 (opcional)],[informe 1 para unico])

  1. Em caso erro a variável $reg_erro$ retorna 1
  2. Após registrar considerar a variável %login_[chave1]% = 1

Logar

::lgn([chave1],[chave2 (opicional)])

Caso seja sucesso a variável %login_[chave1]% assume as situações.

  • -1 - Tem login, mas pendente chave2
  • 0 - Não Logado
  • 1 - Logado

Quando possui chave 2 a variável %chave2_[chave1]% assume o valor correspondente.

Efetuar logoff

::lgf([chave1],[chave2 (opicional)])

Remover o registro do usuário

::urg([chave1],[chave2 (opicional)])

Atualizar dados do usuário

::set("[INFO]","[VALOR]") ::get("[INFO]","[VARIAVEL]")

Info

NOME
EMAIL
ENDERECO
BAIRRO
CIDADE
UF
CEP
CPF

Retorno

$set_retorno$ = 1 - Sucesso
$set_retorno$ = 1 - Sucesso

Formulários

Permite que o sistema crie um formulário preenchido com as respostas do bot, o retorno é armazenado nas variáveis de sistema $formguid$ $formurl$

::frm([cod forms])

Tabelas

Registrar

Permitem armazenar o resultado das pesquisas para consultas futuras, retorna $tabretorno$ igual a 1 se ok.

::tab([cod tab],[mem ou var identificador],[mem ou var URL Externo (opcional)])

URL Externo - Permite referenciar algum link externo para exibição de informação na tabela

Resgatar Dados

Permite obter os dados armazenados em uma tabela.

::gtb([cod tab],[mem ou var identificador],[variavel])

Caso exista dados $tabretorno$ assumirá o valor 1.

%[variavel]% informada armazenará um JSON contendo os dados. Veja como utilizar variáveis JSON [aqui]

Sessão

Retorna na variável $limitesessao$ se igual 1 está no limite ou 0 acima do limite determinado.

::lmt()

API

::api("Metodo","url",[debug (opcional)])

Retorno

%api_retorno% - Retorna o conteúdo da API $api_status$ - Se 1 processou normalmente, se 0 houve erro no carregamento

Utilize a variável $count_repeat$ para controle de tentativas caso o retorno da API seja false.

Retorno da API deve ser em formato JSON com a seguinte estrutura.

{
"bot_msg":"[mensagem - opcional]",
"bot_action": "[acao]", -- vide no topico as opção de ação, vazio é considerado sem ação
"bot_data": "[json]" , -- json com variaveis a serem armazenadas na sessao 
"bot_binary": "[variavel];[nome do arquivo com extensão];[base64]", - binário a ser transmitido (opcional)
"bot_location":"[lat],[lon]" - Envio de localização (Opcional)
}

Caso o retorno não esteja no padrão todo o conteúdo retornado é armazenado em %api_retorno%.

Headers - Authorization

É possível encaminhar na requisição uma header de autorização, utilize a linha abaixo como exemplo antes de solicitar a requisição.

## API Autorization
::api("authorization", "Basic YXZha2phbkBtYWlsLnJ1OnRlc3Rl")

## API Post
::api("POST","https://webhook.site/4b4a9c22-5532-40f4-98dc-3439f602a268")

PDF

Permite armazenar em memória um arquivo em formato PDF

::pdf("[mem]","[nome]",[conteudo html ou url],[charset (opcional)],[orientacao (opcional)],[papel (opcional)])

  • chartset - ISO-8856, UTF-8 etc
  • orientação - P (Paisagem) ou R (Retrato) - padrão R
  • papel - A4, A3 ou Letter - padrão Letter

Direita

Permite obter o contúdo do texto a direita.

::dir("[mem]","[texto]",[quantidade])

Exemplo

::dir("teste","Paulo Corcino",7)
::msg("%teste%")

Tamanho do texto

Obtem a quantidade de caracteres de um texto.

::len("[mem]","[texto]")

Exemplo

::len("teste","Paulo Corcino")
::msg("%teste%")

Subsequência

Permite obter parte de um texto, informe a posição incial e a quantidade de caracteres a ser obtido.

::sbt("[mem]","[texto]", [posição inicial], [quantidade de caracteres])

Exemplo

::sbt("teste","Paulo Corcino",7,3)
::msg("%teste%")

Substituir

Permite substituir um caracter ou texto encontrado por outro texto ou caracter.

::rpl("[mem]","[texto]", "[texto ou caracter a ser susbtituido]", "[texto ou caracter a assumir]")

Exemplo

::rpl("teste","Paulo Corcino","Paulo","João")
::msg("%teste%")

Obter Binário

Obtem referência de um binário a partir de uma URL. Podemos usar esta função como no exemplo para que o Somos Chat encaminhe uma imagem ou documento a partir de uma url para o contato.

::gbn("[mem]","[url]")

Exemplo

::gbn("teste","https://cdn-icons-png.flaticon.com/512/124/124034.png")

# exibe imagem
::msg("",%teste%")

Webhook

Permite encaminhar para um endpoint um JSON contendo as informações da memória do bot.

Crie uma referência para um Webhook em Módulos > Webhook. Insira uma referência (ref) e especifique uma URL. Para testes, recomendamos a utilização do serviço Webhook.site. Utilize o botão "play" para testar o envio de mensagem ao webhook.

::whk("[ref]")

Conteudo do web

BAN

Bane usuário por um tempo determinado.

::ban([limite tentativas],[tempo em minutos banimento],{acoes},[variavel ref (opcional)])

  • limite tentativas - Número de tentativas antes de banir
  • tempo - Tempo para o banimento
  • {acoes} - direção
  • variavel - Variável referência para limite de tentativas, por padrão é utilizado $count_repeat$

Opção

::opc("[mem]",[cod lista],[num opc],[ir para],[ordem],[tp opcao],"[format]",[separador],"[opcao adicional]",[ir para adicional])

Esta função possibilita a criação de um menu de opções dinâmico.

Obrigatórios

  • [mem] - nome da memória onde será armazenado o resultado
  • [cod grupo lista] - Código de um grupo de lista
  • [ir para] - Informe {#n} - n cena ou demais tipos de ações de saída

Opcionais

  • [ordem] - 0 - cresc., 1 - decrecen. e 2 - aleatório
  • [tp opcao] - Tipo do valor campo opção, 0 numérico (1 - n) ou 1 - Nome
  • [formato] - Formatação das opções utilize a identificação op para opção e txt para texto, exemplo. ":op - :txt" O sistema irá formatar com negrito entre as opções e um traço com o texto.
  • [separador] - Define 0 - quebrar linha, 1 - espaço ou 2 - virgula
  • [opcao adicional] - Escreve alguma opção adicional
  • [ir para adicional] - Informe {#n} - n cena ou demais tipos de ações de saída

Download de binários - Imagens, Vídeos, Documentos e Áudios.

Os binários na plataforma Somos Chat possuem um ID único de identificação. Abaixo segue um exemplo.

3e8400173f662f24caaa_jpeg@1@18858@387A6051D8244AE39B6D

É possível baixar este arquivo através da URL.

https://[url platafoma Somos Chat]/[seu app]/getfile.rule?sys=BOT&arquivo=[ID arquivo]

Segue um exemplo:

https://app.somos.chat/somos/getfile.rule?sys=BOT&arquivo=3e8400173f662f24caaa_jpeg@1@18858@387A6051D8244AE39B6D

Documentação de API da plataforma

Todo conteúdo para consumir API da Somos Chat está na URL abaixo.

Postman Public