Converter um app interativo do Google Chat em um complemento do Google Workspace

Se você criou e publicou um app do Google Chat que usa eventos de interação da API Google Chat, como um baseado no início rápido do app Google Chat, esta página mostra como convertê-lo em um complemento do Google Workspace que estende o Google Chat.

Ao converter, seu app do Google Chat pode usar a estrutura de complementos do Google Workspace, abrindo novas possibilidades de integração e recursos no Google Chat e em todo o Google Workspace. Por exemplo, em vez de duas distribuições (um app do Google Chat e um complemento do Google Workspace), você pode distribuir um único complemento do Google Workspace pelo Google Workspace Marketplace que estende os apps do Chat junto com outros aplicativos host do Google Workspace, como Gmail, Agenda e Documentos.

Limitações

Antes de iniciar a conversão, revise as limitações dos complementos do Google Workspace que estendem o Google Chat para garantir que seu app do Google Chat possa ser convertido sem perder funcionalidades essenciais.

Etapa 1: copiar o código do app Google Chat atual

O processo de conversão exige mudanças no código. Para evitar afetar seu app do Google Chat ativo, crie e trabalhe em uma cópia do seu código.

Apps Script

  1. Abra seu projeto do Google Apps Script do app Google Chat.
  2. À esquerda, clique em Visão geral .
  3. À direita, clique em Fazer uma cópia .
  4. À esquerda, clique em Configurações do projeto .
  5. Em Projeto do Google Cloud, clique em Mudar projeto.
  6. Insira o mesmo número de projeto associado ao projeto do app Google Chat atual.
  7. Clique em Configurar projeto.

HTTP

Crie um fork ou uma cópia da base de código atual e implante como um novo serviço, separado do app Google Chat ativo.

Se o app estiver implantado no Google Cloud e depender de recursos vinculados ao projeto do Google Cloud (por exemplo, a identidade padrão do App Engine), o novo código precisará ser implantado em um serviço associado ao projeto do app Google Chat.

Etapa 2: modificar o código copiado

Os complementos do Google Workspace que estendem o Google Chat usam estruturas de solicitação e resposta diferentes em comparação com os apps do Google Chat criados com eventos de interação da API Chat. Você precisa atualizar seu código para usar o complemento do Google Workspace EventObject em vez da API Google Chat Event para solicitações e respostas. Use o guia de conversão de código para modificar seu código.

Etapa 3: ativar a configuração do complemento do Google Workspace para usuários de teste

Use o console do Google Cloud para configurar as opções de complementos do Google Workspace no app Google Chat:

  1. Acesse a página de configuração da API Google Chat no console do Google Cloud.

    Acessar a página de configuração da API Google Chat

  2. Em Recursos interativos, clique em Converter em complemento.

  3. Ative a opção Ativar as configurações de complementos.

  4. Na seção Visibilidade, adicione os endereços de e-mail dos usuários de teste.

  5. Se necessário, atualize as Configurações de conexão com o URL do endpoint de implantação ou o ID de implantação do Apps Script do código do app Google Chat copiado e modificado na etapa 2.

  6. Clique em Salvar e testar.

Etapa 4: testar o app convertido

Teste a funcionalidade do complemento do Google Workspace usando as contas de usuário de teste configuradas na Etapa 3. Verifique todos os recursos e interações.

Etapa 5: concluir a conversão para todos os usuários

Depois de verificar se o complemento convertido do Google Workspace funciona corretamente, disponibilize-o para todos os usuários.

  1. Acesse a página de configuração da API Google Chat no console do Google Cloud.

    Acessar a página de configuração da API Google Chat

  2. Em Recursos interativos, clique em Converter em complemento. Um painel lateral será aberto.

  3. No painel lateral, clique em Converter em complemento.

  4. Digite o ID do projeto e clique em Converter.

Seu app do Google Chat agora é um complemento do Google Workspace que estende o Google Chat.

Opcional: limpar ou liberar recursos não utilizados do Google Cloud

