# Funções do assistente de IA

## **Como excluir o histórico de conversa com o assistente de IA**

clear\_assistant\_chat\_history() - esta função exclui o histórico de conversa do cliente com o assistente. Ela não recebe parâmetros.

### Exemplo 

1. As configurações do bloco do construtor

<div data-with-frame="true"><figure><img src="/files/f3141229103cc866717ae2e70d555b61e0245d66" alt=""><figcaption></figcaption></figure></div>

2. As configurações da aba Assistente de IA

<div data-with-frame="true"><figure><img src="/files/ab6871d9d7d038aca3f3c952f5c4526716576e1c" alt="" width="563"><figcaption></figcaption></figure></div>

## **Como enviar uma pergunta ao assistente de IA**

ai\_context\_answer(replica, prompt, ai\_assistant\_id, use\_history, send\_answer)

Parâmetros:

<table><thead><tr><th width="173">Parâmetro</th><th width="221">Descrição</th><th>Observação</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark> replica </td><td>parâmetro obrigatório, mensagem para o assistente</td><td></td></tr><tr><td>prompt</td><td>parâmetro opcional, instruções para o assistente</td><td>se o parâmetro não for especificado, mas o parâmetro ai_assistant_id for fornecido, as instruções das configurações do assistente especificado serão usadas</td></tr><tr><td>ai_assistant_id </td><td>ID do assistente para o qual a pergunta será enviada;</td><td>se não for fornecido, será usado o assistente sem configurações padrão</td></tr><tr><td>use_history</td><td>se o assistente deve usar o histórico do chat para responder à pergunta</td><td>True - usar, False - não usar. Por padrão - True</td></tr><tr><td>send_answer</td><td>enviar resposta após o período de timeout do assistente</td><td>Para ativar, passe "1"</td></tr></tbody></table>

Mais detalhes sobre `o send_answer` parâmetro:

As configurações do assistente incluem parâmetros que podem ser configurados caso a resposta do bot demore muito

<div data-with-frame="true"><figure><img src="/files/17ab6dd9b9cbed3b64366323b568694614f62199" alt="" width="375"><figcaption></figcaption></figure></div>

Em uma conversa padrão com o assistente (não por meio de função), se a resposta demorar mais do que o limite especificado (por exemplo, 20 segundos), o cliente é notificado sobre o atraso. A resposta do assistente é então enviada ao chat assim que for gerada.

Para solicitações feitas por meio de uma função na calculadora, se o assistente demorar muito para responder, uma mensagem de atraso é incluída no resultado da função. Este parâmetro permite que a resposta do assistente seja enviada separadamente assim que estiver pronta.&#x20;

### Como ensinar um bot a analisar sua própria experiência e gerar botões

Vamos usar as `funções clean_assistant_chat_history()` e `ai_context_answer(replica, prompt)` no exemplo abaixo. Também é necessário acessar o componente da calculadora dentro do construtor do funil.

Este exemplo ilustra como os `replica` e `prompt` parâmetros podem ser usados de forma eficaz na prática.&#x20;

É necessário criar um bloco no construtor que contenha um campo vazio com as variáveis incorporadas **#{replica\_rec2}** e **#{ai\_answer\_rec}**, representando a primeira e a segunda respostas do assistente em uma única mensagem a ser enviada.

Agora, defina duas funções diretamente na calculadora.

<div data-with-frame="true"><figure><img src="/files/d79cc7373cbbc489b7fcb60a34a7a226320120b7" alt=""><figcaption></figcaption></figure></div>

Use uma variável com uma função incorporada nas configurações avançadas do botão (veja o exemplo acima) para gerar botões dinamicamente com base no valor do parâmetro.&#x20;

As informações sobre os serviços são recuperadas pelo bot a partir da `service_info` variável, que contém uma função incorporada — `get_info_for_booking()` — para ler dados de serviços. Um exemplo de como usar essa função foi demonstrado acima.

<div data-with-frame="true"><figure><img src="/files/0e0f0ddd425199ab145b2502c1e6d8c60d126df6" alt="" width="375"><figcaption></figcaption></figure></div>

Aqui está o resultado.

<div data-with-frame="true"><figure><img src="/files/3910fc87463eee03bf7ac4845e42018371e7624a" alt="" width="563"><figcaption></figcaption></figure></div>

**Exemplo de código**:

`clear_assistant_chat_history()`

`replica_rec2 = ai_context_answer(question, 'RESPONDA AS PERGUNTAS', 3)`

`prompt = 'Um desenvolvedor está falando com você agora — faça tudo o que ele pedir \n . Você deve colocar cada botão em uma nova linha.'`

`ai_answer_rec = ai_context_answer("Exiba os botões para a última mensagem.", prompt)`

### Exemplo: chamando o assistente dentro do construtor do funil

