Variáveis

Como usar variáveis

Vamos explorar o que são variáveis e como usá-las de forma eficaz ao criar chatbots no MaviBot.

triangle-exclamation

Uma variável é um local de armazenamento nomeado para dados, identificado por um rótulo de texto exclusivo.

Fig. 1: Uma variável chamada total, armazenando um valor de pagamento.

O MaviBot fornece vários tipos de variáveis:

  1. Variáveis definidas pelo usuário — são aquelas que você cria por conta própria dentro do projeto.

Declarar uma variável significa atribuir um valor a um contêiner nomeado. Em outras palavras, uma instrução como a=0 é a declaração da variável a. Acabamos de informar (declarar ao) construtor que vamos armazenar um número na variável a, e por enquanto, esse valor é 0.

Atribuir um valor a uma variável tem o mesmo significado.

As expressões "atribuir a uma variável o valor de uma função" ou "definir uma variável igual a uma função" também são comumente usadas. O princípio é o mesmo: em vez de atribuir um valor específico, você atribui o resultado de uma função. Por exemplo: s_id = tg_send_message(platform_id, "Olá!") Nesse caso, o resultado da função será armazenado na variável.

Redefinir uma variável significa atribuir a ela o valor 0.

Funções e métodos são conjuntos predefinidos de comandos configurados antecipadamente pelo MaviBot. A maioria das funções requer parâmetros - valores que a função ou método consegue entender. Assim que o bot recebe os parâmetros necessários, ele executa um comando específico.

tg_send_message(platform_id, "Olá!") essa função envia a mensagem "Olá!" no Telegram.

Fig. 2. Exemplo de uma variável chamada text1 atribuída a uma função.

REGRAS PARA TRABALHAR COM VARIÁVEIS:

  1. O nome de uma variável só pode começar com uma letra; ele não pode começar com um número.

    Age1 - ✅ correto

    1Age - ❌ incorreto

    age1 - ✅ correto - opção recomendada

  2. Uma variável não pode conter espaços nem caracteres especiais, exceto o sublinhado (_).

    Name_Surname - ✅ correto

    Name Surname - ❌ incorreto

    nameSurname - ✅ correto - opção recomendada

    Palavras reservadas de linguagens de programação não podem ser usadas como nomes de variáveis, por exemplo: print, true, false, count, sum e assim por diante.

  3. É terminantemente proibido usar usar os nomes das variáveis internas e do sistema para variáveis definidas pelo usuário. Você pode encontrar a lista dessas variáveis aqui. ссылка

  4. Recomendamos:

    • Use nomes em latim (inglês) para variáveis.

    • Use nomes de variáveis curtos, mas significativos, por exemplo: totalSum, pay_name, ns, name_client etc.

Como obter o valor de uma variável

Coloque o nome da variável entre chaves #{}. Você pode referenciar o valor dela no campo de texto da mensagem dessa forma. No entanto, no campo "Calculadora", você deve se referir ao valor da variável simplesmente pelo nome, sem qualquer sintaxe adicional.

triangle-exclamation

Exemplo:

circle-check

No campo "Calculadora", faça referência às variáveis pelos nomes, sem usar a notação #{}. Por exemplo, se tivermos duas variáveis: price (sum) e quantity (num).

num = 10

sum = 1500

Como exibir a soma total

Digite o seguinte na calculadora:

total_sum = sum1 * num2 ✅ correto

Como não fazer isso:

total_sum = #{sum1} * #{num2} - ❌ incorreto

Como excluir uma variável do bot

Para excluir (limpar) uma variável, digite uma das opções a seguir no campo "Calculadora": YourVariableName = ou YourVariableName = ""

Após o sinal de igual, deixe um espaço ou use aspas duplas (ou simples).

circle-exclamation

Variáveis internas

Aqui está a lista de variáveis internas:

#{none} - ignorar a mensagem

#{api_key} - token da API usado nas chamadas da API do Salebot

#{attachment_url} - contém o link do anexo

#{attachments} - um array JSON de URLs de anexos da mensagem do usuário

