Comece a conversa

Nas conversas com agentes do Business Messages, a mensagem de boas-vindas define o tom da interação. Ele também informa aos usuários o que o agente pode fazer, o que moldam as perguntas e expectativas do usuário.

O agente envia uma mensagem de boas-vindas sempre que o usuário abre uma conversa. O agente também pode mostrar inícios de conversa para guiar os usuários por caminhos conhecidos ou frequentes.

Se um usuário tentar iniciar uma conversa fora do horário de funcionamento de um agente, o agente vai mostrar uma mensagem off-line que você pode usar para compartilhar canais alternativos ou sugerir próximas etapas. Ao usar essas configurações, você pode aumentar a confiabilidade e a usabilidade do seu agente.

Sugestões de conversa

Configurações no nível do agente e do local

É possível especificar configurações de conversa no nível do agente ou do local.

  • Nível do agente:essas configurações de conversa se aplicam a todas as conversas com o agente em todos os pontos de entrada.

    Uma mensagem de boas-vindas no nível do agente pode começar com "Agradecemos por entrar em contato com Bridgepoint Runners..." As ativações de conversa podem se concentrar em ações ou informações de toda a empresa.

  • No nível do local:essas configurações substituem as do agente e se aplicam apenas a conversas com esse local nos pontos de entrada PLACESHEET e MAPS.

    Uma mensagem de boas-vindas no nível do local pode começar com "Agradecemos por entrar em contato com a Bridgepoint Runners na Amphitheatre Pkwy..." Os iniciadores de conversa podem se concentrar em tarefas ou informações com base na localização. Uma mensagem off-line pode mencionar quando o local vai abrir novamente.

Localidades

Os agentes e locais podem especificar configurações separadas para as localidades que oferecem suporte. Por exemplo, um agente pode especificar uma mensagem de boas-vindas em inglês para a localidade "en" e ter a mesma mensagem em espanhol para a localidade "es". O Business Messages resolve uma correspondência entre a localidade informada do dispositivo do usuário e as localidades para as quais um agente ou local tem configurações de conversa.

Essa correspondência de localidade é informada no campo resolvedLocale de cada mensagem. É possível especificar um defaultLocale de um agente ou local, que pondera a correspondência de localidade resolvida. Consulte Localização e locais.

As mensagens comerciais usam a localidade resolvida para determinar quais configurações de conversa aplicar.

Mensagem de recepção

A primeira mensagem em uma conversa entre um agente e um usuário é a mensagem de boas-vindas do agente. A mensagem de boas-vindas aparece automaticamente depois que um usuário inicia uma nova conversa. Uma boa mensagem de recepção define as expectativas do usuário ao interagir com o agente. Para editar uma mensagem de boas-vindas, consulte Atualizar as configurações de conversa.

Sugestões de conversa

Uma boa mensagem de boas-vindas aborda a funcionalidade de um agente em um nível alto e é aberta. Já os bons iniciadores de conversa guiam os usuários para perguntas frequentes ou funcionalidades conhecidas.

As sugestões de conversa aparecem como respostas sugeridas em sequência logo após a mensagem de boas-vindas. Quando um usuário toca em um início de conversa, o agente recebe conteúdo predefinido e dados de postback que você define ao especificar o início.

Se um agente oferecer suporte à funcionalidade automatizada para determinadas solicitações, os iniciadores de conversa poderão ser mapeados para essas solicitações, permitindo que você confie em entradas conhecidas para automação e envie perguntas de usuários em formato livre para atendentes disponíveis para responder.

Um agente pode ter no máximo cinco iniciadores de conversa, e cada um deles pode ter no máximo 35 caracteres.

Para adicionar ou editar iniciadores de conversa, consulte Atualizar as configurações de conversa.

Mensagens off-line

Quando um usuário inicia uma conversa com um agente fora do horário de atendimento dele (definido por MessagingAvailability), ele recebe a mensagem off-line do agente. Somente a disponibilidade de um representante humano é considerada ao acionar uma mensagem off-line. Os agentes que só têm representantes de bot sempre enviam uma mensagem de boas-vindas. Uma boa mensagem off-line

  • Explica por que o agente está indisponível
  • Instrui o usuário sobre as próximas etapas adequadas ou canais de contato alternativos
  • Corresponde ao tom da mensagem de boas-vindas e dos puxa-conversa

Mensagem off-line inadequada

"Desculpe, estamos fechados."

Boa mensagem off-line

"Estamos fechados agora, mas estaremos disponíveis novamente amanhã às 8h. Se precisar de ajuda urgente, entre em contato com o suporte pelo número +12223334444 ou pelo e-mail support@gtb.com."

