...

Training Phrases: São as frases que quando o usuário escrever fará ele entrar naquele fluxo de conversa específico, é o gatilho que ativa o node cadastrado. Estas frases serão utilizadas para ensinar os algoritmos do TOTVS Carol Assistant a entender a intenção do cliente e disparar as ações e respostas necessárias para respondê-lo.

No exemplo a seguir, o gatilho do node é ativado quando o usuário está tentando fazer um pedido de pizza no chatbot. Para cadastrar as frases que ativam o node basta preencher os campos, caso seja desejado adicionar mais frases, clique na opção + Add a training phrase.

Recomendações de boas práticas de Training Phrases é usar no mínimo 10 frases, completamente diferentes e não genéricas.
1. Node name: É o nome do nó.
2. If an user says: em português é "Se um usuário disser", é onde deve ser inserida a frase que o cliente deve usar naquele node que será identificada como gatilho para a interação.
3. Remove: Remove a frase inserida.
4. +Add a training phrase: Adiciona uma frase de treinamento, em um node pode ser usado mais de uma frase de treinamento.
5. Melhores práticas: Ter pelo menos 10 frases de treinamento.
  
  Section
Parameters: Todos os dados podem ser extraídos das mensagens do usuário, identificados por meio do Nome do Parâmetro configurado

Section
1. + Add a parameter: Em português adicionar parâmetro
  Section
  1. Parameter name: Nome do parâmetro
  2. Parameter type: Tipo de parâmetro
    
    Parameter type map: São informações que fornecem o caminho para os valores de referência para os sinônimos. Toda entrada do mapa possui apenas um valor de referência e uma lista de sinônimos. São do tipo map os seguintes parameters:
    
    @carol.date-time
    @carol.date
    @carol.date-calendar
    @carol.date-period
    @carol.time
    @carol.time-period
    
    Parameter type list: São informações inseridas de valor único sem sinônimo nem valor de referência. São do tipo lista os seguintes parameters:
    
    @carol.color: Corresponde a entradas de cores como o roxo, quando uma cor é inserida o valor dela é extraído.
    @carol.image
    @carol.language
    
    Parameter type composite: É um tipo de lista que é usada quando se usa um alias. São do tipo composite os seguintes parameters:
    
    @carol.cardinal
    @carol.ordinal
    @carol.geo-country
    @carol.geo-city
    @carol.geo-state
    @carol.location
    @carol.zip-code
    @carol.geo-capital
    @carol.currency-name
    @carol.unit-area-name
    @carol.unit-length-name
    @carol.unit-speed-name
    @carol.unit-volume-name
    @carol.unit-weigth-name
    @carol.uint-information-name
    @carol.given-name
    @carol.last-name
    @carol.person
    @carol.music-genre
    @carol.email
    @carol.number
    @carol.number-integer
    @carol.number-sequence
    @carol.flight-number
    @carol.unit-area
    @carol.unit-currency
    @carol.unit-length
    @carol.unit-speed
    @carol.unit-volume
    @carol.unit-weight
    @carol.temperature
    @carol.phone-number
    
    Parameter type regexp: Alguns padrões não possuem padrões específicos, mas sim correspondentes, através deles é possível fornecer uma expressão regular.
    
    @carol.feedback-stars
    @carol.feedback-thumbs
    @carol.file
    @carol.unit-information
    @carol.any
    @carol.url
  3. Islist?
  4. Required?
  5. Prompts
  6. + Add prompt
  7. Add options?
Responses

Section
1. Respond with: Responda com
  1. Negrito
  2. Itálico
  3. Sublinhado
  4. Tarjado
  5. Marcadores
  6. Subscrição
  7. Sobrescrição
  8. Tipo de letra
  9. Cor da letra
  10. Marcador
  11. Cor
  12. Alinhamento
  13. Retornar ao normal a letra
  14. Inserir imagens
  15. Inserir link
  16. Inserir vídeo
2. + Add response: Adicionar uma resposta
  Section
3. End of conversation: ao chegar nesta intent a conversa será encerrada, dependendo do projeto não é indicado uma intent que encerre a conversation.
4. Additional resources to response: adiciona opções de respostas, fechadas ou abertas.
5. Jump to another Intent node?: Ao se acionar essa opção o cliente será direcionado a outro nó, ou seja, outro trecho do caminho dependendo da resposta dele.
Named Queries: é possível adicionar queries (consultas estáticas) a uma conversation e configurá-las.
Section
1. + Add a named query: ao acionar este botão a query é adicionada permitindo nomear e configurar.
  Section
