Como chamar a Twilio Functions a partir de um plugin Flex

A Twilio está lançando um novo Console. Algumas capturas de tela nesta página podem mostrar o Console legado e, portanto, podem não ser mais precisas. Estamos trabalhando para atualizar todas as capturas de tela para refletir a nova experiência do Console. Saiba mais sobre o novo Console.

Este é um guia sobre como chamar com segurança uma Twilio Function a partir de um plugin Flex. Este tutorial foi criado a partir do plugin Início rápido de desenvolvimento de plugin.

O Flex fornece alguns endpoints comuns do SDK que você pode usar, mas não disponibiliza todas as APIs do Twilio para você. Felizmente, você pode usar as Twilio Functions para decidir exatamente quais APIs do Twilio você precisa, fazer solicitações e retornar os resultados ao Flex.

Este tutorial requer que você tenha um plugin Flex existente. Você escreverá uma Twilio Function que recebe as estatísticas cumulativas de todos os funcionários em um Workspace e transmite esses dados para seu plugin Flex.

Atualmente, os plugins do Flex só podem fazer solicitações application/x-www-form-urlencoded para as Twilio Functions. Objetos aninhados não são suportados.

Vamos começar!

Criar uma Twilio Function

Primeiro, você precisará escrever uma Twilio Function. A função abaixo retorna estatísticas cumulativas de um Workspace do TaskRouter usando a Biblioteca auxiliar NodeJS.

Vá para página do Console do Twilio Functions. Você pode criar um novo Serviço ou usar um Serviço que já tenha. Adicione uma função e cole o seguinte código nela:

exports.handler = function(context, event, callback) {
  // Add the NodeJS Helper Library by calling context.getTwilioClient()
  const client = context.getTwilioClient();

  // Create a custom Twilio Response
  // Set the CORS headers to allow Flex to make an HTTP request to the Twilio Function
  const response = new Twilio.Response();
  response.appendHeader('Access-Control-Allow-Origin', '*');
  response.appendHeader('Access-Control-Allow-Methods', 'OPTIONS, POST, GET');
  response.appendHeader('Access-Control-Allow-Headers', 'Content-Type');

  // Use the NodeJS Helper Library to make an API call.
  // Note how you are passing the workspace SID using a key from the event parameter.
  client.taskrouter.v1
    .workspaces(event.WorkspaceSid)
    .workers()
    .cumulativeStatistics()
    .fetch()
    .then(data => {
        response.appendHeader('Content-Type', 'application/json');
        response.setBody(data);
        // Return a success response using the callback function.
        callback(null, response);
    })
    .catch(err => {
        response.appendHeader('Content-Type', 'plain/text');
        response.setBody(err.message);
        response.setStatusCode(500);
        // If there's an error, send an error response
        // Keep using the response object for CORS purposes
        callback(null, response);
    });
};

Nomeie sua Function com algo significativo, como o Relatório Cumulativo, e dê a ela o URI /cumulative (cumulativo). Antes de salvar, certifique‐se de que a caixa de seleção Check for valid Twilio signature (Verificar assinatura válida do Twilio) esteja desmarcada; voltaremos a ver como proteger sua função mais tarde. Agora, salve sua Function e aguarde até que ela seja implantada.

Tenho minha Function. Como faço uma chamada à ela no meu plugin?

Configure e teste sua Function

Visite a página Configuração das Functions e verifique se a opção Enable ACCOUNT_SID e AUTH_TOKEN está marcada. A ativação dessa caixa de seleção permite que context.getTwilioClient(); gere um novo cliente Twilio usando as credenciais da sua conta. Salve a página.

Agora, teste sua Function. Seu domínio será uma string hifenizada de palavras e números aleatórios e pode ser encontrado na parte superior do Editor de Function. Você pode encontrar o SID do seu Workspace acessando a página TaskRouter Workspaces.

Visite o URL da Function usando o navegador de sua escolha. Adicione o parâmetro de consulta ?WorkspaceSid=WSxxxe o navegador deve fazer uma solicitação GET à sua Function. Por exemplo, visitando

https://YOUR_DOMAIN.twil.io/cumulative?WorkspaceSid=WSxxx

deve renderizar:

{
  ...
  "activityDurations": [{
    "avg": 900,
    "min": 900,
    "max": 900,
    "friendly_name": "Available",
    "sid": "WAxxx",
    "total": 900
  }, 
  ...
  ]
  "reservationsCreated": 0,
  "reservationsAccepted": 0,
  "reservationsRejected": 0,
  "reservationsTimedOut": 0,
  "reservationsCanceled": 0,
  "reservationsRescinded": 0
  ...
}

Chame sua função de um plugin Flex

Para obter esses dados no Flex, você precisará modificar seu código de plugin usando o Criador de plugins. No editor de texto de sua escolha, abra a pasta que contém o plugin.

Para saber como criar seu primeiro plugin, consulte Início rápido do Twilio Flex (Avançado): Introdução ao desenvolvimento de plugin em React.

Em algum lugar do seu plugin, você precisará fazer uma chamada para sua Function. Você pode usar a API Web de busca nativa para fazer uma solicitação para sua função.