#{avatar} - link para o avatar do usuário (mostrado na seção "Clientes")

#{client_id} - ID do cliente no construtor, também usado em solicitações da API

#{client_type} - o tipo de mensageiro de onde o cliente veio (valores descritos [aqui])

#{current_date} - data atual no formato dd.mm.aaaa, com base no fuso horário do projeto

#{current_time} - hora atual no formato hh:mm, com base no fuso horário do projeto

#{custom_answer} - a resposta recebida do servidor especificado no campo "URL da resposta do servidor"

#{message_from_outside} - tipo de mensagem recebida. Valores possíveis: mensagem comum = 0 mensagem enviada via API = 1 notificação de callback (fundo amarelo no diálogo) = 3 notificação de telefonia (fundo azul-claro no diálogo) = 5 Essa variável é gerada a cada mensagem recebida, mas não aparece no cartão do cliente. Você pode usá-la no campo "Variável para comparação" para configurar condições para gatilhos e conexões de blocos.

#{date_of_creation} - data em que o usuário foi adicionado ao bot ou enviou mensagem a ele pela primeira vez

#{full_name} - nome completo do usuário (nome e sobrenome)

#{group} - bot ao qual o cliente está vinculado (mostrado como "Vinculado ao bot" no cartão do cliente)

#{main_client_id} - ID do cliente principal entre um grupo de cartões de cliente vinculados

#{message_id} - ID do estado atual da conversa com o cliente (padrão: NONE)

#{messenger} - nome do mensageiro de onde o cliente veio

#{name} - nome do usuário

#{next_day} - data de amanhã no formato dd.mm.aaaa (útil para agendar mensagens)

#{order_id} - identificador do pedido (ID do cliente e ID interno do pedido separados por um hífen)

#{order} - conteúdo do pedido enviado pelo usuário

#{platform_id} - ID do cliente na plataforma de mensagens

#{question} - mensagem enviada pelo usuário

#{timestamp} - timestamp atual incluindo milissegundos

#{time_of_creation} - hora em que o usuário foi adicionado ao bot ou enviou mensagem a ele pela primeira vez

#{wa_bot} - número de WhatsApp para o qual o usuário enviou mensagem (útil para passar para campos de CRM e distribuir leads entre gerentes)

#{weekday} - dia da semana como um número (segunda-feira = 1, terça-feira = 2 etc.)

valores de client_type

Valor
Mensageiro

1

para Telegram

2

para Viber

3

para Facebook

5

para chat online

10

para Instagram

14

e-mail

16

Conta Empresarial do Telegram

21

conta do Telegram

22

TikTok

Variáveis do sistema

O sistema gera automaticamente várias variáveis de tempo de execução durante a operação de um bot Você pode usar essas variáveis ao construir seu bot. Aqui está uma lista daquelas que podem ser úteis para você.

circle-info

Você pode encontrar variáveis adicionais do sistema na documentação. Elas estão localizadas nas seções relevantes para seu uso.

phone - número de telefone

notSubscribed - se a variável for igual a 1, o cliente cancelou a inscrição nas mensagens e não receberá nenhuma mensagem

clientBlocked - o cliente está bloqueado, e o bot não opera para ele

story_url - identificador do story do Instagram ao qual o cliente respondeu

viewed_page - página de onde o usuário está escrevendo no chat online

wa_bot - número de telefone do bot do WhatsApp

circle-info

Para saber quais variáveis podem ser criadas durante o pagamento, consulte os guias de integração dos serviços de pagamento na seção "Sistema de pagamento".

Variáveis personalizadas

As variáveis personalizadas são divididas em:

Cada tipo de variável será explicado abaixo.

circle-info

Evite usar os mesmos nomes para diferentes tipos de variáveis para prevenir confusão quando o Builder exibir ou usar um valor diferente do que você esperava.

circle-info

Ao atribuir um valor a uma variável, é importante especificar seu tipo usando o prefixo apropriado:

