Inizia la conversazione

Scegli se gestire gli agenti con la console Developer Console o l'API.

Developer Console API

Nelle conversazioni con gli agenti Business Messages, il messaggio di benvenuto definisce il tono dell'interazione. Inoltre, consente agli utenti di sapere cosa può fare l'agente, il che influenza le domande e le aspettative dell'utente.

L'agente invia un messaggio di benvenuto ogni volta che l'utente apre una conversazione. L'agente può anche mostrare spunti di conversazione per guidare gli utenti lungo percorsi noti o frequenti.

Se un utente tenta di avviare una conversazione al di fuori dell'orario di apertura di un agente, l'agente visualizza un messaggio offline che puoi utilizzare per condividere canali alternativi o suggerire i passaggi successivi. Sfruttando queste impostazioni, puoi aumentare l'affidabilità e l'usabilità del tuo agente.

Impostazioni a livello di agente e posizione

Puoi specificare le impostazioni conversazionali a livello di agente o sede.

• A livello di agente:Queste impostazioni conversazionali si applicano a tutte le conversazioni con l'agente su tutti i punti di accesso.

  Un messaggio di benvenuto a livello di agente potrebbe iniziare con "Grazie per aver contattato Bridgepoint Runners..." Gli spunti di conversazione possono concentrarsi su azioni o informazioni a livello aziendale.

• A livello di sede:queste impostazioni sostituiscono quelle a livello di agente e si applicano solo alle conversazioni con quella sede tramite i PLACESHEET e i punti di accesso MAPS.

  Un messaggio di benvenuto a livello di località potrebbe iniziare con "Grazie per aver contattato Bridgepoint Runners su Amphitheatre Pkwy..." Gli spunti di conversazione possono concentrarsi su attività o informazioni basate sulla posizione. Un messaggio offline potrebbe indicare quando la sede sarà aperta la prossima volta.

Impostazioni internazionali

Gli agenti e le sedi possono specificare impostazioni separate per le impostazioni internazionali che supportano. Ad esempio, un agente potrebbe specificare un messaggio di benvenuto in inglese per il locale "en" e avere lo stesso messaggio di benvenuto in spagnolo per il locale "es". Business Messages risolve una corrispondenza tra le impostazioni internazionali segnalate del dispositivo dell'utente e le impostazioni internazionali per cui un agente o una sede dispone di impostazioni conversazionali.

Questa corrispondenza delle impostazioni internazionali viene riportata nel campo resolvedLocale di ogni messaggio. Puoi specificare il defaultLocale di un agente o di una sede, che pondera la corrispondenza delle impostazioni internazionali risolte. Consulta la sezione Localizzazione e località.

Business Messages utilizza le impostazioni internazionali risolte per determinare quali impostazioni conversazionali applicare.

Nota: Business Messages applica solo le impostazioni conversazionali specificate per le impostazioni internazionali risolte. Ad esempio, se le impostazioni internazionali risolte sono "es", ma non hai specificato un messaggio offline per le impostazioni internazionali "es", Business Messages non visualizza un messaggio offline quando potrebbe essere visualizzato, anche se hai specificato messaggi offline per altre impostazioni internazionali.

Messaggio di benvenuto

Il primo messaggio in una conversazione tra un agente e un utente è il messaggio di benvenuto dell'agente. Il messaggio di benvenuto viene visualizzato automaticamente dopo che un utente avvia una nuova conversazione. Un buon messaggio di benvenuto definisce le aspettative dell'utente per l'interazione con l'agente. Per modificare un messaggio di benvenuto, consulta Aggiornare le impostazioni conversazionali.

Spunti di conversazione

Un buon messaggio di benvenuto descrive a grandi linee la funzionalità di un agente ed è aperto, mentre i buoni spunti di conversazione guidano gli utenti verso domande frequenti o funzionalità note.

Gli spunti di conversazione vengono visualizzati come risposte suggerite incolonnate verticalmente subito dopo il messaggio di benvenuto. Quando un utente tocca un suggerimento di conversazione, l'agente riceve contenuti predefiniti e dati di postback che hai impostato quando hai specificato il suggerimento.

Se un agente supporta la funzionalità automatizzata per determinate richieste, gli spunti di conversazione potrebbero essere mappati a queste richieste, consentendoti di fare affidamento su input noti per l'automazione e inviare domande degli utenti in formato libero agli agenti live pronti a rispondere.

