Configurare Cloud Pub/Sub

Gli agenti RBM ricevono messaggi ed eventi tramite una relazione di pubblicazione/sottoscrizione con Cloud Pub/Sub. Quando un utente invia un messaggio al tuo agente o genera un evento, l'app di messaggistica invia le informazioni all'abbonamento Pub/Sub dell'agente, a cui l'agente può accedere al messaggio o all'evento. Vedi Ricevere messaggi.

L'utente invia un messaggio all'agente

Il tipo di sottoscrizione Pub/Sub dell'agente determina il modo in cui l'agente riceve i messaggi, quindi è necessario configurare la sottoscrizione Pub/Sub prima che l'agente possa ricevere messaggi. Gli agenti RBM supportano sia gli abbonamenti pull sia gli abbonamenti push.

Esegui il pull della sottoscrizione

Con una sottoscrizione pull, l'agente contatta Cloud Pub/Sub e recupera messaggi, eventi e altre richieste.

Prerequisiti

Prima di iniziare, devi avere un agente RBM.

Configurazione

  1. Apri la Console per gli sviluppatori di Business Communications, accedi con il tuo Account Google RBM e fai clic sull'agente.
  2. Nel menu di navigazione a sinistra, fai clic su Integrations (Integrazioni).
  3. Fai clic su Modifica abbonamento.
  4. Scegli Pull e poi fai clic su Salva.
  5. Configura l'agente per utilizzare la sottoscrizione pull:
    • Se utilizzi un agente di esempio con una sottoscrizione pull, segui le istruzioni nel file README dell'esempio.
    • Se non utilizzi un agente di esempio, consulta Ricezione di messaggi con la modalità Pull per il codice per consentire all'agente di utilizzare la sottoscrizione pull. A seconda del linguaggio di programmazione, potrebbe essere necessario l'ID progetto dell'agente.

Trovare l'ID progetto

Alcuni meccanismi di abbonamento pull richiedono di specificare l'ID progetto del progetto Google Cloud dell'agente. L'ID progetto dell'agente è incorporato nel nome della sottoscrizione pull che segue project/.

  1. Apri la Console per gli sviluppatori di Business Communications, accedi con il tuo Account Google RBM e fai clic sull'agente.
  2. Nel menu di navigazione a sinistra, fai clic su Integrations (Integrazioni).
  3. Cerca il Nome abbonamento dell'agente.
  4. Individua il segmento di testo tra project/ e / che segue. Questo è l'ID progetto dell'agente. Ad esempio, se il nome della sottoscrizione è projects/rbm-growing-tree-bank-nbdjkl6t/subscriptions/rbm-agent-subscription, l'ID progetto dell'agente è rbm-growing-tree-bank-nbdjkl6t.

C#

private async void InitPullMessages(string projectId, string jsonPath)
{
  GoogleCredential googleCredential = null;
  using (var jsonStream = new FileStream(jsonPath, FileMode.Open,
    FileAccess.Read, FileShare.Read))
  {
    googleCredential = GoogleCredential.FromStream(jsonStream)
      .CreateScoped(SubscriberServiceApiClient.DefaultScopes);
  }

  SubscriptionName subscriptionName = new SubscriptionName(projectId, subscriptionId);
  SubscriberClient subscriber = new SubscriberClientBuilder
  {
    SubscriptionName = subscriptionName,
    GoogleCredential = googleCredential

  }.Build();

  // setup listener for pubsub messages
  await subscriber.StartAsync(
    async (PubsubMessage message, CancellationToken cancel) =>
    {
      string text = System.Text.Encoding.UTF8.GetString(message.Data.ToArray());

      JObject jsonObject = JObject.Parse(jsonAsString);

      string userResponse = GetResponseText(jsonObject);
      string eventType = (string)jsonObject["eventType"];
    
      // check if the message is a user response message
      if ((userResponse.Length > 0) && (eventType == null))
      {
        string messageId = (string)jsonObject["messageId"];
        string msisdn = (string)jsonObject["senderPhoneNumber"];
        // let the user know their message has been read
        kitchenSinkBot.SendReadMessage(messageId, msisdn);
        HandleUserResponse(userResponse, msisdn);
      }
      await Console.Out.WriteLineAsync(
        $"Message {message.MessageId}: {jsonAsString}");
      return SubscriberClient.Reply.Ack;
    });
  }
}
Questo codice è un estratto da un agente di esempio RBM.

