Iniciando a Configuração de Menus e Serviços

Nesta seção, está o passo a passo para disponibilizar os atendimentos digitais, iniciando pelo menu de serviços, até a codificação dos processos. A especificação completa com todos os tipos de dados e possibilidades está na seção Especificação detalhada.

Criando Menus de Atendimento

Cada município possuirá um único menu principal que pode ter um ou N subníveis. Os menus também são críticas, com uma especificação básica, contendo a mensagem que será exibida para o usuário (prompt), bem como as opções de categorias (de outros menus ou de atendimentos).

Exemplo de Código Fonte: Crítica do Menu Principal

return [
  prompt: 'Selecione uma de nossas áreas para solicitar um atendimento:',
  opcoes: [
    [
      valor: 'tag_alvaras_licencas',
      texto: 'Alvarás e Licenças',
      temSubNivel: true
    ],
    [
      valor: 'tag_educacao',
      texto: 'Educação'
    ]
]

Tabela 1: Atributos de Menu

Atributo	Tipo	Descrição	Obrigatório	Valor padrão
prompt	String	Texto exibido antes de listar as opções do menu	Não	Escolha qual a área de serviços você deseja um atendimento em Nome Município - UF
opcoes	Mapa (Item de Menu)	Lista das dos itens de menu	Sim	-

Tabela 2: Atributos de um Item de Menu (Opção)

Atributo	Tipo	Descrição	Obrigatório	Valor padrão
valor	String	Tag/identificador que aponta para uma categoria de serviços ou um submenu	Sim	-
texto	String	Texto descritivo da categoria do menu	Sim	-
temSubNivel	boolean	Indica se aponta para outro menu ou para uma lista de serviços que contenham o valor	Não	false

IMPORTANTE!

O que diferencia a crítica do menu principal das críticas dos demais menus?

• O menu principal é uma crítica cadastrada na BETH com a natureza “Categoria de Serviço” e o evento “Conversação”;
• A diferenciação entre o menu principal (ponto de entrada) e os demais menus (se existirem) é que o menu principal não pode conter nenhuma tag definida;
• Consequentemente, só pode existir uma crítica da natureza “Categoria de Serviço” sem nenhuma tag.

Conferindo a Configuração Pela Tela Portal do Desenvolvedor

O estado da configuração e alguns indicadores podem ser acessados pela tela Portal do Desenvolvedor => Insights. Após criar/alterar as críticas de menu, caso a configuração tenha sido feita com sucesso, você verá a mensagem “menu configurado com sucesso”, semelhante à imagem abaixo.

Imagem de uma configuração com o menu principal configurado e ao menos um atendimento, indica que a Beth já está pronta para uso.

Navegação entre os menus

Quando o usuário seleciona um item do menu, existem dois caminhos possíveis:

• Opção de menu selecionada tem subnível:
  • É carregado o menu que contenha a tag selecionada. As opções deste outro nível serão listadas, e o fluxo continua, até que a opção selecionada pelo usuário não tenha subnível.
• Opção de menu não tem subnível:
  • São listadas as críticas da natureza “Atendimento” que possuam entre as tags a tag da categoria selecionada anteriormente.

Representação visual dos menus de atendimento

A série de imagens abaixo ilustra a utilização de um menu com 2 níveis até a chegada da lista de serviços. No exemplo, é possível visualizar a experiência se o usuário escolher a opção 1 do menu principal (figura 1), na sequência a opção 1 do menu Tipos de Alvarás (figura 2). Por fim, a figura 3 ilustra o menu de serviços que possuem a tag tag_alvaras_funcionamento.

Figura 1: Crítica do Menu Principal

Figura 2: Crítica do Submenu de Tipos de Alvarás

Figura 3: Menu de Serviços (gerado dinamicamente pelo filtro da tag)

Mais detalhes sobre os menus

• Não é obrigatório que existam submenus:
  • Pode existir uma única crítica que representa o menu do município, onde as opções não possuem subnível;
  • Quando uma categoria for selecionada, serão listados os processos que contenham a tag da categoria escolhida anteriormente.
• As opções de menu podem ser selecionadas pelo código sequência dinâmico da opção ou pelo literal, exemplo: digitando “1” ou “um”;
• Algumas opções qualitativas, como sim ou não, também podem ser selecionadas pelo texto “sim”, “não”, ou ainda por algumas variações da mesma intenção, como “isso”, “pode”, “correto”, entre outras opções para representar a opção “sim”.
  • Importante: Para as versões futuras da Beth, está prevista a possibilidade de seleção de opções por texto da própria opção.
• O usuário sempre poderá voltar entre as categorias menus (digitando voltar ou digitando v, voltar, etc.);
• A opção de encerrar o atendimento sempre está disponível pelo menu (digitando x ou sair, encerrar, etc.);
• Em alguns canais, quando o usuário estiver no menu principal e escolher a opção voltar, ele irá para seleção de município.
  • Importante: O usuário não poderá trocar o município de atendimento caso tenha iniciado o atendimento pelo site de uma prefeitura específica. Neste caso, a opção voltar não estará no menu e a BETH irá ignorar caso ele manifeste a intenção de voltar digitando algum texto.

Dicas gerais sobre a codificação de menus

• Não é necessário colocar números como prefixo das críticas de atendimento e opções de menu. A sequência de opções é gerada dinamicamente;
• Tente padronizar a nomenclatura das críticas de menu, de forma que seja fácil identificar os níveis e categorias:
  • Exemplo de títulos de críticas de menu:
    • [ Menu ] Principal
    • [ Menu ] Tributos
    • [ Menu ] Educação
    • [ Menu ] Educação - Emissão de Documentos
• Procure utilizar tags significativas:
  • Exemplo do que fazer:
    • tag_educacao
    • tag_educacao_emissao_documentos
  • Exemplo do que não fazer:
    • tag_ed
    • tag_ed_emidoc
• Os menus permitem uma estrutura muito flexível, de forma que podem ser criados menus temporários ou específicos em alguns casos. Por exemplo, para os processos mais utilizados ou para uma ação que o município esteja fazendo.

Criando Críticas de Atendimento

As críticas de atendimento definem exatamente o que acontecerá durante a conversação do usuário após a escolha do atendimento. Dentro da crítica, é possível definir parâmetros adicionais para solicitar ao usuário e tomar vários caminhos, como por exemplo: encerrar o atendimento com uma mensagem, retornar uma ou mais extensões, ou ainda, retornar somente uma extensão de acordo com algum critério.

Dentro da crítica de atendimento, estão disponíveis fontes de dados e outras API’s de scripts, para que sejam acessadas informações externas (ver lista completa de API’s disponíveis na seção “Especificação Detalhada”).

Pelo fato do atendimento ser “codificado”, existem várias formas de se chegar no mesmo resultado. A especificação de um atendimento permite que seja utilizada uma ou mais iterações na execução da crítica. A principal diferença entre estes formatos é a possibilidade de resolver o atendimento em uma única iteração, ou ainda, encerrar de forma precoce com base em uma validação, no lugar de solicitar várias informações e só então retornar algo para o usuário.

O atendimento mais simples possível

Talvez o exemplo abaixo não seja tão realista, mas ajuda a visualizar as possibilidades ao construir um atendimento. Imagine que você tenha necessidade de desabilitar um atendimento temporariamente e dar uma mensagem padrão para o cidadão. Bastaria retornar o seguinte código no topo da crítica de atendimento:

return [
    mensagem: "Desculpe, mas o processo de consulta de débitos está indisponível até o dia 10/03/2023.",
    encerrar: true
]

O código acima, entregará a mensagem para o usuário e irá encerrar seu atendimento.

Atendimento onde o resultado depende apenas do CPF do cidadão

Imagine um processo, como consultar dívida ativa para o contribuinte. Neste caso, podem existir 3 cenários:

1. Contribuinte não está cadastrado no município;
2. Contribuinte está cadastro e não possui débitos;
3. Contribuinte está cadastrado e possui débitos;

Código da Crítica - Depende somente do CPF do cidadão

// O CPF do usuário sempre irá existir dentro do contexto de atendimento
CPF = contexto.usuario.cpf

filtroContribuinte = "cpfCnpj = '"+ CPF + "'";
contribuintes = Dados.tributos.v2.contribuintes.busca(criterio: filtroContribuintes, limite: 1)

idContribuinte = null
percorrer (contribuintes) { itemContribuintes ->
   idContribuinte = itemContribuintes.id
}

// Cenário 1: Não está cadastrado no município
if (idContribuinte == null) {
    return [
      encerrar: true,
      mensagem: "Não foi encontrado um contribuinte para o seu CPF. Entre em contato com o município para verificar alguma pendência no cadastro."
    ]
}

// Busca possível dívida ativa para o contribuinte
filtroDivida = "idContribuinte = "+ idContribuinte;
resumoDivida = Dados.tributos.v2.dividaAtivaResumo.busca(criterio: filtroDivida, limite: 1)

dividaRegistro = null
percorrer (resumoDivida) { item ->
   dividaRegistro = item
}

// Cenário 2: Está cadastrado no município e não possui dívidas
if (dividaRegistro == null) {
    return [
      encerrar: true,
      mensagem: "Ótima notícia " + contexto.usuario.nome + ", não consta nenhuma dívida ativa em seu nome. Mantendo seus tributos em dia, você contribui para que nossa cidade seja cada vez melhor."
    ]
}

// Cenário 3: Está cadastrado no município e possui dívidas
return [
    encerrar: true,
    mensagem: contexto.usuario.nome + ", existem débitos em seu nome referente ao tributo " + dividaRegistro.nomeTributo + ", no valor de R$ " + dividaRegistro.valorDivida + ". Você pode realizar a quitação aqui mesmo, iniciando um atendimento: Tributos -> Emitir Guia para Pagamento / Refiz."
]

Retornando links Experimental

Alguns atendimentos, necessitam que seja entregue um link clicável para o usuário. Para garantir que o link seja clicável ou possa ser copiado de forma simples, é possível encerrar o atendimento (quando não é utilizada nenhuma extensão), enviando também um link para o usuário em uma mensagem separada.

Encerramento com mensagem e link:

Imagem que demonstra a saída de um dos exemplos a seguir.

Exemplo: Código abaixo entrega a mensagem e o link para o usuário, encerrando o atendimento e demonstrando a pesquisa de satisfação.

return [
  encerrar: true,
  mensagem: "🦟 Para mais informações sobre a vistoria de combate a dengue *acesse o link*:",
  link: "https://sp156.prefeitura.sp.gov.br/portal/servicos/informacao?servico=810"
]

Exemplo 2: Com essa instrução, a pesquisa de satisfação é pulada e o atendimento é encerrado diretamente.

return [
  encerrar: true,
  mensagem: "🦟 Para mais informações sobre a vistoria de combate a dengue *acesse o link*:",
  link: "https://sp156.prefeitura.sp.gov.br/portal/servicos/informacao?servico=810",
  pularAvaliacao: true
]

Exemplo 3: No exemplo abaixo, a pesquisa de satisfação é pulada e o usuário volta para o menu.

return [
  encerrar: true,
  mensagem: "🦟 Para mais informações sobre a vistoria de combate a dengue *acesse o link*:",
  link: "https://sp156.prefeitura.sp.gov.br/portal/servicos/informacao?servico=810",
  voltarAoMenu: true,
  pularAvaliacao: true
]

Exemplo 4: No exemplo abaixo, a pesquisa de satisfação não será pulada. O usuário pode optar por responder a avaliação ou não, e na sequência, será exibido o menu de serviços.

return [
  encerrar: true,
  mensagem: "🦟 Para mais informações sobre a vistoria de combate a dengue *acesse o link*:",
  link: "https://sp156.prefeitura.sp.gov.br/portal/servicos/informacao?servico=810",
  voltarAoMenu: true
]

IMPORTANTE

Os recursos voltarAoMenu e pularAvaliacao estão disponíveis apenas para atendimentos que não utilizam extensões, ou seja, o encerramento do atendimento é uma mensagem de texto podendo ou não ter um link extra.

Estes atributos também estão em fase experimental e podem sofrer modificações.

Utilizando extensões - Versão Simplificada

Observação

Esta seção apresenta um resumo da utilização de extensões. Não se preocupe se alguns termos não estão explicados neste momento. Eles estão detalhados na seção “Especificação Detalhada -> Utilizando Extensões”.

O cenário mais comum em um atendimento será entregar para o usuário um PDF ou retorno de um script como conclusão do atendimento. Neste caso, pode ser necessário que sejam solicitadas algumas variáveis antes de executar a extensão.

Exemplo de Emissão de Holerite: Versão Simplificada

O exemplo abaixo ilustra a emissão de um holerite, dando uma lista de matrículas para seleção e solicita que o usuário digite a competência desejada. Com a finalidade de reduzir o código, as opções estão fixas, mas considere que os valores da lista de opções seriam carregados por fontes de dados na inicialização do script. Também lembre-se de que o atendimento poderia ser encerrado antes, caso não existisse nenhuma matrícula para o CPF do cidadão.

return [
  variaveis: [
    [
      nome: 'matricula',
      rotulo: 'Mátricula no seu CPF para emissão do holerite:',
      tipo: 'lista',
      opcoes: [
        [
          valor: '2022',
          texto: '2022 - DIR. ADMINISTRATIVO E FINANCEIRO - *Ativo*'
        ],
        [
          valor: '2014',
          texto: '2014 - DIR. LIC. E FISCAL. AMBIENTAL - *Inativo*'
        ],
        [
          valor: 'nao_encontrei',
          texto: 'Não encontrei minha mátricula.'
        ]
      ]
    ],
    [
        nome: 'competencia',
        rotulo: 'Competência desejada. Deve estar dentro do seu período de matrícula (de *04/2022* até *atualmente*)',
        tipo: 'mes_ano',
        restricoes: [
          valorMinimo: '04/2022',
          valorMaximo: '11/2022'
        ]
    ]
  ],
  suspender:[
      condicoes: [
      [
        variavel: 'matricula',
        criterio: '=',
        valor: 'nao_encontrei',
        mensagem: 'Desculpe, mas estas são as matrículas disponíveis no seu CPF. Entre em contato com o setor pessoal da Prefeitura para que possamos verificar se existe alguma pendência.'
      ]
    ]
  ],
  encerrar: [
    tipo: 'relatorio',
    identificador: '44199abe-327e-4c64-a1af-1c0b344ced94',
    parametros: [
      cpfContribuinte: contexto.usuario.cpf
    ],
    solicitado: 'Ok, já estou emitindo seu holerite.',
    concluido: 'Aqui está o holerite da competência selecionada.'
  ]
]

Atributos do Retorno da Crítica de Atendimento

Atributo	Tipo	Descrição
mensagem	String ou Mensagem multicanal (Ver na Especificação de Mensagens Multicanal)	Mensagem que será entregue para o usuário. Pode ser a mensagem de início do atendimento (quando existem variáveis para solicitar) ou pode ser a mensagem que encerra o atendimento. - Obrigatória caso o atributo encerrar seja definido como true; - No caso de solicitar variáveis, caso não seja informada, a mensagem padrão será: “Por favor, forneça a(s) informação(ões) para realizar o seu atendimento.”
encerrar	Boolean ou Mapa do tipo Encerrar ou Lista de Mapa do tipo Encerrar	Especifica como será realizado o encerramento do atendimento. Boolean (padrão false): Serão solicitadas as variáveis e após o preenchimento, a crítica será executada novamente. Boolean (true): Entende-se que o atendimento será encerrado neste retorno. Neste caso, é obrigatório que seja definido o atributo mensagem com a mensagem finalizadora. Mapa do tipo Encerrar: Entende-se que o encerramento do atendimento se dará pela extensão informada neste mapa ou o atendimento será encerrado por um dos critérios dentro do atributo suspender (veja mais detalhes na especificação do Mapa do tipo Encerrar). Lista de Mapas tipo Encerrar: O comportamento é semelhante ao definir um único Mapa de Encerramento. A diferença é que como resultado podem ser executadas de 1 à 5 extensões. É obrigatório que ao menos uma extensão seja executada ou que o atendimento seja encerrado previamente pelo atributo suspender (veja mais detalhes na especificação do Mapa do tipo Encerrar).