2. Named Query: nome da consulta que pode ser dado, ou escolhido um já existente.
3. Fields: campos retornados na resposta.
4. Page size: número de registros a serem obtidos (limitado a 1000).
5. Sort field: campo para classificar as informações.
6. Sort order: no caso de Sort field ser usado, a ordem a ser considerada (Valores: ASC ou DESC).
7. + Add sort field: adiciona mais campos para classificação e ordenação.

Fulfillment

Section

O mecanismo de fulfillment do Carol Assistant fornece uma plataforma aberta para criar lógica de negócios, integrações com APIs externas ou criar respostas de forma programática. Por enquanto, oferecemos suporte ao Python 3 como linguagem de programação padrão para criar realizações. Para o correto uso deste recurso, é necessário o correto entendimento dos principais conceitos.

Sua conversation pode ter um fulfillment para cada node de Intenção. O fulfillment do node de intenção será executado quando o node de intenção for ativado por meio de uma mensagem do usuário

Plano de execução do node de Intenção
Section
Criação de um novo Fulfillment

Para adicionar um fulfillment a um node de intenção, selecione a guia preenchimento no painel detalhe do node de intenção e clique no botão + Add a fulfillment.
Section

Depois disso, o Carol Assistant adicionará um novo cumprimento ao node de intenção e abrirá o Ambiente de Desenvolvimento de fulfillment.
Ambiente de Desenvolvimento de fulfillment (FDE)

Com o fulfillment do FDE, os desenvolvedores podem escrever e testar os atendimentos. A partir da versão Carol 3.37, o FDE se parece com a imagem a seguir.

WebHooks

Outra forma de permitir a execução de codigo fonte customizado é utilizando webhooks. Webhook é um método de ampliar ou alterar o comportamento de uma aplicação utilizando callbacks (ligações de retorno) personalizados com contratos, autenticação e padrões pré-estabelicidos. O TOTVS Carol Assistente permite que antes de cada envio de resposta ao usuário da conversa, uma chamada autenticada a um endpoint externo sejá realizada com o conteúdo do contexto da conversa e aguarde uma nova resposta a ser enviada para a conversa com o usuário.

Configuração do WebHook

Para configurar o webhook no nó de intenção, na aba fulfillment, selecione o fulfillment type Webhook.

Agora você pode adicionar a URL do endpoint que irá receber a chamada do webhook. Caso necessário pode-se informar diferentes endpoints para ambientes de desenvolvimento e produção, para isso basta desmarcar o checkbox Use the same URL for Production and Development?

Image Added

Chamadas e payloads

Quando configurado, o TOTVS Carol Assistente, sempre que o nó de intenção for ativado durante uma conversa, irá fazer uma chamada HTTP usando o comando POST para a URL do endpoint configurada. Além dos cabeçalhos http habituais, será enviado um cabeçado específico para a autenticação com o token mostrado na configuração do fulfillment, o que deverá ser validado na ponta que receberá a chamada. Os cabeçalhos da chamada são:

Cabeçalho	Descrição
X-Assistant-Signature-Token	Contém o Webhook token gerado aleatóriamente no momento da configuração do webhook do nó de intenção.
Content-Type	Tipo de conteúdo do payload. Sempre será 'application/json'

O payload da chamada do webhook contém as seguintes propriedades:

Parâmetro	Tipo	Descrição
intent_name	`Str`	Nome do nó ativado
parameters	`Dict`	Todos os parametros desse contexto de conversa
sessionLog	`List`	Lista de ID de sessões até esse ponto da conversa
namedQueries	`Dict`	Resultados da Named Query (se houver) (a ser descontinuado)
query	`String`	Query executada (se houver) (a ser descontinuado)
language	`String`	Idioma da conversa
carolOrganization	`String`	Nome da Organização
carolEnvironment	`String`	Nome do Ambiente
carolOrganizationId	`String`	Id da Organização
carolEnvironmentId	`String`	Id do Ambiente
sessionId	`String`	Id da sessão da conversa atual
isProduction	`Boolean`	Informa se a convesa está acontecendo em Produção ou Desenvolvimento
channelName	`String`	Nome do canal por onde a mensagem chegou

Retorno:

Para retornar dados pelo WebHook, o TOTVS Carol Assistente espera que os dados estejam em um formado pré definido. O retorno deverá ser um objeto JSON com as seguintes propriedades:

Parâmetro	Obrigatório?	Tipo	Descrição
`message`	Sim	`String`	Mensagem que será retornada na conversa
`short_message`	Não	`String`	Mensagem curta de retorno
`jump_to`	Não	`String`	Nome do nó para o qual a conversa será direcionada
`options`	Não	`Array[Str]`	Lista de opções pré-definidas que aparecerão como botões na resposta
`logout`	Não	`Boolean`	Destrói a sessão de usuário na conversa
`parameters`	Não	`Object`	Parametros que serão adicionados no contexto da conversa

