As ações de conversa foram descontinuadas em 13 de junho de 2023. Para mais informações, consulte Desativação do recurso Ações de conversa.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Webhooks

Para oferecer ainda mais flexibilidade na criação de ações, é possível delegar a lógica a serviços da Web HTTPS (fulfillment). Suas ações podem acionar webhooks que fazem solicitações a um endpoint HTTPS. Confira alguns exemplos do que você pode fazer no fulfillment:

Gerar um comando dinâmico com base nas informações fornecidas pelo usuário.
Fazer um pedido em um sistema externo e confirmar se ele foi concluído.
Validar slots com dados de back-end.

**Figura 1**. As intents de invocação e as cenas podem acionar webhooks.

Gatilhos e gerenciadores de webhook

Suas ações podem acionar um webhook em intents ou cenas de invocação, que envia uma solicitação ao endpoint de fulfillment. Seu fulfillment contém gerenciadores de webhook que processam o payload JSON na solicitação. É possível acionar webhooks nas seguintes situações:

Após uma correspondência de intent de invocação
Durante o estágio de entrada de uma cena
Depois que uma condição é avaliada como verdadeira na etapa de condição de uma cena
Durante a etapa de preenchimento de slot de uma cena
Depois que uma correspondência de intent ocorre na etapa de entrada de uma cena

Quando você aciona um webhook nas suas ações, o Google Assistente envia uma solicitação com um payload JSON para o fulfillment, que contém o nome do gerenciador a ser usado para processar o evento. O endpoint de fulfillment pode encaminhar o evento para o gerenciador apropriado para realizar a lógica e retornar uma resposta correspondente com um payload JSON.

Payloads

Os snippets a seguir mostram exemplos de solicitações que suas ações enviam para fulfillment e uma resposta que o fulfillment envia de volta. Consulte a documentação de referência para mais informações.

Exemplo de solicitação

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Exemplo de resposta

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Interações de ambiente de execução

As seções a seguir descrevem tarefas comuns que podem ser realizadas nos processadores de webhook.

Enviar comandos

É possível criar comandos com texto simples, rich text, cards e até mesmo comandos HTML completos com suporte de um app da Web com a Tela interativa. A documentação de solicitações tem informações completas sobre como criar uma solicitação ao processar um evento de webhook. Os snippets a seguir mostram um comando de card:

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

JSON de resposta

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

Ler parâmetros de intent

Quando o ambiente de execução do Google Assistente corresponde a uma intent, ele extrai os parâmetros definidos. A propriedade original é o que o usuário forneceu como entrada, e a propriedade resolvida é o que a NLU resolveu com base na especificação de tipo.

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

Solicitação JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Ler a localidade do usuário

Esse valor corresponde à configuração de localidade do usuário para o Google Assistente.

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Ler e gravar armazenamento

Consulte a documentação de armazenamento para informações completas sobre como usar vários recursos de armazenamento.

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

Solicitação JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

JSON de resposta

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

Verificar as capabilities do dispositivo

É possível verificar os recursos de um dispositivo para oferecer experiências ou fluxos de conversa diferentes.

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

Solicitação JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

Para uma lista completa de recursos de superfície, consulte a referência Capability.

Substituições de tipo de ambiente de execução

Os tipos de ambiente de execução permitem modificar as especificações de tipo durante a execução. É possível usar esse recurso para carregar dados de outras fontes e preencher os valores válidos de um tipo. Por exemplo, é possível usar substituições de tipo de tempo de execução para adicionar opções dinâmicas a uma pergunta de pesquisa ou um item diário a um menu.

Para usar tipos de tempo de execução, acione um webhook da sua ação que chama um manipulador no fulfillment. Depois, preencha o parâmetro session.typeOverrides em uma resposta à sua ação. Os modos disponíveis incluem TYPE_MERGE para preservar as entradas de tipo atuais ou TYPE_REPLACE para substituir as entradas atuais pelas substituições.

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

JSON de resposta

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

Fornecer adaptação de voz

Com a inclusão de preferências de fala, é possível especificar dicas para a NLU e melhorar a correspondência de intents. É possível especificar até 1.000 entradas.

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

JSON de resposta

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

Transição de cenas

Além de definir transições estáticas no projeto de ações, você pode fazer com que as transições de cena ocorram durante a execução.

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

JSON de resposta

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

Ler slots de cena

Durante o preenchimento de slot, é possível usar o atendimento para validar o slot ou verificar o status do preenchimento de slot (SlotFillingStatus).

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

