Para usar a API do Chat nas contas do Support+Chat e nas contas do Chat na fase 4, é necessário gerar um token de acesso OAuth para autenticar as solicitações da API. Não há suporte para autenticação básica. No entanto, gerar um token pela primeira vez pode ser um pouco confuso, portanto, criamos este tutorial com exemplos do passo a passo de como gerar um token manualmente. Ao concluir o procedimento, você terá um token que usa nas solicitações da API do Chat para a leitura e gravação de dados.

Se você está desenvolvendo um aplicativo, deve criar a funcionalidade que gera um token em seu aplicativo para automatizar o processo.

Há duas maneiras de criar um token de acesso para a API do Chat: a mais rápida e conveniente para ambientes de teste (usando o fluxo de concessão "Implícita") e a mais longa e formal para ambientes de produção (usando o fluxo de concessão do "Código de Autorização"). Este tutorial aborda as duas.

Condições

Este tutorial é voltado para as contas do Chat integrado que passaram por todas as mudanças mencionadas no artigo anterior. Isso está sendo implementado gradualmente, então algumas contas podem requerer essa configuração antes que as outras. Se você não sabe se sua conta recebeu as mudanças, entre em contato com a equipe de suporte, que poderá confirmar essa informação para você.

Observação: um efeito colateral das mudanças de conta é que os tokens OAuth precisarão ser recriados. Se você concluir este tutorial antes de as mudanças chegarem em sua conta, precisará executar todas as etapas novamente em um momento posterior.

Procedimento

O fluxo de concessão "Implícita" do OAuth tem as etapas a seguir:

  1. Crie o cliente de API OAuth
  2. Conclua o fluxo de concessão "Implícita" do OAuth para obter o token usando as informações da etapa 1.

Crie o cliente de API OAuth

Primeiramente, precisaremos de um cliente de API. Visite Zendesk Chat > Conta > API e SDKs e clique no botão Adicionar cliente de API. Insira um nome para o cliente e a empresa de sua escolha e, para a URL de redirecionamento, insira http://localhost:8080. Isso deve ter a seguinte aparência:

Clique em Criar cliente de API para concluir a configuração. Um pop-up será exibido com a ID do cliente e o segredo. Muito importante: o segredo do cliente é mostrado apenas uma vez, portanto anote-o para uso posterior. Ele terá esta aparência:

Agora que o nosso cliente de API está pronto, anote a ID e o segredo do cliente antes de clicar em Ok. Entendi. Agora estamos prontos para concluir o fluxo de concessão de OAuth.

Conclua o fluxo de concessão "Implícita" do OAuth para obter o token

Essa abordagem usa o fluxo de concessão "Implícita" do OAuth. Uma alternativa ao uso do fluxo de concessão do "Código de Autorização" do OAuth (mostrado na próxima seção). Se feita de modo manual, essa abordagem tem menos etapas e é mais conveniente do que a concessão de código de autorização mostrada anteriormente.

1. Siga a etapa "Criar o cliente de API OAuth" acima.

2. Colete estas informações do cliente OAuth:

  • ID do cliente: CLIENT_ID
  • Seu subdomínio do Zendesk

3. Formate a URL a seguir com seu próprio CLIENT_ID e SUBDOMAIN, cole-a em uma nova aba do navegador e pressione Enter.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

OBSERVAÇÕES:

  • Se o cliente de OAuth do Chat tem apenas um valor de URL de redirecionamento, então é opcional passar o valor redirect_uri. Por padrão, o sistema usará um valor de URL de redirecionamento do cliente OAuth.
  • Se o cliente de OAuth tiver mais de um valor de URL de redirecionamento, então é obrigatório passar o valor redirect_uri. Se um valor redirect_uri é passado, então a URL precisa estar codificada. No exemplo acima, o parâmetro de redirecionamento opcional seria: redirect_uri=http%3A%2F%2Flocalhost%3A8080

4. A chamada será feita e possivelmente solicitará que você entre e selecione ''Permitir'' para gerar o token.

Se a chamada for realizada, o campo do endereço do navegador irá conter seu novo token OAuth (retornado como o valor access_token).

Apesar de mensagem parecida com um erro ser exibida na janela principal do navegador, se o ''access_token'' for retornado no campo da URL do navegador, então funcionou!

A seguir, uma demonstração do fluxo de trabalho:

 

Uma maneira alternativa e mais longa de gerar o token

As etapas a seguir criam um token igual a seção anterior, mas mostram o fluxo de concessão do "Código de Autorização" do OAuth. Anote os detalhes do cliente OAuth, que serão usados a seguir.