Attenzione: gli agenti non devono fare affidamento solo sugli spunti di conversazione per attivare le risposte automatiche. Se un utente ha una versione obsoleta di un client, quest'ultimo potrebbe avviare una conversazione con l'agente, ma non essere in grado di visualizzare gli spunti di conversazione. Assicurati che l'input utente in formato libero possa attivare risposte automatiche e crea un messaggio di benvenuto efficace che copra le funzionalità del tuo agente.

Un agente può avere un massimo di 5 frasi di avvio della conversazione e ognuna può contenere un massimo di 35 caratteri.

Per aggiungere o modificare gli spunti di conversazione, vedi Aggiornare le impostazioni conversazionali.

Messaggi offline

Quando un utente avvia una conversazione con un agente fuori dall'orario di apertura dell'agente (come definito da MessagingAvailability), l'utente riceve il messaggio offline dell'agente. Quando viene attivato un messaggio offline, viene presa in considerazione solo la disponibilità di un rappresentante umano. Gli agenti che hanno solo rappresentanti bot inviano sempre un messaggio di benvenuto. Un buon messaggio offline

• Spiega perché l'agente non è disponibile
• Fornisce all'utente le istruzioni sui passaggi successivi appropriati o sui canali di contatto alternativi
• Corrisponde al tono del messaggio di benvenuto e degli spunti di conversazione

Bad offline message

"Spiacenti, siamo chiusi."

Buon messaggio offline

"Al momento siamo chiusi, ma puoi trovarci domani alle ore 08:00. Se hai bisogno di assistenza urgente, contatta l'assistenza al numero [phone] o all'indirizzo [e-mail]."

Per modificare un messaggio offline, consulta Aggiornare le impostazioni conversazionali.

Aggiornare le impostazioni conversazionali

Per gestire un messaggio di benvenuto o gli spunti di conversazione, invia una richiesta PATCH con l'API Business Communications per aggiornare il campo conversationalSettings di un agente o di una sede.

Quando aggiorni il campo conversationalSettings, devi includere i valori per tutti i campi nell'oggetto ConversationalSetting. Le richieste di aggiornamento sovrascrivono i contenuti di tutti i campi che modifichi, inclusi i campi secondari. Ad esempio, se invii una richiesta di modifica di un messaggio di benvenuto ma non includi spunti di conversazione, la richiesta rimuove eventuali spunti di conversazione precedenti.

Nota: potrebbero essere necessarie fino a due ore prima che le nuove impostazioni conversazionali vengano visualizzate nelle conversazioni con l'agente.

Prerequisiti

Prima di aggiornare le impostazioni conversazionali, devi disporre di quanto segue:

• Percorso della chiave del service account del progetto GCP sulla macchina di sviluppo
• Le impostazioni locali per cui vuoi aggiornare le impostazioni

• Per le impostazioni a livello di agente, agente name (ad esempio "brands/12345/agents/67890")

  Se non conosci l'name dell'agente, consulta Elenco di tutti gli agenti per un brand.

• Per le impostazioni a livello di sede, posizione name (ad esempio, "brands/12345/locations/67890")

  Se non conosci il name della sede, consulta Elenco di tutte le sedi di un brand.

• Le impostazioni internazionali da aggiornare, come codice lingua ISO 639-1 di due caratteri

• Nuovo messaggio di benvenuto

• URL Norme sulla privacy

• (Facoltativo) Testo per gli spunti di conversazione

• (Facoltativo) Dati di postback per gli spunti di conversazione

• (Facoltativo) Nuovo messaggio offline

Se non conosci i valori attuali di conversationalSettings, consulta Recuperare le informazioni dell'agente e Recuperare i dati sulla posizione.

Inviare la richiesta di aggiornamento

Per aggiornare l'agente o la posizione, esegui questo comando. Sostituisci le variabili con i valori che hai identificato in Prerequisiti.

Se non vuoi suggerimenti per iniziare una conversazione, ometti conversationStarters e tutti i relativi campi secondari.

Impostazioni a livello di 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"
              }
            }
          }
        ]
      }
    }
  }
}'
update-agent-bm-conversationalSettings.sh

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();
update-agent-bm-conversationalSettings.js

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();
    }
  }
}

Questo codice è basato sulla libreria client 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)
update-agent-bm-conversationalSettings.py

Impostazioni a livello di località

# 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"
            }
          }
        }
      ]
    }
  }
}'
update-location-bm-conversationalSettings.sh

Per informazioni su formattazione e valori, vedi brands.agents.patch, brands.locations.patch, e ConversationalSetting.

Esempi

Impostazioni a livello di 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',
                            },
                        },
                    },
                ],
            },
        },
    },
}"

Impostazioni a livello di località

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': '[phone]',
                            },
                        },
                    },
                },
            ],
        },
    },
}"