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

Modificado em Tue, 12 Mar 2024 na (o) 04:29 PM

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. 





Este artigo foi útil?

Que bom!

Obrigado pelo seu feedback

Desculpe! Não conseguimos ajudar você

Obrigado pelo seu feedback

Deixe-nos saber como podemos melhorar este artigo!

Selecione pelo menos um dos motivos
A verificação do CAPTCHA é obrigatória.

Feedback enviado

Agradecemos seu esforço e tentaremos corrigir o artigo