Canais de conversação

Canal Telegram

Antes de configurar o canal Carol Assistant Telegram, é preciso criar seu novo bot usando o BotFather do Telegram. Verifique a documentação do Telegram Bot sobre como criar um Telegram Bot em<{+}https://core.telegram.org/bots+>

Limitações

Section

Wiki Markup

O canal Carol Assistant Telegram não suporta \[modo em linha\] (https://core.telegram.org/bots#inline-mode) e recursos avançados do Telegram como: pagamentos, jogos, teclados embutidos, retornos de chamada e comandos (o desenvolvedor pode treinar uma intenção node para oferecer suporte a um comando de barra, adicionando um comando de barra nas frases de treinamento do node de intenção).
Ao formatar as respostas, lembre-se de que o Telegram aceita apenas um subconjunto de tags de formatação HTML (o Carol Assistant removerá todas as tags não suportadas antes de enviar mensagens para a API do Telegram:
!worddav27570732187d4f150778e0cf6edad7b5.png|height=436,width=522!

Check-list

Section
Crie um novo bot com @botfather Obtenha o token da API do Telegram Bot em @botfather Defina o secret TELEGRAM_TOKEN no Carol Assistant Secrets Adicionar /start como frase de treinamento para o node de intenção de boas-vindas padrão

Configurar

Adicionar token de API do Telegram Bot ao Carol Assistant

Section

Com o seu novo Telegram Bot pronto e o token da API do Telegram Bot recuperado, agora o desenvolvedor pode configurar o Carol Assistant para responder às consultas do Telegram.

Primeiro, adicione seu token de API do Telegram Bot como um novo secret do Carol Assistant. Clique no botão Criar secret e preencha todas as informações necessárias.

Depois de inserir as informações do token, clique em Salvar.

Nota

title	IMPORTANTE:

o nome do secret não pode ser alterado. Padronizamos *TELEGRAM_TOKEN* como o nome do token e usamos internamente na integração do canal

Configure o ponto de extremidade do webhook na configuração do Telegram Bot

Depois de configurar o token da API do Telegram Bot no Carol Assistant, precisamos informar a API do Telegram para onde enviar mensagens do usuário do Telegram para a API do Carol Assistant.

Para ajudar a concluir esta etapa, fornecemos um endpoint:

{+}https://telegram-assistantbackend.apps.carol.ai/setup+

Este ponto de extremidade aceita apenas o método POST HTTP.

...

Configurar

Section

Abra o "App Studio" dentro do Microsoft Teams:

Crie um novo aplicativo do zero
Defina o nome abreviado pelo qual deseja que o seu assistente seja identificado.
Defina um nome completo para o aplicativo e também uma descrição que será mostrada aos usuários.
Defina a versão do aplicativo, por exemplo: 1.0.0
Defina o nome da sua empresa
Definir o site da empresa
Defina uma página "Declaração de privacidade" e "Termos de uso".
Defina a marca do seu Assistente
Abra a página Bots e configure

Defina o nome do bot pelo qual você deseja que seu assistente seja identificado. Será o nome que os usuários irão visualizar e mencionar como Assistente.
Também é hora de escolher como seu Assistente será usado. Existem algumas possibilidades:
- Pessoal
- Equipe
- Conversa em grupo
E então crie o bot

Após a configuração do bot, você verá uma página como esta:

Copie o ID acima do nome do bot e cole-o em ** MSTEAM_APP_ID **
Clique no botão ** Gerar nova senha **, copie a senha e cole no campo ** MSTEAM_TOKEN **.
Obtenha o URL do Webhook na página do Carol Assistant e cole no campo ** Endpoint de mensagens **

Vá para a página ** Testar e Distribuir **

Clique em ** Publicar **
Envie o aplicativo para o catálogo da sua organização.

Nota

title	CUIDADO:

Certifique-se de não enviar o aplicativo para os aplicativos globais. Nesse caso, qualquer organização pode usar seu bot.

Wiki Markup
Navegue até \[Centro de administração do Microsoft Teams\] (https://admin.teams.microsoft.com/)> Aplicativos do Teams> Gerenciar aplicativos.

Pesquise o nome do aplicativo que você acabou de enviar
Clique e publique.

Instalando o App / Bot

...

Árvore de páginas

Versões comparadas

Versão antiga 27

Nova versão Atual

Chave