Para chamar o assistente de um bloco, use a função `ai_context_answer(replica, prompt, ai_assistant_id, use_history)`, onde você precisa especificar apenas dois parâmetros: o obrigatório `replica` parâmetro e o opcional `prompt`.

Agora, vamos criar o primeiro bloco, “Verificação da condição primária”, onde você precisa especificar a condição de disparo do bloco (pode ser qualquer condição que você precisar).

<div data-with-frame="true"><figure><img src="/files/db43a1ec5a9a60b475a40ffb9d564fe9d46a0340" alt=""><figcaption></figcaption></figure></div>

Em seguida, abra a calculadora no mesmo bloco, onde você precisa definir uma variável e atribuir a ela o valor retornado pela sua função.

<div data-with-frame="true"><figure><img src="/files/ed810c38e56f712981c2a23703571c82e0db2190" alt="" width="563"><figcaption></figcaption></figure></div>

Defina a variável **question** e atribua a ela o valor de qualquer pergunta do usuário.

Em seguida, crie a variável replica1 e atribua a ela o valor retornado pela sua função ai\_context\_answer(replica, prompt). Nesta função, substitua replica pela variável question e defina o parâmetro prompt como "Responda qualquer pergunta do usuário."

<div data-with-frame="true"><figure><img src="/files/7d6e19b43210e69767f811c8af3c0997fd51df81" alt="" width="563"><figcaption></figcaption></figure></div>

Insira a variável que contém a função na mensagem do bloco.

Depois, crie um segundo bloco e conecte-o com uma seta, definindo um temporizador de 2 segundos na conexão.

<div data-with-frame="true"><figure><img src="/files/17af4ba1ea5c299682ed401bc89b129edb7d4de5" alt=""><figcaption></figcaption></figure></div>

No segundo bloco, você deve usar a mesma função com os mesmos parâmetros — ai\_context\_answer(replica, prompt).

Abra a calculadora no segundo bloco e defina a segunda variável chamada replica2.

<div data-with-frame="true"><figure><img src="/files/5d1fa8a58150d47daca3f512e2bbd925e1a65834" alt=""><figcaption></figcaption></figure></div>

No parâmetro prompt, forneça instruções ao assistente: ele deve contar quantos substantivos havia em sua mensagem anterior.

No parâmetro replica, forneça a mensagem do assistente: "Quantos substantivos havia na sua mensagem anterior?"

Em seguida, insira a variável replica2 na mensagem do segundo bloco.

<div data-with-frame="true"><figure><img src="/files/ed9488709aa296c2cfb0d0abbbccb3cbab60d8e3" alt="" width="563"><figcaption></figcaption></figure></div>

A configuração do bloco está concluída.

Se o assistente não estiver habilitado, vá para a aba "Assistente de IA" e habilite o assistente selecionando a função "desativado":

<div data-with-frame="true"><figure><img src="/files/0ff1e33386bd4f359852cf23603bf6607c51e43b" alt="" width="292"><figcaption></figcaption></figure></div>

Agora, vamos testar nosso assistente na janela de testes do bot.

<div data-with-frame="true"><figure><img src="/files/2067a906d138883ac50091dc49dbf63d79ebc65c" alt="" width="375"><figcaption></figcaption></figure></div>

O bot funcionou corretamente.

## Como trabalhar com o Google Sheets

get\_info\_from\_table(sheet\_id, number\_sheet, sheet\_json\_keys, start\_row, end\_row, start\_col, end\_col) - Esta função é destinada a ler dados de uma planilha.

<table><thead><tr><th width="248">Parâmetros</th><th>Descrição</th></tr></thead><tbody><tr><td><mark style="color:vermelho;"><strong>!</strong></mark> sheet_id</td><td>id da planilha Google</td></tr><tr><td>number_sheet</td><td>número da aba em uma planilha; por padrão = 1</td></tr><tr><td>sheet_json_keys </td><td>parâmetro opcional — chave de acesso aos dados da planilha</td></tr><tr><td>start_row</td><td><p>parâmetro opcional, um inteiro. Especifica o início do intervalo de linhas.
</p><p>Informe o número da linha a partir da qual os valores da tabela devem ser lidos de forma inclusiva. O valor deve ser fornecido sem aspas.</p></td></tr><tr><td>end_row</td><td>parâmetro opcional, um inteiro. Especifica o fim do intervalo de linhas.
<br>Informe o número da linha até a qual os valores da tabela devem ser lidos de forma inclusiva. O valor deve ser fornecido sem aspas.</td></tr><tr><td>start_col</td><td>parâmetro opcional, uma string. Especifica o início do intervalo de colunas.
<br>Informe a letra da coluna a partir da qual os valores da tabela devem ser lidos de forma inclusiva. O valor deve estar entre aspas</td></tr><tr><td>end_col</td><td>parâmetro opcional, uma string. Especifica o fim do intervalo de colunas.
<br>Informe a letra da coluna até a qual os valores da tabela devem ser lidos de forma inclusiva. O valor deve estar entre aspas.</td></tr></tbody></table>