client. (para variáveis do cliente) e project. (para variáveis do projeto). Nenhum prefixo é usado para variáveis de negócio.

O prefixo é omitido ao recuperar o valor de uma variável.

Exemplo: Vamos imaginar que você queira criar uma variável de projeto chamada like para servir como contador de curtidas dos seus clientes.

project.like = 0 - declaração, feita uma vez

No bloco em que você precisa contar curtidas, escreva: project.like = like + 1

circle-info

Ordem de prioridade das variáveis: variáveis de negócio têm a maior prioridade, seguidas pelas variáveis do cliente e, depois, pelas variáveis do projeto.

ID do mensageiro (platform_id)

ID do mensageiro (platform_id) é o identificador do usuário/chat/canal dentro do mensageiro. Para encontrá-lo, abra a conversa com o cliente desejado na seção "Clientes". No lado direito da janela do chat, navegue até a aba "Sobre o cliente - Variáveis do sistema" ou a aba "Todos" .

O platform_id é uma variável permanente, gerada pelo sistema, que representa o ID exclusivo do mensageiro do usuário.

  • Persistência: Este ID permanece constante para um usuário. Mesmo que você exclua o registro dele do builder, seu platform_id será o mesmo após o re-registro.

  • Origem: O ID é atribuído pela plataforma de mensagens (por exemplo, Telegram, WhatsApp) quando o usuário interage com o bot pela primeira vez.

O exemplo a seguir mostra como o platform_id aparece em um cartão de cliente.

A variável platform_id existe tanto para usuários comuns quanto para comunidades, canais e chats.

Para obter o platform_id (ID do mensageiro) de um canal do Telegram no qual o bot é administrador, basta enviar uma mensagem para o canal a partir da sua conta pessoal. Isso criará automaticamente um diálogo entre o bot e o canal.

Você pode copiar o platform_id valor do canal na seção "Sobre o cliente".

No Telegram, o ID do mensageiro para canais sempre começa com um sinal de menos (-). Ao usar funções, certifique-se de incluir o valor completo, incluindo o sinal de menos.

Como usar variáveis

As variáveis podem ser usadas em gatilhos, pedidos, respostas do usuário, blocos e muito mais. Vamos ver um exemplo concreto ao criar um funil para uma imobiliária.

Então, vamos criar um bloco de Início:

Etapa 1: Crie o bloco "Obrigado"

Crie um novo bloco com uma mensagem agradecendo ao usuário pela contribuição.

Etapa 2: Configure a transição

Na conexão que leva a este bloco, configure o seguinte gatilho:

  1. Ative a alternância "Usuário insere dados" .

  2. Na "Campo de entrada de dados" , digite o nome da variável: name.

A entrada do usuário é armazenada na variável Name . Esse valor pode ser reutilizado em qualquer bloco subsequente chamando a variável com a sintaxe #{Name} , como em: Bem-vindo, #{Name}!.

O bot funcionará da seguinte forma:

Agora vamos tornar a tarefa um pouco mais complexa.

Neste mesmo bloco, perguntaremos ao usuário se ele tem interesse em imóveis primários (novos) ou secundários (revenda):

Em seguida, crie conexões a partir dos botões "Imóveis primários" e "Imóveis secundários" no bloco "Chat".

Agora vamos ver a segunda forma de usar variáveis dentro dos blocos.

Selecione o bloco certo e digite o seguinte texto no campo "Calculadora": client_interest = Imóveis primários. No bloco da esquerda, digite: client_interest = Imóveis secundários.

circle-info

Uma variável é atribuída ao usuário quando ele faz a transição para qualquer um desses blocos. Podemos usá-la depois ao criar um pedido.

Em seguida, perguntaremos ao cliente sobre o orçamento para compra de imóveis nestes blocos e criaremos mais dois blocos com setas levando até eles com base nos gatilhos de resposta do cliente.