Sottoscrizione push

Con una sottoscrizione push, Cloud Pub/Sub esegue il push di messaggi, eventi e altre richieste a un URL webhook da te specificato.

Prerequisiti

Prima di iniziare, occorre quanto segue:

  • Un agente RBM
  • Un URL dell'endpoint del webhook attivo che supporti
    • HTTPS con un certificato SSL valido
    • POST richieste
    • La possibilità di eseguire l'eco di un parametro in risposta a una richiesta di convalida

Configurazione

  1. Apri la Console per gli sviluppatori di Business Communications, accedi con il tuo Account Google RBM e fai clic sull'agente.
  2. Nel menu di navigazione a sinistra, fai clic su Integrations (Integrazioni).
  3. Fai clic su Modifica abbonamento.
  4. Scegli Push.
  5. In URL endpoint webhook, inserisci l'URL del webhook che inizia con "https://".

  6. Configura il webhook in modo che accetti una richiesta POST con il parametro clientToken specificato e invii una risposta 200 OK con il valore del parametro secret.

    Ad esempio, se il webhook riceve una richiesta POST con i seguenti contenuti del corpo

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    il webhook deve confermare il valore clientToken e, se clientToken è corretto, restituire una risposta 200 OK con il corpo secret: 1234567890.

  7. Nella console, fai clic su Verifica.

    Quando la piattaforma RBM verifica il webhook, viene chiusa la finestra di dialogo Configura il webhook.

  8. Fai clic su Salva.

  9. Configura l'agente per ricevere messaggi dal webhook:

    • Se utilizzi un agente di esempio con una sottoscrizione push, segui le istruzioni nel file README dell'esempio.
    • Se non utilizzi un agente di esempio, configura la tua infrastruttura in modo da passare i messaggi dal webhook all'agente.

Node.js

let requestBody = req.body;

if ((requestBody.hasOwnProperty('clientToken')) && (requestBody.hasOwnProperty('secret'))) {
  console.log('RBM webhook verification request');

  // Confirm that the clientToken is the one we are seeing in the RBM console
  if (requestBody.clientToken == CLIENT_TOKEN) {
    console.log('Tokens match, returning secret');
    res.status(200).send('secret: ' + requestBody.secret);
  }
  else {
    // Client tokens did not match - sending permission denied
    console.log('Tokens do not match');
    res.sendStatus(403);
  }
}

Verifica i messaggi in arrivo

Poiché i webhook possono ricevere messaggi da qualsiasi mittente, devi verificare che Google abbia inviato messaggi in arrivo prima di elaborare i contenuti dei messaggi.

Per verificare che Google abbia inviato un messaggio che hai ricevuto, segui questi passaggi:

  1. Estrai l'intestazione X-Goog-Signature del messaggio. Questa è una copia sottoposta ad hashing e codificata in Base64 del payload del corpo del messaggio.
  2. Decodifica in base 64 il payload RBM nell'elemento message.body della richiesta.
  3. Utilizzando come chiave il token client del webhook (specificato al momento della configurazione della sottoscrizione push), crea un HMAC SHA512 dei byte del payload del messaggio decodificato in base-64 e codifica il risultato in base64.
  4. Confronta l'hash X-Goog-Signature con l'hash che hai creato.
    • Se gli hash corrispondono, significa che Google ha inviato il messaggio.

    • Se gli hash non corrispondono, controlla la procedura di hashing su un messaggio noto.

      Se la procedura di hashing funziona correttamente e ricevi un messaggio che a tuo parere ti è stato inviato in modo fraudolento, contattaci.

Node.js

if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
  // Validate the received hash to ensure the message came from Google RBM
  let userEventString = Buffer.from(requestBody.message.data, 'base64');
  let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
  let data = hmac.update(userEventString);
  let genHash = data.digest('base64');
  let headerHash = req.header('X-Goog-Signature');

  if (headerHash === genHash) {
    let userEvent = JSON.parse(userEventString);

    console.log('userEventString: ' + userEventString);
    handleMessage(userEvent);
  }
  else {
    console.log('hash mismatch - ignoring message');
  }
}

res.sendStatus(200);

Passaggi successivi

Dopo aver configurato la sottoscrizione e impostato l'agente per comunicare con Cloud Pub/Sub, l'agente può ricevere messaggi dai tuoi dispositivi di test. Invia un messaggio per convalidare la configurazione.