Existem três tipos de funções que atuam como ganchos durante a execução de uma ação:

• Execução da ação (obrigatório) — chamada no final de uma ação, depois de preencher todos os parâmetros.
• Carregador de parâmetros (opcional) — chamado depois preencher todos os parâmetros estáticos.
• Manipulador de contexto (opcional) — chamado para cada entrada de usuário no curso de uma ação.

Fluxo de execução de uma ação

Sempre que um usuário insere uma sentença no Zia, o Zia tenta entender a entrada do usuário, e vê se ela combina com uma das ações configuradas. Se corresponder a uma das ações configuradas, o Zia solicitará ao usuário os parâmetros necessários para executar uma ação como uma conversa. Para cada entrada do usuário, a função do manipulador de contexto será chamada. Depois de preencher todos os parâmetros estáticos, a função do carregador de parâmetros será chamada apenas uma vez.

Depois de receber do usuário todos os parâmetros configurados, o Zia executa a função de execução da ação e responde ao usuário com a mensagem retornada pela função de execução.

Adicionar uma nova ação

Novas ações podem ser adicionadas a partir da guia "Personalizar". Personalizar fornece um ambiente parecido com o Sandbox no qual você pode desenvolver e testar novas ações. Os pontos a seguir explicam as etapas que estão envolvidas na adição de novas ações.

Para adicionar uma nova ação

1. Clique em Adicionar Ação.
2. Insira o Nome da Ação.
3. Com base na ação pretendida, escolha se a ação deve Responder a uma pergunta ou Executar uma operação.
4. Se a ação for responder a uma pergunta, escolha se a resposta deve ser dada diretamente ou se a resposta deve ser construída a partir do CRM.
5. Defina as Sentenças de amostra e os Parâmetros.
6. Clique em Avançar.
   
7. Se necessário, configure as funções Carregador de parâmetros e Manipulador de contexto.
8. Clique em Editar Código de Execução.
9. Defina a Função de Execução.
10. Clique em Concluído.
    A ação pretendida é criada e estará disponível no chat do Zia somente após ela ser publicada.

Definir sentenças de amostra

Definir sentenças de amostra é a chave na definição da ação, pois é o que o usuário provavelmente dirá ao Zia para acionar uma ação. Vamos dar uma olhada em algumas sentenças de amostra:

• Para ações que pretendem executar uma operação, as sentenças de amostra devem ser definidas na seção "Como esta operação será chamada?".
• Para ações que pretendem responder a uma pergunta, as sentenças de amostra devem ser definidas na seção "Como esta pergunta pode ser feita?".
• Qualquer texto digitado como sentença de amostra pode ser selecionado e marcado como um parâmetro. Ao selecionar o texto, aparecerá uma janela pop-up para você associar qualquer parâmetro ao texto selecionado, ou criar um novo parâmetro para associá-lo ao texto.

Você pode adicionar mais sentenças de amostra clicando no ícone "+" e remover qualquer sentença específica clicando no ícone "-".

Você também pode reordenar essas sentenças para deixar as sentenças mais usadas na parte superior, usando o ícone de reordenar ao lado da caixa de texto das sentenças de amostra.

As primeiras três sentenças de amostra adicionadas pelo usuário serão exibidas como uma sugestão para chamar uma ação. Assim, é uma prática recomendada usar sentenças de destaque que sejam fáceis de lembrar.

Definir parâmetros

Os parâmetros são dados de entrada que devem ser recebidos do usuário para completar uma ação. Você pode adicionar um novo parâmetro à ação clicando na opção "Novo" na lista de parâmetros ou na caixa de diálogo de sugestões de parâmetros que aparece ao marcar parâmetros em sentenças de amostra.

Na janela pop-up Novo parâmetro, insira as seguintes informações:

Observe que o usuário pode fornecer valores para todos estes tipos de dados no idioma inglês e o Zia converterá a sentença literal no tipo de dados declarado.

1. Nome do parâmetro – um nome de parâmetro válido deve seguir os seguintes pontos.
   • Um nome de parâmetro válido deve começar com uma letra minúscula.
   • Não são permitidos caracteres diferentes de letras, números e símbolo de sublinhado.
   • Um nome de parâmetro deve ser único para uma ação.
   • Os nomes a seguir não podem ser usados como nome de parâmetro, pois são palavras reservadas no Zia (userInput, previousParam, additionalParams, sessionData, broadcast, previousUserMsgs, cache, org e user).
