Guia de Configuração do Menu Dinâmico 55PBX

Introdução ao Menu Dinâmico 55PBX

O Menu Dinâmico 55PBX é uma poderosa ferramenta que permite a criação de menus interativos adaptáveis a diversas necessidades de comunicação. Este guia passo a passo fornece instruções detalhadas sobre como configurar e utilizar esta funcionalidade, visando melhorar a experiência de atendimento ao cliente por meio de menus personalizados.

Primeiros Passos

Para iniciar, a criação de um menu dinâmico é acessada através do menu de opções "Integração", selecionando a opção "Padrão 55PBX". Este padrão permite a configuração de itens essenciais como:

● Método de Url;
● Tipo;
● URL;
● Configurar variáveis de envio;

Configuração dos Métodos de URL

Os métodos de URL definem como as requisições serão feitas para um determinado recurso. Eles incluem:

• GET: Solicita a representação de um recurso.
• POST: Cria um recurso com os dados fornecidos.
• PUT: Atualiza ou cria um recurso na URL especificada.
• PATCH: Atualiza parcialmente um recurso.
• DELETE: Exclui o recurso especificado.

Autenticação e Tipos de Requisição

Na seção "Tipo", você pode definir o tipo de autenticação necessária para a requisição:

Token: Requer a inserção de um Header e Token específicos. 

Em Header é possível definir o nome do header que receberá o valor do Token, exemplo:
Authorization, x-api-key, etc:

Obs: Esses valores são normalmente informados nas instruções da API.

Em Token deve ser informado o valor do token de autenticação. É possível digitar um token fixo ou utilizar um token dinâmico através de uma variável de resposta(normalmente obtida em outra consulta de menu dinâmico) ao selecionar o checkbox “Utilizar variável de resposta”:

Obs: Para utilizar uma variável de resposta como token, primeiro é necessário declará-la
em + Variável de resposta: 

Bearer Token: Similar ao Token, mas adiciona o prefixo "Bearer". 

O funcionamento do tipo de autenticação Bearer Token é muito parecido com o tipo Token,a única diferença é que no momento em que a requisição é efetuada, o texto “Bearer” é adicionado antes do Token:

Dessa forma, com base no exemplo acima, o envio do Header de autenticação ficaria da seguinte forma: 

Obs: As instruções de quando um token deve ser enviado como Bearer são normalmente informadas nas instruções da API.

Token Dinâmico: Permite a configuração de informações de autenticação no corpo da requisição. 

Determinadas solicitações não necessitam de um cabeçalho de autenticação, permitindo a transferência de informações por meio do corpo da solicitação. A configuração do corpo da solicitação pode ser realizada na seção "Configurar variáveis de envio".

Ao selecionar esta opção, um modal será exibido, permitindo a configuração do corpo da requisição e outros cabeçalhos. Para adicionar novos elementos, clique em "+Adicionar". 

Nota: Este módulo será descrito com mais detalhes em outra seção deste documento. 

Exemplo:

Para exemplificar, consideremos um cenário onde é necessário gerar um token de acesso para autenticar solicitações subsequentes. Este processo é executado por meio de uma requisição exemplar, descrita a seguir: 

URL (Endpoint): https://exemplo.com.br/v1/auth/token

Cabeçalhos: Não aplicável

Corpo da Requisição:

Com base nas especificações fornecidas, a configuração seria estabelecida da seguinte maneira: Configuração da URL: 

Configuração do Corpo: 

Autenticação por Usuário e Senha: Este método emprega credenciais de usuário para realizar a autenticação.

Quando a opção "Usuário e Senha" é escolhida, dois campos adicionais serão disponibilizados para preenchimento: "Usuário" e "Senha".

Para processos de autenticação que requerem usuário e senha, os dados devem ser inseridos nos campos designados para cada informação. 

URL

Este campo destina-se à especificação do Endpoint, ou seja, a URL pela qual um serviço pode ser acessado mediante requisições. 

Variáveis da 55PBX podem ser integradas à URL especificada, precedendo o nome da variável com o caractere de dois pontos:

Para inserir uma variável na URL, é necessário declará-la previamente na seção "Configurar variáveis de envio". Isso é feito ao especificar o nome da variável nos campos "Variável 55PBX" e "Variável do Sistema", conforme indicado:

Exemplo:

No exemplo apresentado, configura-se um menu dinâmico para realizar uma consulta de ticket no Zendesk, utilizando o Padrão 55PBX. Isso é feito com base em um número de protocolo inserido via URA e armazenado sob uma determinada máscara. 

Endpoint

Para localizar um ticket específico no Zendesk, insira o número do ticket desejado ao final da URL de busca. 

Nota: O exemplo mencionado foi aplicado utilizando o sistema Zendesk da PBX

https://instancia.zendesk.com/api/v2/tickets/{id_do_ticket}

1 -  O identificador do ticket é registrado sob o nome de "protocolo". 

2 - O menu dinâmico Padrão 55PBX é configurado inserindo-se a variável "protocolo" no campo URL, precedida pelo caractere dois pontos.

3 - No menu dinâmico, dentro da seção "Configurar variáveis de envio", a variável é declarada em ambos os campos disponíveis.  

Com a configuração estabelecida, ao inserir um número de protocolo na Unidade de Resposta Audível (URA), o termo "protocolo" será automaticamente substituído pelo número fornecido, permitindo que a solicitação seja processada adequadamente. 