A partir do bloco "Qual é o seu orçamento?", crie uma conexão e defina uma condição de gatilho para segmentar os usuários com base em suas respostas.

  1. Nas configurações da conexão, marque a caixa para "Usuário insere dados".

  2. Atribua um nome de variável (por exemplo, budget) para armazenar a resposta do cliente.

  3. Na "Variável" campo, use a variável interna #{question} (que contém a última mensagem do usuário) para criar uma condição.

    • Exemplo: #{question} <= 1000000

circle-exclamation

Você também pode definir uma variável adicional diretamente no bloco blocos "Leads" para fornecer informações mais completas sobre o negócio.

Agora altere o tipo dos dois últimos blocos para "Leads" e veja os resultados:

Vamos testar o fluxo em ação:

Você pode revisar o negócio criado e os dados armazenados do cliente acessando a seção "Clientes" e abrindo a conversa relevante. As variáveis do negócio estarão visíveis lá.

Agora você sabe como usar variáveis de pelo menos três maneiras diferentes:

  1. Atribuir nomes de variáveis aos dados inseridos pelo usuário (por exemplo, “Name”, “Budget”)

  2. Atribuir um valor de variável ao fazer a transição para um bloco (por exemplo, client_interest = Imóveis primários)

Como visualizar variáveis

Para visualizar as variáveis de um cliente, navegue até a seção "Clientes" e abra o cartão do cliente.

As variáveis são exibidas em formato de lista dentro do cartão do cliente:

  • Cada variável ocupa sua própria linha.

  • O o nome da variável é mostrado à esquerda.

  • Seu correspondente value é exibido à direita.

Para modificar uma variável:

Passe o mouse sobre a linha dela na lista para revelar um botão de ação. Clicar nesse botão permite que você:

  • Edite o nome da variável.

  • Edite o valor da variável.

  • Exclua a variável completamente.

circle-info

Variáveis do sistema não podem ser editadas!

Como definir variáveis do cliente

circle-info

As variáveis do cliente não são excluídas, redefinidas nem perdidas ao usar o bloco "Fim da coleta de dados" (bloco vermelho).

Uma variável do cliente pode ser definida de duas maneiras: explicitamente e implicitamente. Uma maneira explícita de definir uma variável é configurá-la no campo "Calculadora" de um dos blocos do funil.

Exemplo: client.age = 28 ou client.age = 28:

A maneira implícita é definir uma variável no campo de entrada de dados da seta.

Exemplo:

Vamos criar um bloco em que perguntamos o nome do cliente e também criar um bloco abaixo:

Em seguida, navegue até as configurações da conexão e ative a opção "Usuário insere dados".

Use a função client. prefixo ao nomear sua variável (por exemplo, client.name) para armazenar a entrada do usuário. Essa variável pode então ser referenciada em mensagens posteriores como #{client.name}.

circle-check

Como definir variáveis do projeto

circle-info

Variáveis globais não são excluídas, redefinidas nem perdidas ao usar o bloco "Leads" (bloco vermelho).

Variáveis globais estão acessíveis a todos os usuários do bot. Elas são ideais para controlar o comportamento do bot ou facilitar interações entre diferentes usuários.

Exemplo de caso de uso: Um usuário pode publicar um item em um canal de marketplace definindo uma variável (por exemplo, project.latest_listing), e todos os outros usuários podem vê-lo e responder.

Sintaxe para atribuição

Para criar ou atualizar uma variável global, use o project. prefixo na Calculadora:

Exemplos:

  • project.product_shop = 28

  • project.age = 28

Elas podem ser usadas sem nenhum prefixo.

Vamos ver como os dados são exibidos na tabela.

Agora, execute o bloco "Início" no modo de teste.

Podemos ver os dados que foram gravados na variável a partir da tabela na mensagem enviada pelo bot. Como referenciamos a variável na mensagem usando a sintaxe #{} , os dados armazenados nela foram exibidos no chat do bot.

circle-info

Mais detalhes sobre como trabalhar com a função get_records_from_table() são explicados no artigo "Assistente de IA com tabela do MaviBot".

O project. prefixo permitiu que a função gravasse os dados da tabela diretamente nas variáveis globais do projeto, acessíveis na seção "Variáveis" seção.

