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 e a empresa do cliente que desejar e, na URL de direcionamento, 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 o seu próprio CLIENT_ID e SUBDOMAIN, cole-a numa nova aba do navegador e pressione Enter.

https://www.zopim.com/oauth2/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: o subdomínio do Zendesk; ex. se sua conta está em niall.zendesk.com, o valor é 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. Visite https://www.zopim.com/oauth2/authorizations/new e adicione alguns parâmetros de consulta para passar algumas das informações acima. Dessa vez precisaremos de:

  • response_type: esse será sempre o código
  • redirect_uri: para onde será redirecionado após a concessão do acesso, http://localhost:8080 para o nosso tutorial
  • client_id: específico para você, conforme escrevemos anteriormente
  • scope: qual acesso que esse token terá, escolheremos entre read e write
    • Também inclui o escopo ''chat'' se estiver usado o token em relação à 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://www.zopim.com/oauth2/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: será sempre o authorization_code (código de autorização)
  • code: código que será obtido após permitirmos o acesso a partir da URL
  • client_id: a 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 (leitura e gravação).

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

curl https://www.zopim.com/oauth2/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

Lembre-se: você já tem a CLIENT_ID (ID do cliente) e CLIENT_SECRET, mas não temos ainda o AUTH_CODE (código de autorização).

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://www.zopim.com/oauth2/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 com o 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 a fazer é apenas um GET simples para /api/v2/chats para ver as informações de conta:

curl https://www.zopim.com/api/v2/chats -H "Authorization: Bearer TOKEN"

Substituindo TOKEN com o 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". Há dois outros tipos de concessão com suporte do Zendesk Chat: "password" e "client_credentials". A descrição detalhada deles você encontra na documentação de referência Tipos de concessão confidencial.

Para chamadas da API usadas por administradores e agentes para alguns itens, como métricas para relatórios, é recomendável a obter um token OAuth com um desses tipos de concessão. É necessário que você defina 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://www.zopim.com/api/v2/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 uma ID do cliente, pode executar a chamada com cURL a seguir para atualizar a propriedade client_type:

curl https://www.zopim.com/api/v2/oauth/clients/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