Por exemplo, suponha que você queira extrair o fuso horário de uma resposta. Neste exemplo, o nome do slot é datetime1. Para conseguir o fuso horário, use:

conv.scene.slots['datetime1'].value.time_zone.id

Solicitação JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Invalidar slots de cena

Você pode invalidar slots e fazer com que o usuário forneça um novo valor.

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

JSON de resposta

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Opções de desenvolvimento

O Actions Builder oferece um editor in-line chamado editor do Cloud Functions, que permite criar e implantar uma função do Cloud para Firebase diretamente no console. Também é possível criar e implantar o fulfillment na hospedagem de sua escolha e registrar o endpoint HTTPS do fulfillment como seu gerenciador de webhook.

Editor in-line

Para desenvolver com o editor do Cloud Functions:

Abra seu projeto do Actions on Google e acesse a guia Desenvolver > Webhook > Mudar método de atendimento. A janela Métodos de atendimento vai aparecer.
Selecione Cloud Functions in-line e clique em Confirmar.

Endpoint HTTPS externo

Esta seção descreve como configurar o Cloud Functions para Firebase como um serviço de atendimento para sua ação de conversa. No entanto, é possível implantar o fulfillment em um serviço de hospedagem de sua escolha.

Configurar o ambiente

Para configurar o ambiente, siga estas etapas:

Faça o download e instale o Node.js.
Configure e inicialize a CLI do Firebase. Se o comando a seguir falhar com um erro EACCES, talvez seja necessário mudar as permissões do npm.
```
npm install -g firebase-tools
```
Autentique a ferramenta do Firebase com sua Conta do Google:
```
firebase login
```
Inicie o diretório do projeto em que você salvou seu projeto do Actions. Você vai precisar selecionar os recursos da CLI do Firebase que quer configurar para seu projeto do Actions. Escolha Functions e outros recursos que você queira usar, como o Firestore. Depois, pressione "Enter" para confirmar e continuar:
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Associe a ferramenta do Firebase ao seu projeto do Actions selecionando-o com as teclas de seta para navegar na lista de projetos:

Observação: é possível pular esta etapa selecionando [não configurar um projeto padrão], mas depois você precisará fazer essa associação usando o comando firebase use PROJECT_ID.

Depois de escolher o projeto, a ferramenta do Firebase inicia a configuração das funções e pergunta qual linguagem você quer usar. Selecione usando as teclas de seta e pressione Enter para continuar.

=== Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

Escolha se você quer usar o ESLint para identificar prováveis bugs e aplicar o estilo digitando Y ou N:
```
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
```
Para receber as dependências do projeto, digite Y no prompt:
```
? Do you want to install dependencies with npm now? (Y/n)
```
Quando a configuração for concluída, você verá uma saída semelhante a esta:
```
✔  Firebase initialization complete!
```

Instale a dependência @assistant/conversation:

$ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

Receba as dependências de fulfillment e implante a função de fulfillment:

$ npm install
$ firebase deploy --only functions

A implantação leva alguns minutos. Quando concluído, você verá uma saída semelhante a esta: Você vai precisar do URL da função para inserir no Dialogflow.

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>

Copie o URL de atendimento para usar na próxima seção.

Registrar o gerenciador de webhook

Para registrar o endpoint da função do Cloud como um gerenciador de webhook:

No Console do Actions, clique em Desenvolver > Webhook.
Clique em Mudar o método de atendimento. A janela Métodos de atendimento aparece.
Selecione Webhook e clique em Confirmar.
Cole o URL do serviço da Web no campo Webhook.
Clique em Salvar.

Webhooks Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Gatilhos e gerenciadores de webhook

Payloads

Exemplo de solicitação

Exemplo de resposta

Interações de ambiente de execução

Enviar comandos

Node.js

JSON de resposta

Ler parâmetros de intent

Node.js

Solicitação JSON

Ler a localidade do usuário

Node.js

JSON

Ler e gravar armazenamento

Node.js

Solicitação JSON

JSON de resposta

Verificar as capabilities do dispositivo

Node.js

Solicitação JSON

Substituições de tipo de ambiente de execução

Node.js

JSON de resposta

Fornecer adaptação de voz

Node.js

JSON de resposta

Transição de cenas

Node.js

JSON de resposta

Ler slots de cena

Node.js

Solicitação JSON

Invalidar slots de cena

Node.js

JSON de resposta

Opções de desenvolvimento

Editor in-line

Endpoint HTTPS externo

Configurar o ambiente

Registrar o gerenciador de webhook

Webhooks