Para editar uma mensagem off-line, consulte Atualizar as configurações de conversa.

Atualizar as configurações de conversa

Para gerenciar uma mensagem de boas-vindas ou iniciadores de conversa, faça uma solicitação PATCH com a API Business Communications para atualizar o campo conversationalSettings de um agente ou local.

Ao atualizar o campo conversationalSettings, inclua valores para todos os campos no objeto ConversationalSetting. As solicitações de atualização substituem o conteúdo de todos os campos editados, incluindo campos filhos. Por exemplo, se você fizer uma solicitação para modificar uma mensagem de boas-vindas, mas não incluir iniciadores de conversa, a solicitação vai remover todos os iniciadores anteriores.

Pré-requisitos

Antes de atualizar as configurações de conversa, você precisa dos seguintes itens:

  • Caminho para a chave da conta de serviço do projeto do GCP na sua máquina de desenvolvimento
  • A localidade para a qual você quer atualizar as configurações

  • Para configurações no nível do agente, use name (por exemplo, "brands/12345/agents/67890")

    Se você não souber o name do agente, consulte Listar todos os agentes de uma marca.

  • Para configurações no nível do local, name (por exemplo, "brands/12345/locations/67890")

    Se você não souber o name do local, consulte Listar todos os locais de uma marca.

  • A localidade a ser atualizada, como um código de idioma ISO 639-1 de dois caracteres

  • Nova mensagem de boas-vindas

  • URL da Política de Privacidade

  • (Opcional) Texto para sugestões de conversa

  • (Opcional) Dados de postback para sugestões de conversa

  • (Opcional) Nova mensagem off-line

Se você não souber os valores atuais de conversationalSettings, consulte Receber informações do agente e Receber informações de local.

Enviar o pedido de atualização

Para atualizar o agente ou o local, execute o seguinte comando: Substitua as variáveis pelos valores identificados em Pré-requisitos.

Se você não quiser sugestões de início de conversa, omita conversationStarters e todos os campos filhos dele.

Configurações no nível do agente

cURL 

# This code updates the conversational settings of a Business Messages agent.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/patch

# Replace the __BRAND_ID__, __AGENT_ID__ and __LOCALE__
# Make sure a service account key file exists at ./service_account_key.json

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/agents/__AGENT_ID__?updateMask=businessMessagesAgent.conversationalSettings.__LOCALE__" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "businessMessagesAgent": {
    "conversationalSettings": {
      "__LOCALE__": {
        "welcomeMessage": {
          "text": "My first welcome message"
        },
        "offlineMessage": {
          "text": "My first offline message"
        },
        "privacyPolicy": {
          "url": "https://www.your-company-website.com/privacy"
        },
        "conversationStarters": [
          {
            "suggestion": {
              "reply": {
                "text": "Suggestion 1",
                "postbackData": "post_back_suggestion_1"
              }
            }
          }
        ]
      }
    }
  }
}'

Node.js 

/**
 * This code snippet updates the conversationalSettings of a Business Messages agent.
 * Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/patch
 *
 * This code is based on the https://github.com/google-business-communications/nodejs-businesscommunications Node.js
 * Business Communications client library.
 */

/**
 * Edit the values below:
 */
const BRAND_ID = 'EDIT_HERE';
const AGENT_ID = 'EDIT_HERE';
const LOCALE = 'en';
const PATH_TO_SERVICE_ACCOUNT_KEY = './service_account_key.json';

const businesscommunications = require('businesscommunications');
const {google} = require('googleapis');

// Initialize the Business Communications API
const bcApi = new businesscommunications.businesscommunications_v1.Businesscommunications({});

// Set the scope that we need for the Business Communications API
const scopes = [
  'https://www.googleapis.com/auth/businesscommunications',
];

// Set the private key to the service account file
const privatekey = require(PATH_TO_SERVICE_ACCOUNT_KEY);

async function main() {
  const authClient = await initCredentials();

  const agentName = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID;

  if (authClient) {
    // Setup the parameters for the API call
    const apiParams = {
      auth: authClient,
      name: agentName,
      updateMask: 'businessMessagesAgent.conversationalSettings.' + LOCALE,
      resource: {
        businessMessagesAgent: {
          conversationalSettings: {
            [LOCALE]: {
              privacyPolicy: { url: 'https://www.your-company-website.com/privacy' },
              welcomeMessage: { text: 'My updated welcome message' },
              offlineMessage: { text: 'My updated offline message' },
              conversationStarters: [
                {
                  suggestion: {
                    reply: {
                      'text': 'Suggestion 2',
                     'postbackData': 'post_back_suggestion_2',
                    },
                  },
                }
              ],
            },
          }
        }
      }
    };

    bcApi.brands.agents.patch(apiParams, {}, (err, response) => {
      if (err !== undefined && err !== null) {
        console.dir(err);
      } else {
        // Agent found
        console.log(response.data);
      }
    });
  }
  else {
    console.log('Authentication failure.');
  }
}