Opcionalmente, depois de converter seu app do Google Chat em um complemento do Google Workspace, para evitar cobranças na sua conta do Google Cloud pelos recursos usados pelo app do Google Chat que não estão mais em uso, considere desativá-los.

Guia de conversão de código

Esta seção detalha o mapeamento entre o formato de interação da API Google Chat Event e o formato do complemento do Google Workspace EventObject.

Mapeamento de solicitações

A tabela a seguir mostra como os campos na API Google Chat Event são mapeados para os campos correspondentes no complemento do Google Workspace EventObject.

Campo Event de interação da API Google Chat Campo EventObject do complemento do Google Workspace Observações
action.actionMethodName N/A Para interações com cards, o nome do método pode ser transmitido como um parâmetro em commonEventObject.parameters. Consulte Abrir uma caixa de diálogo inicial.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Disponível em diferentes payloads, dependendo do tipo de evento.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Disponível em diferentes payloads, dependendo do tipo de evento.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Disponível em diferentes payloads, dependendo do tipo de evento.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Disponível em diferentes payloads, dependendo do tipo de evento.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Disponível em diferentes payloads, dependendo do tipo de evento.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Disponível em diferentes payloads, dependendo do tipo de evento.
token N/A A verificação é processada de maneira diferente. Consulte Solicitar verificação para apps HTTP.
type N/A O tipo de evento pode ser deduzido do gatilho.
user chat.user

Mapeamento de solicitações por caso de uso

A tabela a seguir mostra as diferenças nos payloads de solicitação para casos de uso comuns entre apps do Google Chat criados com eventos de interação da API Chat e complementos do Google Workspace que estendem o Google Chat.

Caso de uso Payload de interação da API Chat Event Payload do complemento EventObject do Google Workspace
App adicionado ao espaço 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Remover app do espaço 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
O usuário @menciona um app 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
O usuário @menciona um app para adicioná-lo ao espaço Você precisa processar uma solicitação do Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Você precisa processar duas solicitações do Google Chat.

Primeira solicitação:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Segunda solicitação:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Comando de barra 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Comando de barra para adicionar um app ao espaço Você precisa processar uma solicitação do Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Você precisa processar duas solicitações do Google Chat.

Primeira solicitação:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Segunda solicitação:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
O usuário clica em um botão em um card ou caixa de diálogo 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Para eventos de caixa de diálogo, common.formInputs contém valores de widget. Exemplo do Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Para eventos de caixa de diálogo, commonEventObject.formInputs contém valores de widget. Exemplo do Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
O usuário envia informações em um card da página inicial do app 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
O usuário invoca um comando de app usando um comando rápido. 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Visualização de link 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
O usuário atualiza um widget em uma mensagem ou caixa de diálogo de card 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Mapeamento de respostas por caso de uso

Os complementos do Google Workspace que ampliam o Google Chat retornam ações em vez de um objeto Message. A tabela a seguir correlaciona os tipos de resposta Message da API Google Chat com os equivalentes de ação dos complementos do Google Workspace.