2. Tipo de parâmetro – escolha um tipo de dados apt para o parâmetro. O Zia suporta os seguintes tipos de dados:
   • Texto – qualquer sequência de caracteres
   • Número – qualquer número válido
   • Hora – qualquer horário válido
   • Data – qualquer data válida
   • Matriz de seleção única – uma lista de opções disponíveis a partir da qual o usuário pode escolher uma.
   • Matriz de seleção múltipla – uma lista de opções disponíveis a partir da qual o usuário pode escolher mais de uma.
3. Parâmetros do tipo matriz – nos parâmetros do tipo matriz, você pode inserir as informações adicionais a seguir:
   • Valores da matriz – você pode incluir uma lista de opções a partir da qual o usuário pode escolher uma ou várias opções. Ou você pode inserir uma ID para cada opção ou usar a ID gerada automaticamente à medida que digita apenas os valores.
   • Modo de entrada – especifica a forma que um parâmetro de matriz é solicitado ao usuário. Pode ser Textual ou Visual. Se Textual for escolhido, o usuário poderá digitar (em caso de chat) ou falar (em caso de voz) o valor preferido que deseja atribuir ao parâmetro de matriz. No caso do modo de entrada Visual, o usuário precisará clicar ou tocar para selecionar sua entrada a partir dos valores da matriz, exibidos como um botão de opção (em caso de seleção única) ou caixa de seleção (em caso de seleção múltipla).
     
4. Mensagem de prompt – é a pergunta que o Zia faria ao usuário para obter a entrada do valor do parâmetro como uma parte da conversa do Zia com o usuário. Por exemplo, para obter o valor do parâmetro "starttime" na ação de criar evento, a mensagem de prompt deve ser definida como "Que horas o evento começa?" ou "De quando é o evento?". Ou você pode substituir a mensagem de prompt de um parâmetro pela função do manipulador de contexto.

Reordenar os parâmetros – o fluxo da conversa do Zia depende da ordem dos parâmetros definidos. Ao detectar uma ação, o Zia solicitará todos os parâmetros, um a um, com a respectiva mensagem de prompt na ordem em que estão definidos. Você pode reorganizar os parâmetros mesmo depois de criá-los, basta arrastar e soltar um parâmetro individual na posição desejada.

Definir funções

O fluxo da conversa e a execução de uma ação são determinados pelas funções definidas para a ação específica. As funções são ganchos personalizados escritos por desenvolvedores de ação que são chamados pelo Zia durante o curso de uma execução de ação em pontos de chamada apt.

Todas as funções devem ser escritas em Deluge. Deluge é uma linguagem de script on-line do ambiente de nuvem do Zoho. Consulte este guia para obter uma explicação detalhada do Deluge.

Existem 3 funções que atuam como ganchos no curso da execução do Zia. O Zia chamará as funções nos pontos de chamada apt com valores exatos para todos os argumentos. Todas as funções definidas devem retornar o valor do tipo de dados especificado.

Os seguintes argumentos de entrada definidos pelo sistema estão disponíveis para todas as funções, além dos argumentos específicos da função.

Além dos argumentos definidos pelo sistema acima, todos os parâmetros estáticos definidos para a ação também estarão disponíveis como argumentos de entrada para todas as funções. Cada parâmetro estático é, por si só, um argumento para todas as funções.

O Zia preencherá os valores apt para todas as variáveis e os passará como argumentos de entrada para todas as funções.

Cada função possui sua própria especificação de dados de retorno. Observe que é da responsabilidade do desenvolvedor cumprir o contrato de dados de retorno para o funcionamento adequado da sua ação.

Definir a função do carregador de parâmetros

A função do carregador de parâmetros é usada para adicionar novos parâmetros à ação dinamicamente no tempo de execução, além dos parâmetros definidos estatisticamente. Isso é útil quando não se conhece os parâmetros de uma ação antecipadamente, normalmente quando os parâmetros são diferentes com base nos usuários. É opcional definir a função do carregador de parâmetros.

Por exemplo, se formos escrever uma ação para criar uma tarefa dentro do CRM, o formulário de criação da tarefa será diferente para diferentes usuários com base nas configurações de layout da sua configuração. Nesses casos, carregamos os campos do formulário de criação da tarefa como parâmetros dinâmicos através da função do carregador de parâmetros, de modo que o Zia consiga solicitar esses parâmetros, um a um, para criar uma tarefa.

Observe que o Zia não conseguirá detectar os valores para os parâmetros dinâmicos carregados a partir das funções do carregador de parâmetros, que podem ter sido mencionados na sentença de chamada. O Zia só solicitará ao usuário os parâmetros dinâmicos, um a um, por meio da mensagem de prompt que é declarada para cada um dos parâmetros da função do carregador de parâmetros.