Os placeholders serão usados em vez de dados reais e lembre-se de que o segredo do seu cliente OAuth deve ser guardado com máxima segurança, pois é basicamente uma senha para a conta do Chat.

  • ID do cliente: CLIENT_ID
  • Segredo do cliente: CLIENT_SECRET
  • URI de redirecionamento: http://localhost:8080
  • Subdomínio: seu subdomínio do Zendesk; por exemplo, se sua conta estiver em niall.zendesk.com, esse valor será niall
  • Código de autorização: ainda não o temos

1. Prepare a primeira URL

Criaremos aqui uma URL para solicitar um código de autorização. Acesse https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new e adicione alguns parâmetros de consulta para passar algumas das informações descritas anteriormente. Dessa vez precisaremos de:

  • response_type: sempre será code
  • redirect_uri: para onde será o redirecionamento depois de conceder acesso, http://localhost:8080 para o nosso tutorial
  • client_id: específico para você, conforme escrito anteriormente
  • scope: o acesso que esse token terá, escolheremos read e write
    • Também inclui o escopo ''chat'' se estiver usado o token na API de conversas do Chat.
  • subdomain: seu subdomínio do Zendesk

Ao juntar essas informações com a codificação da URL, você terá a URL final, que terá esta aparência:

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

com CLIENT_ID e SUBDOMAIN sendo as únicas diferenças para a sua própria URL.

2. Prepare a chamada com cURL

Antes de visitar essa URL, vamos criar a chamada com cURL que iremos executar posteriormente. Dessa vez precisaremos fazer o seguinte:

  • grant_type: sempre será authorization_code
  • code: será obtido após permitirmos o acesso por meio da URL
  • client_id: o ID do cliente
  • client_secret: o segredo do cliente
  • redirect_uri: o mesmo da última etapa - http://localhost:8080
  • scope: o mesmo da última etapa - read e write

Quando juntamos tudo, temos um comando com uma aparência semelhante a esta:

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Lembre-se: agora você já deve ter o CLIENT_ID e o CLIENT_SECRET, mas ainda não temos o AUTH_CODE.

3. Obtenha o código de autorização

Agora vá até a URL que geramos na etapa 1. Veremos uma página com esta aparência:

Clique em Permitir para conceder acesso e ser redirecionado para a URL de redirecionamento. Ela parecerá com uma página com link desfeito, mas o importante é observar a URL para ver o código de autorização, ou seja, tudo que vem depois de ?code=.

Copie esse código e vamos para a etapa final! O código de autorização é válido apenas por um curto período de tempo. Se você demorar alguns minutos, precisará executar novamente a etapa anterior para obter um novo valor de código.

4. Faça com que a chamada com cURL obtenha o seu token

Voltando para nossa chamada com cURL que criamos na etapa 2, que se parece com isto

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Substitua AUTH_CODE pelo código da etapa 3 e execute o comando em um aplicativo de terminal. Você receberá uma resposta na forma de um objeto JSON como este:

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. Teste seu novo token

É sempre bom testar tudo com para verificar se está funcionando como esperado, por isso faremos isso agora. A chamada mais fácil de fazer é um GET simples para /api/v2/chats para ver as informações da sua conta:

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

substituindo TOKEN pelo valor que recuperamos na etapa 4. 

Informações adicionais

client_type confidencial

As seções anteriores mostraram os tipos de concessão "Implícita" e do "Código de Autorização". A API do Chat também oferece suporte ao tipo de concessão confidencial usando as credenciais do cliente. A descrição detalhada você encontra na documentação de referência Confidential Grant Type.

Para chamadas de API usadas por administradores e agentes para alguns itens, como métricas de relatórios, pode ser preferível obter um token OAuth com o tipo de concessão confidencial. É necessário definir o client_type como "confidential" (confidencial). Por padrão, esse valor é definido como "public" (público). Isso pode ser feito apenas pela API e ser obtido da seguinte maneira:

1. Obtenha a ID do cliente

Primeiramente, precisaremos da ID do seu novo cliente. Você pode obter essa informação usando o seu novo token, com a chamada a seguir:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

Que mostrará todos os seus clientes. Você pode ter apenas um, mas caso tenha muitos, deve escolher o que deseja atualizar e anotar sua ID.

2. Atualize o client_type

Agora que você tem o ID do cliente, é possível executar a chamada com cURL a seguir para atualizar a propriedade client_type:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

Assim que concluído, seu token pode ser usado para pontos de extremidade restritos.

Powered by Zendesk