Estender a interface da mensagem

Os complementos do Google Workspace que estendem o Gmail podem fornecer uma interface do usuário quando o usuário está lendo mensagens. Isso permite que os complementos automatizem tarefas que respondem ao conteúdo da mensagem, como mostrar, recuperar ou enviar informações adicionais relacionadas a ela.

Acessar a interface de mensagens do complemento do Google Workspace

Há duas maneiras de ver a interface de mensagens de um complemento. A primeira maneira é abrir uma mensagem enquanto o complemento já está aberto (por exemplo, ao visualizar a página inicial do complemento na janela da caixa de entrada do Gmail). A segunda maneira é iniciar o complemento ao visualizar uma mensagem.

Em ambos os casos, o complemento executa a função de gatilho contextual correspondente, definida no manifesto do complemento. O gatilho também é executado se o usuário mudar para outra mensagem enquanto o complemento ainda estiver aberto. A função de acionamento contextual cria a interface da mensagem, que o Gmail mostra ao usuário.

Criar um complemento de mensagens

Para adicionar a funcionalidade de mensagens a um complemento, siga estas etapas gerais:

1. Adicione os campos adequados ao projeto manifesto do script do complemento, incluindo os escopos necessários para a funcionalidade de mensagens. Adicione um campo de acionamento condicional ao manifesto, com um valor unconditional de {}.
2. Implemente uma função de acionamento contextual que crie uma interface de mensagem quando o usuário selecionar o complemento em uma mensagem.
3. Implemente as funções associadas necessárias para responder às interações do usuário com a interface.

Acionadores contextuais

Para ajudar os usuários a ler mensagens, os complementos podem definir um gatilho contextual nos manifestos. Quando o usuário abre uma mensagem do Gmail (com o complemento aberto) que atende aos critérios de acionamento*, o acionamento é ativado. Um gatilho disparado executa uma função de gatilho contextual que cria a interface do usuário do complemento e a retorna para o Gmail exibir. Nesse ponto, o usuário pode começar a interagir com ele.

Os gatilhos contextuais são definidos no manifesto do projeto do complemento. A definição de gatilho informa ao Gmail qual função de gatilho acionar em quais condições. Por exemplo, este snippet de manifesto define um gatilho incondicional que chama a função de gatilho onGmailMessageOpen() quando uma mensagem é aberta:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Função de acionamento contextual

Todo acionador contextual precisa ter uma função de acionamento correspondente que crie a interface do usuário do complemento. Especifique essa função no campo onTriggerFunction do manifesto. Implemente essa função para aceitar um argumento de objeto de evento de ação e retornar um único objeto Card ou uma matriz de objetos Card.

Quando um gatilho contextual é acionado para uma determinada mensagem do Gmail, ele chama essa função e transmite um objeto de evento de ação. As funções de acionamento geralmente usam o ID da mensagem fornecido por esse objeto de evento para receber o texto da mensagem e outros detalhes usando o serviço do Gmail do Apps Script. Na maioria dos casos, é necessário ativar os escopos do Gmail usando o token de acesso fornecido pelo objeto de evento e a função GmailApp.setCurrentMessageAccessToken(accessToken) antes de usar outras funções do serviço do Gmail. Por exemplo, sua função de acionamento pode extrair o conteúdo da mensagem usando estas funções:

// Activate temporary Gmail scopes, in this case to allow
// the add-on to read message metadata and content.
var accessToken = e.gmail.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);

// Read message metadata and content. This requires the Gmail scope
// https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
var messageId = e.gmail.messageId;
var message = GmailApp.getMessageById(messageId);
var subject = message.getSubject();
var sender = message.getFrom();
var body = message.getPlainBody();
var messageDate = message.getDate();

// Setting the access token with a gmail.addons.current.message.readonly
// scope also allows read access to the other messages in the thread.
var thread = message.getThread();
var threadMessages = thread.getMessages();

// Using this link can avoid the need to copy message or thread content
var threadLink = thread.getPermalink();

A função de acionamento pode então agir sobre esses dados, extraindo as informações necessárias para a interface. Por exemplo, um complemento que resume números de vendas pode coletar valores do corpo da mensagem e organizá-los para exibição em um card.

A função de acionamento precisa criar e retornar uma matriz de objetos Card criados. Por exemplo, o código a seguir cria um complemento com um único card que apenas lista o assunto e o remetente da mensagem:

function onGmailMessageOpen(e) {
  // Activate temporary Gmail scopes, in this case to allow
  // message metadata to be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();

  // Create a card with a single card section and two widgets.
  // Be sure to execute build() to finalize the card construction.
  var exampleCard = CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader()
          .setTitle('Example card'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}