Abrir caixas de diálogo interativas

Esta página descreve como um app do Google Chat pode abrir caixas de diálogo para mostrar interfaces do usuário (IUs) e responder a usuários.

No Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Para saber mais, consulte a Visão geral do Extend Google Chat.

As caixas de diálogo são interfaces com base em cards que são abertas em um espaço ou mensagem do Chat. A caixa de diálogo e o conteúdo dela só ficam visíveis para o usuário que a abriu.

Os apps de chat podem usar caixas de diálogo para solicitar e coletar informações dos usuários do Chat, incluindo formulários de várias etapas. Para mais detalhes sobre como criar entradas de formulário, consulte Coletar e processar informações dos usuários.

Pré-requisitos

Node.js

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do HTTP.

Apps Script

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do Apps Script.

Abrir uma caixa de diálogo

Uma caixa de diálogo com vários widgets diferentes.
Figura 1: um app de chat que abre uma caixa de diálogo para coletar informações de contato.

Esta seção explica como responder e configurar uma caixa de diálogo:

  1. Acionar a solicitação de caixa de diálogo de uma interação do usuário.
  2. Processe a solicitação retornando e abrindo uma caixa de diálogo.
  3. Depois que os usuários enviarem informações, processe o envio fechando a caixa de diálogo ou retornando outra caixa de diálogo.

Acionar uma solicitação de caixa de diálogo

Um app de chat só pode abrir caixas de diálogo para responder a uma interação do usuário, como um comando de barra ou um clique em um botão de uma mensagem em um card.

Para responder aos usuários com uma caixa de diálogo, um app de chat precisa criar uma interação que aciona a solicitação de caixa de diálogo, como esta:

  • Responder a um comando de barra. Para acionar a solicitação de um comando de barra, marque a caixa de seleção Abre uma caixa de diálogo ao configurar o comando.
  • Responder a um clique em um botão em uma mensagem, como parte de um card ou na parte de baixo da mensagem. Para acionar a solicitação de um botão em uma mensagem, configure a ação onClick do botão definindo o interaction como OPEN_DIALOG.
Botão que aciona uma caixa de diálogo
Figura 2: um app de chat envia uma mensagem que solicita que os usuários usem o comando de barra /addContact.
A mensagem também inclui um botão que os usuários podem clicar para acionar o comando.

O JSON a seguir mostra como acionar uma solicitação de caixa de diálogo de um botão em uma mensagem de cartão. Para abrir a caixa de diálogo, defina o campo onClick.action.interaction do botão como OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

Em que BUTTON_TEXT é o texto que aparece no botão e ACTION_FUNCTION é a função executada para abrir a caixa de diálogo inicial.

Abrir a caixa de diálogo inicial

Quando um usuário aciona uma solicitação de caixa de diálogo, o app de chat recebe um objeto de evento com um payload que especifica que um objeto dialogEventType é REQUEST_DIALOG.

Para abrir uma caixa de diálogo, o app de chat pode responder à solicitação retornando um objeto RenderActions com a navegação pushCard para mostrar um card. O card precisa conter elementos da interface do usuário (IU), incluindo um ou mais sections[] de widgets. Para coletar informações dos usuários, você pode especificar widgets de entrada de formulário e um widget de botão. Para saber mais sobre como projetar entradas de formulário, consulte Coletar e processar informações dos usuários.

O JSON a seguir mostra como um app de chat retorna uma resposta que abre uma caixa de diálogo:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

Em que BUTTON_TEXT é o texto que aparece no botão (como Next ou Submit), WIDGETS representa um ou mais widgets de entrada de formulário e ACTION_FUNCTION é a função de callback da ação que é executada quando os usuários clicam em um botão.

Processar o envio da caixa de diálogo

Quando os usuários clicam em um botão que envia uma caixa de diálogo, o app de chat recebe um objeto de evento com um objeto ButtonClickedPayload. No payload, o dialogEventType é definido como SUBMIT_DIALOG.

O app de chat precisa processar o objeto de evento fazendo uma das seguintes ações:

Opcional: retornar outra caixa de diálogo

Depois que os usuários enviam a caixa de diálogo inicial, os apps de chat podem retornar uma ou mais caixas de diálogo adicionais para ajudar os usuários a revisar informações antes de enviar, preencher formulários de várias etapas ou preencher o conteúdo do formulário de forma dinâmica.

Para processar os dados inseridos pelos usuários, o app Chat processa os dados no objeto commonEventObject.formInputs do evento. Para saber mais sobre como recuperar valores de widgets de entrada, consulte Coletar e processar informações dos usuários.

Para acompanhar os dados que os usuários inserem na caixa de diálogo inicial, adicione parâmetros ao botão que abre a próxima caixa de diálogo. Para mais detalhes, consulte Transferir dados para outro cartão.

Neste exemplo, um app de chat abre uma caixa de diálogo inicial que leva a uma segunda caixa de diálogo para confirmação antes do envio:

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

Este exemplo envia uma mensagem de cartão retornando o card JSON. Também é possível usar o serviço de cards do Apps Script. 

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

Onde WIDGETS representa qualquer outro widget de entrada de formulário.

Fechar a caixa de diálogo

Quando os usuários clicam em um botão de envio em uma caixa de diálogo, o app de chat executa a ação associada e fornece o objeto de evento com buttonClickedPayload definido para o seguinte:

  • isDialogEvent é true.
  • dialogEventType é SUBMIT_DIALOG.

O app de chat precisa retornar um objeto RenderActions com EndNavigation definido como CLOSE_DIALOG.

Opcional: mostrar uma notificação

Ao fechar a caixa de diálogo, você também pode mostrar uma notificação de texto.

Para mostrar uma notificação, retorne o objeto RenderActions com o campo notification definido.

O exemplo a seguir verifica se os parâmetros são válidos e fecha a caixa de diálogo com uma notificação de texto, dependendo do resultado:

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Para mais detalhes sobre a transmissão de parâmetros entre caixas de diálogo, consulte Transferir dados para outro card.

Opcional: enviar uma mensagem de confirmação

Ao fechar a caixa de diálogo, você também pode enviar uma nova mensagem ou atualizar uma existente.

Para enviar uma nova mensagem, retorne um objeto DataActions com o campo CreateMessageAction definido com a nova mensagem. Por exemplo, para fechar a caixa de diálogo e enviar uma mensagem de texto, retorne o seguinte:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Para atualizar uma mensagem depois que o usuário envia uma caixa de diálogo, retorne um objeto DataActions que contenha uma das seguintes ações:

Resolver problemas

Quando um app do Google Chat ou um card retorna um erro, a interface do Chat mostra uma mensagem informando que "Ocorreu um erro". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não mostra nenhuma mensagem de erro, mas o app ou o card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro possa não aparecer na interface do Chat, mensagens de erro descritivas e dados de registro estão disponíveis para ajudar a corrigir erros quando o registro de erros para apps de chat estiver ativado. Para saber como visualizar, depurar e corrigir erros, consulte Resolver e corrigir erros do Google Chat.