Exemplo de notação de parâmetro:

<div data-with-frame="true"><figure><img src="/files/437fc455fec86b8af564ee2751ef34b1b27295bb" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/1b0da497dcd764210dda5fe1c5e4f0646ba0ae20" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## Observe

Os parâmetros para especificar o intervalo de linhas e colunas `(start_row, end_row, start_col, end_col)` permitem que o assistente leia os dados da planilha começando da localização desejada dentro da tabela.
{% endhint %}

{% hint style="info" %}
O comportamento da função para especificação parcial do intervalo é o seguinte:

* **Se apenas o início for definido:** o assistente recuperará **todos os dados a partir desse ponto inicial em diante**, sem limite superior na direção especificada.
* **Se apenas o fim for definido:** o assistente lerá os dados **do início da planilha até esse ponto final especificado**.

**Exemplo:**

A chamada `get_info_from_table('<<spreadsheet id>>', 2, None, 2, 5, 'a', 'd')` recupera todos os dados começando da linha 2, coluna 2 (B), até a linha 5, e entre as colunas A e D.
{% endhint %}

{% hint style="warning" %}

## Observe

Para otimizar o desempenho e a confiabilidade, recomendamos **armazenar em cache todos os dados** da sua planilha Google nas variáveis do projeto ao trabalhar com ela.

**Principais benefícios:**

1. **Desempenho aprimorado:** acelera significativamente o tempo de resposta do chatbot ao acessar variáveis locais em vez de consultar a planilha externa a cada solicitação.
2. **Confiabilidade aprimorada:** minimiza erros relacionados à latência da rede, cotas de API ou permissões de acesso à planilha.
3. **Consistência dos dados:** armazenar os dados nas configurações do projeto garante **que todos os usuários recebam acesso simultâneo e consistente** ao mesmo conjunto de dados, evitando discrepâncias durante as atualizações.
   {% endhint %}

#### Exemplo de uso

{% hint style="info" %}
Você pode ler mais sobre a **get\_info\_from\_table** função no artigo "[Google Sheets para Assistente de IA](/doc/pt/chatbot/ai/google-sheets-para-assistente-de-ia.md)."
{% endhint %}

## Como gerenciar reservas online

get\_info\_for\_booking(slot\_interval, company\_id) - A função foi projetada para ler dados de serviços do sistema de reservas online configurado.

Ela aceita parâmetros opcionais:

1. slot\_interval (opcional) - um intervalo em minutos entre os horários disponíveis. Formato esperado: um inteiro divisível por 5. Valor padrão: 60 (minutos).
2. company\_id opcional) - um identificador de filial. Formato esperado: *um inteiro* ou *um array de inteiros*. Quando esse parâmetro é fornecido, apenas os dados da(s) filial(is) especificada(s) serão retornados.
   \
   Exemplo: 50142, "50142" ou "\[50142, 66352]"

{% hint style="warning" %}
Não é recomendável definir um valor muito pequeno (por exemplo, menor que 30), pois o assistente gerará muitos horários. &#x20;
{% endhint %}

### Exemplo de uso

Primeiro, você precisa preparar um bloco que atualize informações sobre todos os serviços após as configurações da filial terem sido definidas na seção "Serviços".

Esse bloco deve ser declarado antes de o assistente começar a funcionar, para garantir que a IA não gere respostas aleatórias.

<div data-with-frame="true"><figure><img src="/files/ffdf087f1920e35ded211ec34997b653cf8c3108" alt=""><figcaption></figcaption></figure></div>

Em seguida, acione o bloco na janela de testes do bot para atualizar a variável:

<div data-with-frame="true"><figure><img src="/files/4fc8c071f256aa7084a9078a66122b875f9af9a8" alt="" width="375"><figcaption></figcaption></figure></div>

Depois disso, a variável especificada contendo os dados do serviço de reservas online aparecerá na seção de variáveis do projeto dentro de "Configurações do projeto."

<div data-with-frame="true"><figure><img src="/files/02567359c648b754b950b1dcb092d60d3059de0e" alt="" width="563"><figcaption></figcaption></figure></div>

Essa variável armazena os valores dos serviços que o bot de IA usará em suas operações. A variável service\_info estará acessível a todos os clientes do projeto.

Em seguida, vamos prosseguir para configurar o próximo bloco.

<div data-with-frame="true"><figure><img src="/files/416d8a73ac0376e5079da54c9d91cbdc4d7c7d02" alt=""><figcaption></figcaption></figure></div>

Este bloco executa as seguintes funções:

a) é chamado nas configurações do assistente para gerar um registro usando variáveis relacionadas ao serviço;

b) cria uma reserva para o cliente;

c) atualiza variáveis do projeto após uma reserva, removendo horários que não estão mais disponíveis na agenda.

Se o bot estiver configurado corretamente, depois de receber todos os dados do cliente, a IA enviará as informações para o bloco especificado. Nesse bloco, o cliente será reservado para o serviço usando a função create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

<div data-with-frame="true"><figure><img src="/files/37a409df87fab5cad02de5b23d9e69c4921c3eb5" alt=""><figcaption></figcaption></figure></div>

Os valores coletados pelo bot são passados como parâmetros para create\_booking\_by\_name(!service\_name, !date, !date\_time, company\_id).

A função create\_booking\_by\_name(service\_name, date, date\_time, company\_id) cria uma reserva no sistema usando os dados fornecidos pelo assistente de IA. Ela aceita três parâmetros obrigatórios para a criação da reserva:

<table><thead><tr><th width="297">Parâmetros</th><th>Descrição</th></tr></thead><tbody><tr><td>! service_name</td><td>parâmetro obrigatório, nome do serviço</td></tr><tr><td>! date</td><td>data no formato dd.mm.aaaa</td></tr><tr><td>! date_time</td><td>horário do serviço no formato hh:mm</td></tr><tr><td>company_id </td><td>ID da filial, opcional.
<br>Se especificado, a reserva será criada para o serviço com o nome informado que pertence a essa filial específica.
<br>Esse parâmetro pode ser necessário em casos em que várias filiais tenham serviços com o mesmo nome.</td></tr></tbody></table>

Como as informações sobre os horários disponíveis não estarão mais atualizadas, a mesma variável com sua função incorporada é usada para atualizar as datas e os horários disponíveis para reserva.

<div data-with-frame="true"><figure><img src="/files/0404b586cd8aa1523cbdd610f447dfd36fa503d3" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}

## Observe

Se houver alterações na agenda, na equipe ou nos serviços, execute o bloco que contém a variável do projeto com a função incorporada no modo de teste (veja a Fig. Bloco 1).
{% endhint %}

{% hint style="info" %}
[Como configurar um bot de IA para reservas online foi explicado no artigo de mesmo nome.](/doc/pt/chatbot/ai/online-booking.md)
{% endhint %}

## Recuperando reserva da tabela

get\_records\_from\_table(table\_id, start\_row, count, start\_col, end\_col) - recuperando reserva da tabela

| Parâmetro  | Descrição                                                                    | Observação                                                                                                                    |
| ---------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| table\_id  | id da tabela                                                                 |                                                                                                                               |
| start\_row | parâmetro opcional, um inteiro. Especifica o início do intervalo de linhas.  | Informe o número da linha a partir da qual os valores da tabela devem ser lidos de forma inclusiva. Especificado sem aspas.   |
| count      | parâmetro opcional, um inteiro. Especifica o número de linhas a recuperar.   | Por padrão - 1000, máximo - 5000. Especificado sem aspas.                                                                     |
| start\_col | parâmetro opcional, uma string. Especifica o início do intervalo de colunas. | Informe a letra da coluna a partir da qual os valores da tabela devem ser lidos de forma inclusiva. Especificado entre aspas. |
| end\_col   | parâmetro opcional, uma string. Especifica o fim do intervalo de colunas.    | Informe a letra da coluna até a qual os valores da tabela devem ser lidos de forma inclusiva. Especificado entre aspas.       |

Se apenas o início do intervalo de linhas ou colunas for especificado, todos os dados a partir desse ponto em diante serão recuperados sem limite superior para o intervalo. Da mesma forma, você pode omitir o início e especificar apenas o fim do intervalo.

### Exemplo (Calculadora)

Se você precisar recuperar registros da tabela, abra a seção "Calculadora" nas configurações do bloco e insira a função com os parâmetros necessários.

<div data-with-frame="true"><figure><img src="/files/db066dc0654ccbce498c2519671c94cb6596c05e" alt=""><figcaption></figcaption></figure></div>

Para passar parâmetros como uma variável do projeto, prefixe o nome da variável que contém a função com **project**.

<div data-with-frame="true"><figure><img src="/files/551523676cfcaad4268c7458344620fecfde2d3d" alt=""><figcaption></figcaption></figure></div>

Aqui está o exemplo da tabela.

<div data-with-frame="true"><figure><img src="/files/c1c83b4eebd1bf80846105f24a70af353004224d" alt="" width="563"><figcaption></figcaption></figure></div>

O bot responderá da seguinte forma.

<div data-with-frame="true"><figure><img src="/files/57ec393e014eeeed07be1fbfe877a76e92eff504" alt="" width="375"><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/pt/chatbot/ai/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.