Processar as informações inseridas pelos usuários

Este guia descreve como receber e ler as informações que os usuários inserem em mensagens de cards e caixas de diálogo. Os usuários podem inserir dados que os apps de chat recebem, leem e respondem. Os widgets que permitem aos usuários inserir informações incluem:

  • TextInput para entrada de texto de formato livre que também oferece suporte a 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 em apps de chat:

Abra o Criador de cards.

O recebimento de dados de usuários permite que os apps de chat façam o seguinte:

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

Como funciona o recebimento de dados

Um app do Chat apresenta informações ao usuário em uma caixa de diálogo ou uma mensagem de card. Neste exemplo, uma caixa de diálogo solicita que o usuário insira informações sobre um contato usando os widgets TextInput e SelectionInput:

Uma caixa de diálogo com uma variedade de widgets diferentes.

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

Para coletar dados sobre o que os usuários inseriram, use o campo 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. Por exemplo, Event.common.formInputs.stringInputs representa entradas de string.

O 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 um widget TextInput.

Receber dados de cards

Quando um usuário insere dados em uma mensagem de card, seu app do Chat recebe um evento de interação com o app do Chat, 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, como este exemplo:

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 a dados coletados em uma mensagem ou caixa de diálogo no card

Depois de receber os dados de uma mensagem em card ou de caixa de diálogo, o app do Chat responde confirmando o recebimento ou retornando um erro. Ambos são feitos com ActionResponse:

  • Para confirmar o recebimento, responda com um parâmetro ActionResponse que tenha "actionStatus": "OK".
  • Para retornar um erro, responda com um parâmetro ActionResponse que tenha "actionStatus": "ERROR MESSAGE".

Exemplo

O exemplo a seguir verifica se há um valor name. Se ausente, o app retornará um erro. Se estiver presente, o app confirmará o recebimento dos dados do formulário e fechará 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

Neste exemplo, uma mensagem de cartão é enviada 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 do Google Chat retorna um erro, a interface do Chat mostra a mensagem "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 card do Chat produz um resultado inesperado. Por exemplo, uma mensagem de card pode não aparecer.

Embora uma mensagem de erro não apareça 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 dos apps do Chat está ativado. Se precisar de ajuda para visualizar, depurar e corrigir erros, consulte Resolver problemas e corrigir erros do Google Chat.