Package: assistant-fulfillment-helper
Assistant Fulfillment HelperEsta biblioteta tem como objetivo facilitar a criação dewebhookspara os nós de intenção daAssistente TOTVS. Com poucas linhas de código, é possivel criar uma regra de negócio customizada em sua própria estrutura de servidor.Pré-requisitos:>= Python 3.7Por onde começar?Crie um projeto novo e instale o módulo usando PyPI:pipinstallassistant-fulfillment-helperImporte e instancie a classeFulfillmentHelperpara poder definir sua própria regra de negócio.fromassistant_fulfillment_helperimportFulfillmentHelperfh=FulfillmentHelper()fh.start()# Inicia um servidor localO código acima irá instanciar o módulo e servirá um Webhook pronto para receber as requisições dos seus nós de intenção da Assistente. Para checar se está tudo certo, abra seu navegador e acessehttp://127.0.0.1:5052(endereço padrão).O endereço (path) raíz possui dois roteamentos:GET: Trás uma mensagem de sucesso comhttp response 200, e pode ser utilizada comohealth check.POST: Iniciará o processamento dasintenções definidasna sua aplicação. É a chamada que o servidor espera receber da Assistente.Definindo uma IntençãoPara definir uma intenção, basta adicionar o decoratorintent()no método que deverá ser o callback para aquela intenção. Uma intenção deverá estar vinculada à um Webhook, o qual é definido no momento da criação do callback.Por exemplo:fromassistant_fulfillment_helperimportFulfillmentHelperfh=FulfillmentHelper()@fh.intent(webhook='pedidos',node='Novo pedido',token='{token}')defcb_novo_pedido(args):""" Sua regra de negócio aqui """passNesse exemplo, o "Novo pedido" no UI da Assistente deverá estar definido nas configurações do Fullfilment (webhook):http://meu-servidor.com.br/pedidos.intent()O decoratorintent()definirá o callback pra cada intenção em uma lista de intenções dentro de um contexto de webhook. Será efetuado uma chamada para o método declarado como callback toda a vez que o servidor receber uma chamada vinda de um nó da Assistente para a intenção definida.
É possível registrar quantos callback de intenções e webhooks forem necessários, mas apenas um callback é permitido para cada intenção (nó).Parâmetros:ParâmetroObrigatório?TipoDescriçãowebhookSimStrPath do webhook, para o qual a Assistant requisitará nesse nótokenSimStrToken disponibilizado pela Assistente na configuração do Nó de IntençãonodeSimStrNome do Nó de Intenção cadastrado na Assistentefallback_messageNãoStrMensagem padrão de retorno em caso de falha na execução do callbackCriando um callbackNa chamada do callback, será passado uma variável do tipoDictcom alguns argumentos que poderão ser utilizados na regra de negócio como quiser.
Exemplo de um método para callback de um Nó de Intenção:fromassistant_fulfillment_helperimportFulfillmentHelper,FulfillmentHelperResponsefh=FulfillmentHelper()@fh.intent(webhook='pedidos',node='Novo pedido',token='{token}')defcb_novo_pedido(params):session=params.get('sessionId')message=f"Olá Usuário, nosso id de sessão é:{session}"returnFulfillmentHelperResponse(message=message)Os parametros passados na chamada do callback são:ParâmetroTipoDescriçãointent_nameStrNome do nó sendo processadoparametersDictTodos os parametros desse contexto de conversasessionLogListLista de ID de sessões até esse ponto da conversanamedQueriesDictResultados da Named Query (se houver)queryStrQuery executada (se houver)languageStrIdioma da conversacarolOrganizationStrNome da OrganizaçãocarolEnvironmentStrNome do AmbientecarolOrganizationIdStrId da OrganizaçãocarolEnvironmentIdStrId do AmbientesessionIdStrId da sessão da conversa atualisProductionBoolInforma se a convesa está acontecendo em Produção ou DesenvolvimentochannelNameStrNome do canal por onde a mensagem chegouRetorno do CallbackO metodo de callback deve retornar uma classe do tipoFulfillmentHelperResponse, como noexemplo acima. Essa classe possui os seguintes atributos para retorno:ParâmetroObrigatório?TipoDescriçãomessageSimStrMensagem que será retornada na conversashort_messageNãoStrMensagem curta de retornojump_toNãoStrNome do nó para o qual a conversa será direcionadaoptionsNãoList[Str]Lista de opções pré-definidas que aparecerão como botões na respostalogoutNãoBoolDestrói a sessão de usuário na conversa(default: False)parametersNãoDictParametros que serão adicionados no contexto da conversaExemplo de uso:@fh.intent(webhook='boas-vindas',node='Boas vindas',token='{token}')defcallback_boas_vindas(params):message=f"Olá, o que deseja fazer agora?"returnFulfillmentHelperResponse(message=message,short_message="Boas vindas",jump_to="Pedidos",options=["Criar Pedido","Consultar Pedido","Cancelar Pedido"],logout=False,parameters={'onboarding':True})Falha do CallbackSe por algum motivo houver uma excessão na execução do callback, o servidor responderá uma mensagem de fallback padrão para a assistente ("Desculpe, não consegui processar seu pedido no momento."). Essa mensagem pode ser alterada na definição da intenção.Por exemplo:@fh.intent(webhook='login',node='Login',token='{token}',fallback_message='Estamos passando por alguns problemas.')defcallback_login(params):resposta='lorem'*1/params# raises a TypeError ExceptionreturnFulfillmentHelperResponse(message=resposta)Na execução desse callback, a excessãoTypeErrorserá capturada pelo servidor. O qual, por sua vez, retornará para o usuário na Assistente a mensagem de fallback definida para esse callback e o detalhes do erro será disponibilizado no console do servidor.Iniciando um servidor localExistem diferentes formas de executar o servidor webhook. A biblioteca disponibiliza o métodostart()para rodar o servidor diretamente pelo código e o métodoget_app_context()para poder executar externamente por outra biblioteca (ex: gunicorn) e executar testes.get_app_context()O métodoget_app_context()retornará o contexto do servidor em uma variável, o que é util para executar testes e rodar a aplicação utilizando bibliotecas externas e deixar pronto para receber requisições como um Webhook.Por exemplo:fh=FulfillmentHelper()application=fh.get_app_context()Agora a aplicação pode ser executada com o comando:gunicornmy_appNOTA: nesse exemplo a variávelapplicationpoderá ser utilizada por bibliotecas de testes também.start()O métodostart()é responsável por iniciar um servidor e deixar pronto para receber requisições como um Webhook. Por esse método, o servidor pode ser configurado passando algumas propriedades no momento da chamada.Por exemplo:fh=FulfillmentHelper()fh.start(debug=True)As configurações customizáveis para o servidor local são:ParâmetroObrigatório?TipoDefaultDescriçãodebugNãoBoolFalseO Debug ativo habilita verbosidade e reinicia o servidor em cada alteração de códigohostNãoStr0.0.0.0Nome ou IP do host localportNãoInt5052Porta do host localExceçõesOs possíveis erros são tratados pelas exceções da biblioteca. Aqui está a lista das exceções existentes:ExceçãoProblemaDuplicatedIntentNodeException()Foi tentado adicionar dois métodos de callback para o mesmo Nó de IntençãoIntentCallbackNotFoundException()O WebHook recebeu uma chamada para um Nó de Intenção indefinidoIntentResponseInstanceException()O Callback invocado não retornou a classe de resposta esperada (FulfillmentHelperResponse())InvalidWebhookTokenException()O WebHook token utilizado na chamada é diferente do token informado no registro do nóWebhookNotFoundException()O servidor recebeu uma requisição para um webhook indefinidoExecutando em ambiente de DEV:Dica: Ao invocar o metodostart(),habilite o Debugpara um desenvolvimento mais rápido.Ao iniciar o webhook local, será necessario disponibilizar a aplicação para fora da sua rede. Para isso recomendamos a utilização de algum software de proxy local, como, por exemplo, ongrok. Após instalação, execute o comando abaixo em seu terminal para obter a URL pública da sua aplicação. Essa URL poderá ser adicionada como WebHook nas configurações dos seus nós na Assistente para um teste local.ngrokhttphttp://127.0.0.1:5052NOTA: Informe o host e porta definida na inicialiazação do servidor WebHook.Executando com GunicornÉ possivel executar o servidor do webhook utilizandoGunicorn, uma vez que o contexto da aplicação esteja acessível no arquivo de chamada raíz da sua aplicação. Há duas formas pra obter o contexto da aplicação no seu arquivo.Utilizando o métodoget_app_context():fromassistant_fulfillment_helperimportFulfillmentHelperfh=FulfillmentHelper()...application=fh.get_app_context()Importando aapplication(contexto da aplicação) diretamente:fromassistant_fulfillment_helperimportFulfillmentHelper,applicationfh=FulfillmentHelper()...Agora é só iniciar o servidor comGunicorn:gunicorn -w 4 mainNOTA:maindeve ser o nome do arquivo raíz da sua aplicação, o qual possui o contexto do app acessível (application).LicençaMIT (LICENSE)