Caso de uso Resposta Message da API Google Chat Resposta da ação do chat do complemento do Google Workspace
Criar uma mensagem no espaço invocado 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse é opcional. Para saber mais, consulte Responder a um comando de barra.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Para saber mais, consulte Enviar uma mensagem.
Atualizar uma mensagem 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Para saber mais, consulte Atualizar uma mensagem (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Para saber mais, consulte Atualizar uma mensagem (complementos).
Visualização de link 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Para saber mais, consulte Visualizar um link (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Para saber mais, consulte Visualizar um link(complementos).
Abrir uma caixa de diálogo inicial 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Para saber mais, consulte Abrir uma caixa de diálogo (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
O card que você empurra pode conter widgets com ações de onClick. Para complementos HTTP do Google Workspace, configure estas ações para chamar um endpoint de função: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Para saber mais, consulte Abrir uma caixa de diálogo (complementos).
Fechar uma caixa de diálogo 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Para saber mais, consulte Fechar uma caixa de diálogo (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Para saber mais, consulte Fechar uma caixa de diálogo (complementos).
Conectar a um sistema externo (configuração de solicitação) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Para saber mais, consulte Conectar-se a um sistema externo.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Para saber mais, consulte Conectar o complemento do Google Workspace a um serviço de terceiros.
Preencher automaticamente itens em widgets interativos 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Para saber mais, consulte Adicionar um menu de multisseleção.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Para saber mais, consulte Coletar e processar informações de usuários do Google Chat.

Processar interações com cards em mensagens criadas antes da conversão

Quando você converte um app HTTP do Google Chat em um complemento do Google Workspace, as interações com cards em mensagens criadas antes da conversão exigem um tratamento especial. Os complementos do Google Workspace usam um URL HTTP completo para o action.function de um card, enquanto os apps do Google Chat criados com eventos de interação da API Google Chat usam um nome de função. A tabela a seguir resume essas diferenças.

App do Google Chat criado com eventos de interação da API Google Chat Complemento do Google Workspace que estende o Google Chat
Configuração Você configura um único endpoint para todos os eventos no console do Google Cloud. Ao implementar interações com cards, o action de um card contém apenas o nome da função a ser executada. O endpoint HTTP comum é invocado para eventos de clique no card.

Para saber mais, consulte Abrir uma caixa de diálogo (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 É possível configurar endpoints por evento no console do Google Cloud, mas isso não inclui eventos de clique no card. Ao implementar interações com cards, o action de um card precisa conter o URL completo do endpoint HTTP a ser invocado. É possível definir um endpoint HTTP exclusivo por botão ou usar um endpoint comum e transmitir a ação como um parâmetro em action.parameters.

Para saber mais, consulte Abrir uma caixa de diálogo (complementos).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Para garantir que as interações com cards funcionem para mensagens criadas antes da conversão, configure um URL de interação com card na página de configuração da API Google Chat.

Esse URL é usado apenas para interações em mensagens criadas antes da conversão do app. Quando um usuário interage com uma dessas mensagens, o valor action.function original é transmitido como um parâmetro chamado __action_method_name__.

Exemplo: clique do card

Se você configurou o URL de interação do card como https://.../card-interaction-handler e um usuário clicar em um card em uma mensagem histórica com a seguinte ação:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Um evento é entregue ao URL de interação do card configurado no seguinte formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Exemplo: menu de seleção múltipla

Se um usuário interagir com um menu de seleção múltipla com uma fonte de dados externa:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Um evento é entregue ao URL de interação do card configurado no seguinte formato:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Se você ativar a opção Usar um URL de endpoint HTTP comum para todos os gatilhos nos gatilhos HTTP, o URL comum também será usado para eventos de Clique no botão.

Verificar solicitações de complementos HTTP do Google Workspace que estendem o Chat

Para apps do Google Chat baseados em HTTP, a lógica para verificar se as solicitações se originam do Google precisa ser atualizada ao converter para um complemento do Google Workspace.

As principais diferenças na verificação de solicitações são:

Tipo de app Público-alvo aceito E-mail da conta de serviço
App do Google Chat criado com eventos de interação da API Google Chat Número do projeto chat@system.gserviceaccount.com
Complemento do Google Workspace que estende o Google Chat Somente endpoint HTTP E-mail da conta de serviço por projeto

O e-mail exclusivo da conta de serviço do seu complemento do Google Workspace pode ser encontrado na seção Converter em complementos do Google Workspace na página de configuração da API Google Chat no console do Google Cloud.

Para verificar solicitações no seu complemento atualizado do Google Workspace:

  1. Se você estiver usando o Cloud Run Functions, conceda o papel roles/cloudfunctions.invoker à conta de serviço por complemento. Consulte Autorizar acesso com o IAM.
  2. Atualize seu código de verificação de token para usar o e-mail da conta de serviço do complemento do Google Workspace e verificar a assinatura do token do portador. Consulte Validar solicitações do Google.