Para o nosso plugin, vamos alterar a solicitação GET para uma solicitação POST. Mesmo que, em última análise, recuperemos dados sobre o Workspace do TaskRouter, o plugin está chamando uma Function, não recuperando os dados diretamente. Como podemos querer enviar muitos dados em algum momento, o uso de uma solicitação POST também pode ser melhor. Finalmente, os corpos da solicitação POST são mais fáceis de trabalhar do que os parâmetros de consulta.

Para um plugin chamado YourPlugin, veja como YourPlugin.js pode parecer:

import { FlexPlugin } from 'flex-plugin';
import React from 'react';

const PLUGIN_NAME = 'YourPlugin';

export default class YourPlugin extends FlexPlugin {
  constructor() {
    super(PLUGIN_NAME);
  }

  /**
   * This code is run when your plugin is being started
   * Use this to modify any UI components or attach to the actions framework
   *
   * @param flex { typeof import('@twilio/flex-ui') }
   * @param manager { import('@twilio/flex-ui').Manager }
   */

  init(flex, manager) {
    // Describe the body of your request
    const body = { WorkspaceSid: 'WSxxx' };

    // Set up the HTTP options for your request
    const options = {
      method: 'POST',
      body: new URLSearchParams(body),
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
      }
    };

    // Make the network request using the Fetch API
    fetch('https://YOUR_DOMAIN.twil.io/cumulative', options)
      .then(resp => resp.json())
      .then(data => console.log(data));
  }
}

Quando você executa o plugin, deve ver a resposta da API registrada no console do navegador!

Aguarde um segundo... Isso não parece muito seguro.

Protegendo as Twilio Functions

Sua função está publicamente acessível, então qualquer pessoa na Internet pode chamá‐la! No entanto, não precisa se preocupar: você pode protegê‐la usando o JSON Web Token (JWT) da sua instância Flex e, em seguida, validar o token dentro de sua Function.

Atualize o código fetch para incluir também o JWT no corpo da solicitação:

import { FlexPlugin } from 'flex-plugin';
import React from 'react';

const PLUGIN_NAME = 'YourPlugin';

export default class YourPlugin extends FlexPlugin {
  constructor() {
    super(PLUGIN_NAME);
  }

  /**
   * This code is run when your plugin is being started
   * Use this to modify any UI components or attach to the actions framework
   *
   * @param flex { typeof import('@twilio/flex-ui') }
   * @param manager { import('@twilio/flex-ui').Manager }
   */

  init(flex, manager) {
    // Add the Token using the Flex manager
    const body = {
      WorkspaceSid: 'WSxxx',
      Token: manager.store.getState().flex.session.ssoTokenPayload.token
    };

    const options = {
      method: 'POST',
      body: new URLSearchParams(body),
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8'
      }
    };

    fetch('https://YOUR_DOMAIN.twil.io/cumulative', options)
    .then(resp => resp.json())
    .then(data => console.log(data));
  }
}

Observe que a única coisa alterada aqui é a adição da chave Token no parâmetro body.

Agora, é fácil atualizar sua função para que ela possa verificar esse token. Visite a página Configuração de Functions e role até a parte inferior da página. Visite a página package twilio-flex-token-validator no registro do npm para encontrar a versão atual do pacote. Depois de conhecer a versão, adicione twilio-flex-token-validator e sua versão atual em Dependencies. Salve a página.

Retorne à sua função cumulativa e importe functionValidator do módulo twilio-flex-token-validator. Em seguida, envolva sua Function com ela:

const TokenValidator = require('twilio-flex-token-validator').functionValidator;

exports.handler = TokenValidator(function(context, event, callback) {
    // Add the NodeJS Helper Library by calling context.getTwilioClient()
  const client = context.getTwilioClient();

  // Create a custom Twilio Response
  // Set the CORS headers to allow Flex to make an HTTP request to the Twilio Function
  const response = new Twilio.Response();
  response.appendHeader('Access-Control-Allow-Origin', '*');
  response.appendHeader('Access-Control-Allow-Methods', 'OPTIONS POST GET');
  response.appendHeader('Access-Control-Allow-Headers', 'Content-Type');

  // Use the NodeJS Helper Library to make an API call.
  // Note how you are passing the workspace SID using a key from the event parameter.
  client.taskrouter.v1
    .workspaces(event.WorkspaceSid)
    .workers()
    .cumulativeStatistics()
    .fetch()
    .then(data => {
        response.appendHeader('Content-Type', 'application/json');
        response.setBody(data);
        // Return a success response using the callback function.
        callback(null, response);
    })
    .catch(err => {
        response.appendHeader('Content-Type', 'plain/text');
        response.setBody(err.message);
        response.setStatusCode(500);
        // If there's an error, send an error response
        // Keep using the response object for CORS purposes
        callback(null, response);
    });
});

O TokenValidator lê o parâmetro Token e o valida. Se o token for inválido, o validador responderá com um 403. Se o token for válido, seu código será executado.

Parabéns! Agora você tem uma Function segura que pode chamar do seu plugin do Flex!

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.