/**
 * Initializes the Google credentials for calling the
 * Business Messages API.
 */
 async function initCredentials() {
  // Configure a JWT auth client
  const authClient = new google.auth.JWT(
    privatekey.client_email,
    null,
    privatekey.private_key,
    scopes,
  );

  return new Promise(function(resolve, reject) {
    // Authenticate request
    authClient.authorize(function(err, tokens) {
      if (err) {
        reject(false);
      } else {
        resolve(authClient);
      }
    });
  });
}

main();

Java 

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.services.businesscommunications.v1.BusinessCommunications;
import com.google.api.services.businesscommunications.v1.model.*;
import com.google.common.collect.ImmutableMap;
import java.io.FileInputStream;
import java.util.Arrays;

class Main {
  /**
   * Initializes credentials used by the Business Communications API.
   */
  private static BusinessCommunications.Builder getBusinessCommunicationsBuilder() {
    BusinessCommunications.Builder builder = null;
    try {
      GoogleCredential credential = GoogleCredential
            .fromStream(new FileInputStream("PATH_TO_SERVICE_ACCOUNT_KEY"));

      credential = credential.createScoped(Arrays.asList(
          "https://www.googleapis.com/auth/businesscommunications"));

      credential.refreshToken();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      JacksonFactory jsonFactory = JacksonFactory.getDefaultInstance();

      // Create instance of the Business Communications API
      builder = new BusinessCommunications
          .Builder(httpTransport, jsonFactory, null)
          .setApplicationName(credential.getServiceAccountProjectId());

      // Set the API credentials and endpoint
      builder.setHttpRequestInitializer(credential);
    } catch (Exception e) {
      e.printStackTrace();
    }

    return builder;
  }