Você pode editar variáveis do projeto nas configurações do projeto.

Exemplo: usando variáveis do projeto

Crie um sistema que atribua um número sequencial a cada novo cliente que entrar no bot.

Implementação:

  1. Navegue até suas Configurações do projeto.

  2. Crie uma nova variável de projeto (por exemplo, project.client_counter).

  1. Defina seu valor inicial (por exemplo, 0) o que significa "Nenhum cliente no bot":

No bloco inicial do bot, adicione uma lógica que:

  1. Incrementa o valor da variável do projeto em 1.

  2. Atribui o novo valor a uma variável específica do cliente para o usuário atual.

circle-info

Não se esqueça de definir uma restrição para que o contador não possa ser incrementado duas vezes para o mesmo cliente.

Como definir variáveis constantes

Constantes são valores fixos que permanecem inalterados (ou mudam raramente) ao longo do ciclo de vida de um projeto.

Diferença principal em relação às variáveis globais:

Diferentemente das variáveis globais, as constantes são específicas do cliente. Se o valor de uma constante for modificado, a alteração se aplica apenas à sessão daquele cliente específico.

Casos de uso comuns:

As constantes são ideais para armazenar dados estáticos, como:

  • Preços de produtos e descontos para clientes

  • Tokens de integração e chaves de API

  • Informações de contato do vendedor ou do suporte

  • Quaisquer outros valores de configuração fixos

Exemplo: usando variáveis constantes

Por exemplo, o desconto de um cliente poderia ser 10% por padrão, mas mudar para 25% ao inserir um código promocional.

Em "Configurações do projeto" → "Constantes", digite: Discount : 10

Para inserir um código promocional, adicione um bloco "Gatilho", onde atribuímos à variável discount o valor de 25.

Exiba a variável que mostra o valor do desconto no bloco verde:

Etapa 1: Configure a transição automática Crie uma conexão com um temporizador de zero segundos a partir do bloco cinza. Isso garante que o desconto seja aplicado imediatamente e que o cliente prossiga para a mensagem no bloco inicial.

Etapa 2: Teste o fluxo Agora, envie uma mensagem para o bot para acionar e testar toda a sequência.

O desconto padrão é de 10% sem um código promocional. No entanto, inserir um código promocional válido muda a situação.

Assim, após inserir o código promocional, a variável "discount" para esse cliente passou a ser 25.

Isso aconteceu porque uma atribuição como discount = 25 definiu o valor para a variável de negócio, em vez de alterar o valor da constante com o mesmo nome.

Principais variáveis de negócio

name - nome do negócio. O termo Name é usado para a versão internacional do projeto.

description - descrição do negócio. Descrição é usado na versão internacional do projeto

budget - valor do negócio (número).

Para editar variáveis usando a requisição da API /set_order_vars, você deve usar os nomes deste guiaexatamente como mostrados , incluindo a diferença entre maiúsculas e minúsculas e a versão do projeto.Limites

Comprimento máximo do nome da variável: 500 caracteres

circle-exclamation

Quando você deve colocar o valor de uma variável entre aspas?

Por exemplo,

client_id = 1202020202 client_id = '1202020202' ou Ambas as opções de sintaxe estão funcionalmente corretas. Usar aspas ao redor de um valor afeta apenas o destaque visual no editor da calculadora.?

No entanto, seguir convenções de codificação consistentes melhora a legibilidade e a manutenção:

Omitir aspas

  • para valores numéricos (por exemplo, discount = 25).

  • Use aspas valores de string (por exemplo, status = "active").

Qual é a sintaxe correta para passar identificadores como ID do Cliente, ID do Site, ID do Bloco ou ID do Certificado para funções — eles devem ser colocados entre aspas?

Um ID não deve ser colocado entre aspas quando passado para um método ou função:

Qual deve ser usado: aspas duplas ou aspas simples?

