Processar as informações inseridas pelos usuários

Este guia descreve como receber e ler as informações que os usuários inserem mensagens do card e caixas de diálogo. Os usuários podem inserir dados que os apps do Chat recebem, leem e respondem Entre os widgets que permitem aos usuários inserir informações estão:

  • TextInput para entrada de texto em formato livre que também aceita sugestões.
  • SelectionInput para itens de lista e menus, como caixas de seleção, botões de opção e menus suspensos.
  • DateTimePicker para entradas de data e hora.

Use o Card Builder para criar e visualizar mensagens de cards JSON para apps do Chat:

Abrir o Card Builder

Ao receber entradas de dados dos usuários, os apps do Chat podem fazer coisas como: o seguinte:

  • Atualizar casos de atendimento ao cliente.
  • Criar ordens de serviço.
  • Autentique-se com serviços da Web.

Pré-requisitos

Node.js

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.

Apps Script

Um app do Google Chat com recursos interativos ativados. Para criar um interativo com o app Chat no Apps Script, conclua este guia de início rápido.

Python

Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.

Como funciona o recebimento de dados

Um app de chat apresenta informações para o usuário como caixa de diálogo ou mensagem do card. Neste exemplo, uma caixa de diálogo solicita que o usuário digite informações sobre um contato usando o TextInput e SelectionInput widgets:

Uma caixa de diálogo com vários widgets diferentes.

Ao terminar, o app do Chat recebe os dados que os usuários digitam na caixa de diálogo no formato JSON e um evento de interação em que:

Para obter dados sobre o que os usuários inseriram, use o método Event.common.formInputs no payload do evento. O campo formInputs é um mapa em que as chaves são IDs de string atribuídos a cada widget e os valores representam a entrada do usuário para cada widget. Objetos diferentes representam tipos de dados de entrada diferentes. Para exemplo, Event.common.formInputs.stringInputs representam entradas de string.

Seu app pode acessar o primeiro valor inserido pelo usuário em event.common.formInputs.NAME.stringInputs.value[0], em que NAME é o campo name de uma Widget TextInput.

Receber dados de cards

Quando um usuário insere dados em uma mensagem do cartão, seu O app do Chat recebe um app do Chat de interação do cliente, como no exemplo a seguir:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Receber dados de caixas de diálogo

Quando um usuário envia dados em uma caixa de diálogo, seu app do Chat recebe outro evento de interação com o app do Chat, como exemplo a seguir:

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

Responder aos dados coletados em uma mensagem ou caixa de diálogo de cartão

Depois de receber os dados de uma mensagem de cartão ou de uma caixa de diálogo, o O app de chat responde confirmando o recebimento ou retornar um erro, e ambos são feitos retornando uma ActionResponse:

  • Para confirmar o recebimento, responda com uma ActionResponse que tem "actionStatus": "OK".
  • Para retornar um erro, responda com um ActionResponse que tem "actionStatus": "ERROR MESSAGE".

Exemplo

O exemplo a seguir verifica a presença de um valor name. Se ausente, o app retorna um erro. Se presente, o app confirma o recebimento dos dados do formulário e fecha a caixa de diálogo.

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Apps Script

Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script. 

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

Resolver problemas

Quando um app ou card retornar um erro, o A interface do chat mostra a mensagem "Algo deu errado". ou "Não foi possível processar sua solicitação". Às vezes, a interface do Chat não exibe nenhuma mensagem de erro, mas o app do Chat ou produz um resultado inesperado; por exemplo, uma mensagem de cartão 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 você a corrigir os erros quando a geração de registros de erros nos apps do Chat está ativada. Para receber ajuda com a visualização, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.