  public static void main(String args[]) {
    try {
      // Create client library reference
      BusinessCommunications.Builder builder = getBusinessCommunicationsBuilder();

      String agentName = "brands/BRAND_ID/agents/AGENT_ID";

      Agent agent = new Agent().setBusinessMessagesAgent(
          new BusinessMessagesAgent().setConversationalSettings(ImmutableMap.of("LOCALE",
              new ConversationalSetting()
                  .setPrivacyPolicy(new PrivacyPolicy().setUrl("PRIVACY_POLICY_URL"))
                  .setWelcomeMessage(new WelcomeMessage().setText("WELCOME_MESSAGE"))
                  .setOfflineMessage(new OfflineMessage().setText("OFFLINE_MESSAGE"))
                  .setConversationStarters(Arrays.asList(
                      new ConversationStarters().setSuggestion(new Suggestion()
                          .setReply(new SuggestedReply()
                              .setText("REPLY_TEXT")
                              .setPostbackData("POSTBACK_DATA"))),
                      )))));

      BusinessCommunications.Brands.Agents.Patch request = builder
          .build().brands().agents().patch(agentName, agent);

      request.setUpdateMask("businessMessagesAgent.conversationalSettings.LOCALE");

      Agent updatedAgent = request.execute();
      System.out.println(updatedAgent.toPrettyString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
 Esse código é baseado na biblioteca de cliente Java Business Communications.

Python 

"""This code updates the conversational settings of a Business Messages agent.

Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.agents/patch

This code is based on the https://github.com/google-business-communications/python-businessmessages
Python Business Messages client library.
"""

from oauth2client.service_account import ServiceAccountCredentials
from businesscommunications.businesscommunications_v1_client import BusinesscommunicationsV1
from businesscommunications.businesscommunications_v1_messages import (
    Agent,
    BusinessMessagesAgent,
    ConversationStarters,
    ConversationalSetting,
    OfflineMessage,
    PrivacyPolicy,
    WelcomeMessage,
    NegativeBotFeedbackMessage,
    BusinesscommunicationsBrandsAgentsPatchRequest,
)

# Edit the values below:
BRAND_ID = 'EDIT_HERE'
AGENT_ID = 'EDIT_HERE'
SCOPES = ['https://www.googleapis.com/auth/businesscommunications']
SERVICE_ACCOUNT_FILE = './service_account_key.json'

credentials = ServiceAccountCredentials.from_json_keyfile_name(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

client = BusinesscommunicationsV1(credentials=credentials)

agents_service = BusinesscommunicationsV1.BrandsAgentsService(client)

agent_name = 'brands/' + BRAND_ID + '/agents/' + AGENT_ID

agent=Agent(
                businessMessagesAgent=BusinessMessagesAgent(
                        conversationalSettings=BusinessMessagesAgent.ConversationalSettingsValue(
                        additionalProperties=[BusinessMessagesAgent.ConversationalSettingsValue.AdditionalProperty(
                            key='en',
                            value=ConversationalSetting(
                                privacyPolicy=PrivacyPolicy(url='https://www.your-company-website.com/privacy'),
                                welcomeMessage=WelcomeMessage(text='Welcome to Business Messages'),
                            offlineMessage=OfflineMessage(text='This is an offline message'),
                                conversationStarters=[
                                    ConversationStarters(
                                        suggestion=Suggestion(
                                           reply=SuggestedReply(text='Option 1',
                                  postbackData='option_1')
                                        )
                                    )]
                                )
                            )
                        ]
                    )
                )
)

updated_agent = agents_service.Patch(
        BusinesscommunicationsBrandsAgentsPatchRequest(
            agent=agent,
            name=agent_name,
            updateMask='businessMessagesAgent.conversationalSettings.en'
        )
    )

print(updated_agent)

Configurações no nível do local 

# This code updates the agent interaction of a bot and human representatives.
# Read more: https://developers.google.com/business-communications/business-messages/reference/business-communications/rest/v1/brands.locations/patch

# Replace the __BRAND_ID__, __AGENT_ID__, __LOCATION_ID__, __LOCALE__
# Make sure a service account key file exists at ./service_account_key.json

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/__BRAND_ID__/locations/__LOCATION_ID__?updateMask=conversationalSettings.__LOCALE__" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json ./service_account_key.json businesscommunications)" \
-d '{
  "conversationalSettings": {
    "__LOCALE__": {
      "welcomeMessage": {
        "text": "My second welcome message"
      },
      "offlineMessage": {
        "text": "My second offline message"
      },
      "privacyPolicy": {
        "url": "https://www.your-company-website.com/privacy"
      },
      "conversationStarters": [
        {
          "suggestion": {
            "reply": {
              "text": "Suggestion 2",
              "postbackData": "post_back_suggestion_2"
            }
          }
        }
      ]
    }
  }
}'

Para informações sobre formatação e valores, consulte brands.agents.patch, brands.locations.patch e ConversationalSetting.

Exemplos

Configurações no nível do agente 

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/BRAND_ID/agents/AGENT_ID?updateMask=businessMessagesAgent.conversationalSettings.en" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY businesscommunications)" \
-d "{
    'businessMessagesAgent': {
        'conversationalSettings': {
            'en': {
                'welcomeMessage': {
                    'text': 'Thanks for contacting Growing Tree Bank. What can I help with today?',
                },
                'offlineMessage': {
                    'text': 'We\'re closed for the night. Please reach out to us again tomorrow.',
                },
                'privacyPolicy': {
                    'url': 'https://www.growingtreebank.com/privacy',
                },
                'conversationStarters': [
                    {
                        'suggestion': {
                            'reply': {
                                'text': 'Set up an account',
                                'postbackData': 'new-account',
                            },
                        },
                    },
                    {
                        'suggestion': {
                            'reply': {
                                'text': 'Look up account information',
                                'postbackData': 'account-lookup',
                            },
                        },
                    },
                ],
            },
        },
    },
}"

Configurações no nível do local 

curl -X PATCH \
"https://businesscommunications.googleapis.com/v1/brands/12345/locations/67890?updateMask=conversationalSettings.en" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/business-communications" \
-H "$(oauth2l header --json /path/to/service/account/key businesscommunications)" \
-d "{
    'conversationalSettings': {
        'en': {
            'welcomeMessage': {
                'text': 'Thanks for contacting Growing Tree Bank on Amphitheatre Pkwy. What can I help with today?',
            },
            'offlineMessage': {
                'text': 'We\'re closed for the night. Please reach out to us again tomorrow.',
            },
            'privacyPolicy': {
                'url': 'https://www.growingtreebank.com/privacy',
            },
            'conversationStarters': [
                {
                    'suggestion': {
                        'reply': {
                            'text': 'What are your hours?',
                            'postbackData': 'hours',
                        },
                    },
                },
                {
                    'suggestion': {
                        'reply': {
                            'text': 'Set up an account',
                            'postbackData': 'new-account',
                        },
                    },
                },
                {
                    'suggestion': {
                        'reply': {
                            'text': 'Look up account information',
                            'postbackData': 'account-lookup',
                        },
                    },
                },
                {
                    'suggestion': {
                        'action': {
                            'text': 'Call us',
                            'postbackData': 'call',
                            'dialAction': {
                              'phoneNumber': '+12223334444',
                            },
                        },
                    },
                },
            ],
        },
    },
}"