Ponto de chamada

Após o Zia detectar a ação na entrada do usuário, os possíveis valores de parâmetros estáticos presentes na entrada também serão detectados. Os parâmetros estáticos ausentes serão solicitados ao usuário, um a um, na mesma ordem em que estão definidos. Depois de preencher todos os parâmetros estáticos, o Zia chamará a função do carregador de parâmetros com os valores apt para todos os argumentos de entrada.

Se não houver parâmetros estáticos definidos, a função do carregador de parâmetros será chamada sempre que o Zia detectar uma ação. A função do carregador de parâmetros será chamada apenas uma vez durante um ciclo de execução da ação.

Argumentos de entrada

Além dos argumentos de entrada definidos pelo sistema, os seguintes argumentos de entrada também estão disponíveis para a função do carregador de parâmetros.

Valor de retorno

A função de valor de retorno deve retornar um mapa no formato a seguir.

additionalParams (obrigatório) – o valor desta chave deve ser uma lista de elementos de parâmetros. Cada parâmetro deve ser do tipo de dados de mapa. Veja a seguir as propriedades de um objeto de mapa de parâmetros.

1. name – nome do parâmetro.
2. data type – o tipo de dados do parâmetro. Pode assumir um dos valores a seguir.
   • text
   • number
   • date
   • time
   • boolean
   • array_checkbox
   • array_radio
3. prompt_msg – a mensagem de prompt para o parâmetro.
4. options – as opções de um parâmetro tipo matriz como lista. Cada opção é um mapa que tem as chaves "id" e "label".
5. input_mode – o modo de entrada de um parâmetro tipo matriz. O valor pode ser TEXTUAL ou VISUAL.
   -mandatory- essas chaves devem estar presente no mapa do parâmetro.
6. assign (opcional) – o valor desta chave deve ser um mapa. Esta chave é usada para alterar os valores para qualquer um dos argumentos de entrada mutáveis da função. Todos os parâmetros estáticos e o argumento definido pelo sistema “cache” são mutáveis.

Definir a função do manipulador de contexto (opcional)

A função do manipulador de contexto é usada para controlar o fluxo da conversa de uma ação. Você pode alterar a ordem em que os parâmetros são solicitados aos usuários no tempo de execução. Você também pode ignorar alguns parâmetros, fazer validações personalizadas dos valores dos parâmetros e solicitar uma confirmação antes da execução da ação no tempo de execução.

Observe que a função do manipulador de contexto pode substituir a ordem em que os parâmetros estáticos são definidos. Se a função do manipulador de contexto estiver ativada, o Zia solicitará os parâmetros na ordem conforme determinado pela função do manipulador de contexto, e não pela ordem que você declarou ao definir os parâmetros.

Ponto de chamada

Após o Zia detectar a ação da entrada do usuário, os possíveis valores de parâmetros estáticos que estão presentes na entrada do usuário serão detectados. Em seguida, o Zia solicitará o primeiro parâmetro estático ausente ao usuário. Quando um usuário responde à solicitação de parâmetro, o Zia chamará a função do manipulador de contexto. Dessa forma, a função do manipulador de contexto é chamada para cada parâmetro que é solicitado na conversa. Isso se aplica aos parâmetros estáticos e dinâmicos. Se uma ação não tiver parâmetros, a função do manipulador de contexto será executada uma vez antes da função de execução.

Argumentos de entrada

Além dos argumentos de entrada definidos pelo sistema, os seguintes argumentos de entrada também estão disponíveis para a função do manipulador de contexto.

Valor de retorno

A função do carregador de parâmetros deve retornar um mapa no formato a seguir.

todo (obrigatório) – usado para indicar ao Zia o que fazer depois de concluir a função do manipulador de contexto. Esta chave deve estar presente na resposta da função do manipulador de contexto. Pode assumir um dos valores a seguir.

1. prompt – instrui o Zia a solicitar um parâmetro do usuário.
2. confirm – instrui o Zia a pedir uma confirmação final para a chamada da função de execução da ação.
3. execute – instrui o Zia a chamar a função de execução da ação.

prompt (aplicável somente se "todo" = "prompt") – contém um mapa que especifica que parâmetro deve ser solicitado ao usuário. Se esta chave não for fornecida, mesmo que "todo" esteja definido como "prompt", o Zia solicitará o próximo parâmetro seguindo a ordem da definição dos parâmetros. Portanto, esta chave pode ser ignorada se tivermos que usar a ordem padrão da definição dos parâmetros. O valor do mapa pode conter as seguintes chaves.