Exemplo: Ilustração do formato da URL com a inserção do número 5:

https://instancia.zendesk.com/api/v2/tickets/5

Portanto, conforme ilustrado no exemplo anterior, a pesquisa de ticket será dinâmica, gerando um resultado único para cada número de protocolo inserido na Unidade de Resposta Audível (URA). 

Ajuste de Variáveis de Envio

Selecionando a opção "Configurar variáveis de envio", será apresentada uma janela modal que permite a configuração do corpo da requisição e de outros cabeçalhos, através da funcionalidade "+Adicionar".

Nota: O campo "Variável 55PBX" suporta a inserção de textos fixos e variáveis.

• Para empregar uma variável, é necessário especificar seu nome. 

• Para especificar um texto, insira seu valor entre dois símbolos de porcentagem. 

Configuração de Header

Para configurar um Header, siga os passos abaixo:

Insira o nome do Header no campo "Variável do Sistema";

Insira o valor do Header no campo "Variável 55PBX";

Ative a opção "Utilizar como Header" marcando a caixa correspondente.

Exemplo:

Corpo (Body)

Utilizando o Padrão 55PBX, é possível configurar dois tipos de corpo de requisição: JSON e form-urlencoded.

JSON

Para definir o conteúdo do corpo a ser enviado, é necessário especificar o nome da propriedade no campo "Variável do Sistema" e o seu valor correspondente no campo "Variável 55PBX".

Por padrão, a configuração das variáveis é projetada para suportar o envio de JSON em formato simples, excluindo objetos e arrays, focando unicamente nas propriedades do JSON. 

Os exemplos abaixo ilustram um formato de JSON que pode ser configurado através do menu: 

JSON inválido:
{
"nome": "Fulano de Tal",
"email": [
"contato@55pbx.com",
"fulano@55pbx.com"
],
"telefone": {
"tipo": "celular",
"numero": "5511996523259"
}
}

JSON válido
{
"nome": "Fulano de Tal",
"email": "fulano@55pbx.com",
"telefone":"5511996523259"
}

O exemplo subsequente apresenta o procedimento de preenchimento utilizando como referência o JSON válido mencionado anteriormente: 

form-urlencoded

Para configurar um corpo como x-www-form-urlencoded, em configurar variáveis de envio, o checkbox x-www-form-urlencoded deve ser ativado:

Para definir um corpo de requisição como x-www-form-urlencoded, na seção de configuração das variáveis de envio, a opção x-www-form-urlencoded deve ser selecionada.

Retornos

Após a execução de uma solicitação de busca, atualização ou modificação, espera-se o recebimento de uma resposta em formato JSON pela Unidade de Resposta Audível (URA), contendo diversos elementos de informação relevantes à operação realizada. É possível integrar os dados obtidos nesse JSON na URA ao designá-los como Variáveis de Resposta.

Para empregar essas variáveis na URA, deve-se especificar o nome do atributo que se pretende acessar, antecedendo-o com o prefixo "55pbx". As palavras devem ser conectadas utilizando o caractere sublinhado (_) para separação.

Exemplo

Considerando a execução de uma pesquisa de usuário em um sistema específico, utilizando seu número de telefone como critério de busca, os dados a seguir foram obtidos como resultado:

{
"nome": "Fulano de Tal",
"email": [
"contato@55pbx.com",
"fulano@55pbx.com"
],
"telefone": {
"tipo": "celular",
"numero": "5511996523259"
}
}

Acesso a Propriedade Simples:

Para manipular uma variável simples, que não está incorporada em um objeto ou array, é necessário identificar seu nome, antecipando-o com o prefixo "55pbx". A título de exemplo, a variável "nome" é declarada conforme demonstrado abaixo, com base no JSON previamente mencionado:

Acessando array(arranjo)

Ao trabalhar com array, além de incluir o texto 55pbx e separar as palavras com underline, é necessário indicar a posição do dado que desejamos acessar dentro do array. No exemplo a seguir, acessamos o primeiro e-mail do array através do número 0 e o declaramos como uma variável de resposta:

Neste caso, o e-mail que estará disponível através da variável 55pbx_email_0 é o:
contato@55pbx.com

Acessando array de objetos

Acesso a Propriedades de Objetos em Arrays:

Para acessar propriedades de objetos localizados dentro de arrays, é necessário primeiro indicar a posição do elemento no array e, em seguida, especificar o nome da propriedade desejada, utilizando o sublinhado (_) como separador. A seguir, apresentamos um exemplo com um JSON fictício que ilustra o retorno dos e-mails de um contato:

{
"email":[
{
"tipo": "casa",
"endereco": "contato@55pbx.com.br"
},
{
"tipo": "trabalho",
"endereco": "fulano@55pbx.com.br"
}
]
}

Tendo como referência o exemplo fornecido, para declarar uma variável que armazene o tipo do primeiro e-mail presente no array, a formatação seria realizada da seguinte maneira:

Nota: A primeira posição dos arrays sempre tem índice 0. 

Acessando objetos

Para acessar e declarar dados de um objeto, utilize o nome do objeto seguido pelo nome de sua propriedade, separados por underline, conforme as especificações previamente indicadas. No exemplo abaixo, é declarada a variável "tipo" do objeto "telefone" com base no JSON fornecido como exemplo.