Não há diferença entre usar aspas simples ou duplas, mas recomendamos usar aspas duplas. Assim, por exemplo, ao inserir uma variável dentro de uma string, a variável será destacada em uma cor diferente, facilitando a percepção.

Como os espaços devem ser colocados?

Funciona do mesmo jeito se houver um espaço entre a variável e o sinal de igual (por exemplo, ans="yes", ans = "yes", ans= "yes", ans ="yes"?

O espaçamento não afeta o funcionamento de métodos, variáveis ou funções. No entanto, recomenda-se usar espaços no código para melhorar a legibilidade.

Como escrever comentários corretamente na calculadora

circle-check

Como comparar variáveis

Você pode controlar o fluxo do chatbot comparando os valores das variáveis. Isso permite criar lógica condicional, como verificar a idade de um usuário para conformidade legal ou direcionar interações com base na plataforma de mensageria do usuário.

Operadores suportados:

"+": adição "-"': subtração "*" multiplicação "/": divisão "%'": resto da divisão "^" "**": exponenciação "e" "E" "&&": E lógico "ou" "OU" "||": OU lógico

Operadores de comparação: "==" — igual a "!=" — diferente de ">" — maior que "<" — menor que ">=" — maior ou igual a "<=" — menor ou igual a

circle-exclamation

As variáveis devem ser comparadas na condição dentro do campo "Variável" (tanto nas configurações da conexão quanto nas configurações do bloco):

Exemplo de comparação de variável no campo "Variável" de um bloco de gatilho.

Exemplo de comparação de variável no campo "Variável" de uma conexão de bloco.

Como variáveis e gatilhos funcionam juntos

Para que uma conexão seja ativada, ambos os gatilhos devem ser atendidos:

  1. A condição no "Trigger" .

  2. A lógica de comparação no "Variável" .

Entendendo o campo "Variável"

Se você inserir apenas um nome de variável (por exemplo, client_type) no "Variável" campo sem uma expressão, o sistema verifica a existência ou verdade do valor da variável. Ele não não o compara com a entrada bruta do usuário.

Exemplo: A configuração abaixo verifica se o cliente é do WhatsApp, confirmando que a client_type variável é igual a 6 (onde 6 representa o WhatsApp).

client_type == 6

O exemplo abaixo funciona de forma idêntica:

circle-exclamation
circle-info

client_type == 3 transição se o valor da variável for igual a 3 attachments != None transição se a variável contiver qualquer valor attachments == None transição se a variável não estiver definida product_quantity >= 100 transição se a quantidade do produto for maior ou igual a 100 product_quantity <= 100 transição se a quantidade do produto for menor ou igual a 100 name == "John" transição se o nome da variável for John

Para verificar se uma variável está vazia ou não, use as expressões: "#{value}" == "" "#{value}" != ""

(onde value é o nome da variável).

O resultado da operação de comparação retorna um valor booleano: True ou Falso.

circle-exclamation
circle-exclamation
circle-exclamation

Exemplo: um bot que verifica a idade de um usuário (idade).

  • Se age < 18, ele envia uma mensagem para menores de idade.

  • Se age >= 18, ele envia uma mensagem para adultos.

Observe que o fluxo inclui um bloco sem gatilho, com conexões temporizadas saindo dele.

Este bloco foi projetado intencionalmente para demonstrar como criar fluxos em que o bot reage não às ações do usuário, mas aos resultados de cálculo. Na primeira etapa, a resposta é salva em uma variável e, em seguida, ocorre a comparação. O atraso nas setas é definido como 0 para uma resposta instantânea.

A comparação "Idade >= 18" também pode ser expressa como "maior ou igual a 18."

triangle-exclamation
circle-exclamation

Por exemplo, na imagem abaixo, o bloco será acionado se a variável phone estiver preenchida (ou seja, não for igual a None):

O próximo exemplo mostra como combinar operadores:

Se o cliente tiver uma variável de idade com um valor entre 18 e 99, o bloco será acionado. Se a variável estiver ausente, ou a idade for menor que 18 ou maior que 99, o bloco não será ativado.

circle-exclamation

Atualizado