1. param_name * – o nome do parâmetro a ser solicitado. O nome do parâmetro deve ser um dos parâmetros estáticos ou dinâmicos declarados.
2. options – opções a serem exibidas como sugestões para o parâmetro. Aplica-se somente aos parâmetros tipo matriz.
3. msg – usada para substituir momentaneamente a mensagem de prompt padrão do parâmetro.

confirm (obrigatório somente se "todo" = "confirm") – contém um mapa que especifica a mensagem de confirmação para a execução da ação que deve ser solicitada ao usuário. O valor do mapa pode conter somente a seguinte chave.

1. message – a mensagem de confirmação que deve ser solicitada ao usuário.

assign – a valor dessa chave deve ser um mapa. Esta chave é usada para alterar os valores para qualquer um dos argumentos de entrada mutáveis da função. Todos os parâmetros estáticos e o argumento definido pelo sistema “cache” são mutáveis.

Função de execução

A função de execução é o ponto de extremidade para a execução de uma ação. Ela define o preenchimento de uma ação. É a execução real da ação e fornece uma mensagem final de sucesso (ou falha) ao usuário como resultado da conclusão de uma ação. A resposta ao usuário pode ser um texto sem formatação ou uma coleção de cartões (elementos visuais). A resposta ao usuário pode ser um texto sem formatação ou uma coleção de cartões (elementos visuais).

Ponto de chamada

A função de execução é chamada no ponto de extremidade de uma ação. Por padrão, o ponto de extremidade de uma ação vem depois que todos os valores dos parâmetros são solicitados e preenchidos com os valores corretos. Como alternativa, o ponto de extremidade também pode ser definido a partir da função do manipulador de contexto (“todo” : “execute”). Após a função de execução ser chamada, a ação é concluída e qualquer outra conversa do usuário será considerada como uma nova ação.

Argumentos de entrada

Além dos argumentos de entrada definidos pelo sistema, os seguintes argumentos de entrada também estão disponíveis para a função de execução.

Valor de retorno

A função de execução deve retornar um mapa no formato a seguir.

message (obrigatório) – para fornecer uma mensagem de texto sem formatação como uma resposta ao usuário. O texto sem formatação será processado por meio de voz ou como texto, dependendo do meio de comunicação.

card (opcional) – para fornecer uma mensagem visualmente formatada como uma resposta ao usuário. Um cartão é uma coleção de elementos visuais, como tabela, imagem etc. O cartão será renderizado na tela para mídias de chamada e chat. O valor desta chave é uma lista de objetos de mapa. Cada objeto de mapa representa um elemento de UI no cartão. Um único cartão pode conter mais de um elemento do mesmo tipo. Todos os elementos contidos no cartão serão exibidos um abaixo do outro na mensagem de resposta.

Veja a seguir a lista de elementos de UI que são suportados pelo Zia:

Publicar uma ação

As ações personalizadas são escritas no ambiente do Sandbox e não estarão disponíveis para o restante dos usuários da organização. Para disponibilizar as ações personalizadas para todos, os dados da ação devem ser atualizados para o Zia.

Para atualizar todas as ações escritas para o Zoho CRM, clique no botão “Atualizar” na guia do Zoho CRM. Observe que o botão de atualização só estará visível caso haja atualizações disponíveis em quaisquer ações personalizadas que você tenha escrito.

Permissões no Zia

O administrador do Zia pode fornecer controles de acesso aos usuários com base em suas funções e nível de hierarquia dentro da organização. A lista abaixo exibe os níveis de permissão para cada função.

1. Usuário — só pode usar chat ou conversar com o Zia.
2. Desenvolvedor — pode escrever habilidades para o Zia.
3. Gerente — pode atualizar as habilidades para o Zia para disponibilizá-lo para todos os usuários.
4. Administrador — pode gerenciar outros usuários.
5. Superadministrador — é o administrador principal.

A função mínima exigida para acessar o console do desenvolvedor é Desenvolvedor. Os usuários da função Administrador têm o privilégio de alterar as funções de outros usuários. A opção de alterar a função de qualquer usuário está disponível na guia Configurações. Em Configurações, clique no usuário cuja função deve ser alterada. Clique na opção "Alterar Função", escolha uma nova função para o usuário no menu suspenso e clique em "Atualizar". O usuário será movido para a nova função.