Como usar a API de Chat no Zendesk: Um guia passo a passo

Então, está a pensar em construir uma integração personalizada, extrair alguns dados de chat para um relatório ou automatizar alguns fluxos de trabalho no Zendesk. É um excelente objetivo. Usar a API dá-lhe o poder de realmente moldar a plataforma à sua vontade.

Mas sejamos realistas por um segundo. Descobrir por onde começar com as APIs do Zendesk pode parecer um pesadelo. Tem o clássico Live Chat, a plataforma mais recente de Messaging e uma vasta gama de APIs diferentes para escolher: REST, Real-Time, Conversations… é o suficiente para dar vontade de fechar o separador do navegador antes mesmo de escrever uma única linha de código.

Se isto lhe soa familiar, está no lugar certo. Este guia está aqui para simplificar as coisas. Vamos percorrer um processo simples e passo a passo para usar a API de Chat clássica que o Zendesk oferece. Vamos esclarecer a confusão e levá-lo de coçar a cabeça a fazer a sua primeira chamada de API com sucesso.

O que precisa para começar com a API de Chat da Zendesk

Antes de arregaçarmos as mangas e mergulharmos no código, vamos fazer uma verificação rápida para garantir que tem tudo o que precisa. Tratar disto agora irá poupar-lhe muitas dores de cabeça mais tarde.

Aqui está uma lista de verificação rápida:

• Uma conta Zendesk com acesso à API. Isto está geralmente disponível nos planos Zendesk Suite Team e superiores. Se não tiver a certeza de qual é o seu plano, vale a pena dar uma olhada nos detalhes da sua subscrição para confirmar.

• Permissões de administrador. Precisará de ser administrador na sua conta Zendesk para gerar as chaves de API. Se não for administrador, terá de encontrar a pessoa que é e pedir-lhe educadamente para o ajudar.

• Um cliente de API. Precisará de uma forma de enviar pedidos para a API. Uma ferramenta como o Postman é fantástica para isto, porque permite testar chamadas de API com uma interface fácil de usar em vez de escrever código imediatamente. Em alternativa, pode usar o cURL diretamente no terminal do seu computador ou saltar diretamente para a sua linguagem de programação favorita.

• Conhecimentos básicos de APIs REST. Não precisa de ser um especialista, mas ter uma familiaridade com ideias como endpoints, pedidos GET e cabeçalhos de autorização tornará este processo muito mais suave.

Um guia passo a passo para usar a API de Chat da Zendesk

Muito bem, agora que tem todas as suas ferramentas prontas, vamos ao que interessa. Começaremos por dar sentido ao panorama do Zendesk e depois vamos sujar as mãos com uma chamada de API real.

Passo 1: Compreender o panorama da API de Chat da Zendesk (Chat vs. Messaging)

Honestamente, o maior ponto de confusão para qualquer pessoa que começa com as APIs do Zendesk é a diferença entre os seus dois produtos de chat: Live Chat e Messaging. Parecem semelhantes, mas por baixo do capô, são duas coisas completamente diferentes que usam conjuntos de APIs totalmente distintos. Esclarecer isto desde o início é fundamental.

Zendesk Live Chat (O Clássico)

Este é o produto de chat original, baseado em sessões, com o qual muitos de nós estamos familiarizados (costumava chamar-se Zopim). Pense nele como uma chamada telefónica: um cliente inicia um chat, é uma conversa ao vivo, em tempo real, e termina quando ele fecha a janela. Este produto usa um conjunto específico de APIs, incluindo a API REST de Chat, que é o que vamos focar neste guia. Estas APIs são construídas para gerir essas conversas em tempo real, lidar com agentes e extrair registos de chat históricos deste sistema clássico.

Zendesk Messaging

Esta é a abordagem mais recente e omnicanal do Zendesk. Foi construída para conversas assíncronas, o que é mais parecido com mensagens de texto ou WhatsApp. Um cliente pode enviar uma mensagem do seu site, aplicação móvel ou até mesmo do Facebook Messenger, e depois voltar mais tarde para ver a resposta. Aqui está a parte fundamental: o Messaging não usa as APIs de Chat clássicas de todo. Em vez disso, baseia-se num kit de ferramentas de desenvolvimento diferente, incluindo coisas como Sunshine Conversations e webhooks para dados em tempo real.

Esta divisão é uma verdadeira dor de cabeça para equipas que tentam construir automações unificadas. Gerir dois modelos de API completamente diferentes é complicado e pode consumir muito tempo e recursos. É uma razão comum pela qual tantos destes projetos ficam presos no desenvolvimento. É também exatamente por isso que plataformas como a eesel AI existem. Ela fornece uma integração de um clique com o Zendesk que se conecta a todos os dados do seu helpdesk, quer venham do Chat clássico ou do Messaging moderno. Isto permite-lhe construir agentes de IA inteligentes sem ter de se preocupar com qual API deveria estar a usar.

Passo 2: Escolher a API certa para o seu objetivo

Mesmo no mundo do Live Chat da velha guarda, o Zendesk oferece algumas APIs diferentes, cada uma projetada para uma tarefa específica. Escolher a certa desde o início evitará que ande às voltas.

Aqui está um resumo rápido das suas opções:

• API REST de Chat: Esta é a ferramenta principal que usará para a maioria das coisas. Usá-la-ia para obter programaticamente dados de chat históricos, buscar transcrições, gerir os seus agentes e atualizar informações do chat após o término de uma conversa. Usaremos esta API no nosso exemplo abaixo.

• API de Chat em Tempo Real: Esta é uma API de streaming construída para monitorizar o que está a acontecer agora mesmo. Se precisa de construir um painel que mostre quantos chats estão ativos ou quais agentes estão online neste exato segundo, esta é a API que quer.

• API de Conversas (GraphQL): Esta API foi originalmente projetada para construir aplicações que pudessem agir como agentes, como chatbots personalizados. No entanto, o Zendesk colocou esta API em modo de manutenção e já não está disponível para novas integrações. Para qualquer novo projeto, deve evitar esta.

• SDK Web: Esta não é uma API típica, mas sim uma biblioteca JavaScript que reside do lado do cliente. Dá-lhe o poder de construir um widget de chat completamente personalizado para o seu site, dando-lhe controlo total sobre a aparência, sensação e experiência do utilizador.

Para tornar tudo ainda mais claro, aqui está uma tabela simples para o ajudar a decidir:

Passo 3: Gerar as suas credenciais de API

Para comunicar com a API de forma segura, o seu código precisa de provar que tem permissão. A forma padrão de fazer isto é criando um cliente OAuth no seu painel do Zendesk Chat, o que lhe dará as credenciais necessárias para gerar um token de acesso.

Veja como fazer:

1. Vá para o seu painel do Zendesk Chat. Normalmente, pode encontrá-lo no tabuleiro de produtos (o ícone de quatro quadrados) na sua conta principal do Zendesk Support.

2. No menu à esquerda, navegue para Definições > Conta e clique no separador API e SDKs.

3. Clique no grande botão Adicionar Cliente de API.

4. Verá um formulário. Dê ao seu cliente um Nome de Cliente memorável (algo como "Integração de Dados de Chat" funciona bem) e preencha o nome da sua Empresa. Para os URLs de Redirecionamento, pode simplesmente inserir "https://localhost" por agora. Isto é um marcador de posição que é necessário para o fluxo de autenticação, e está perfeitamente bem para o que estamos a fazer hoje.

5. Depois de criar o cliente, o Zendesk mostrar-lhe-á um ID do Cliente e um Segredo do Cliente. Copie o Segredo do Cliente e guarde-o num local seguro, como um gestor de palavras-passe. Esta é a sua única oportunidade de o ver.

6. Estas credenciais são usadas num processo chamado fluxo de autorização OAuth para obter um token de portador temporário. Para manter este guia simples, vamos avançar rapidamente e assumir que gerou um token de acesso para usar diretamente nos seus pedidos.

Passo 4: Fazer a sua primeira chamada de API

E agora, o momento da verdade. Vamos usar as credenciais que acabou de gerar para extrair alguns dados reais da sua conta. O nosso objetivo é simples: obter uma lista dos seus chats mais recentes.

O Endpoint

O endpoint da API é simplesmente o URL para o qual envia o seu pedido. Para obter uma lista de todos os chats, o endpoint é "GET /api/v2/chats".

Autenticação

Cada pedido que envia precisa de ser autenticado para provar que é você. Faz isto incluindo o seu token de acesso num cabeçalho de "Authorization". O formato é simples: "Authorization: Bearer SEU_TOKEN_DE_ACESSO".

Juntando Tudo (Exemplo com cURL)

Usar o cURL a partir do seu terminal é uma das formas mais rápidas de testar uma API sem complicações. Abra o seu terminal, substitua SEU_TOKEN_DE_ACESSO pelo token real que tem e execute este comando:

"`bash

curl https://www.zopim.com/api/v2/chats \

-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

"`

Se tudo foi configurado corretamente, o servidor do Zendesk deverá responder com um monte de texto formatado em JSON contendo uma lista dos seus chats.

Exemplo de Resposta

A resposta será uma matriz JSON de objetos de chat. Aqui está um trecho simplificado do que isso pode parecer:

"`json

{

"chats": [

{  

  "id": "1A2B3C4D5E",  

  "visitor": {  

    "name": "Jane Doe",  

    "email": "jane.doe@example.com"  

  },  

  "history": [  

    {  

      "type": "chat.msg",  

      "display_name": "Jane Doe",  

      "msg": "Olá, tenho uma pergunta sobre o meu pedido recente.",  

      "timestamp": 1678886400000  

    },  

    {  

      "type": "chat.msg",  

      "display_name": "Agente de Suporte",  

      "msg": "Olá Jane, terei todo o prazer em ajudar com isso!",  

      "timestamp": 1678886460000  

    }  

  ],  

  "timestamp": "2023-03-15T12:00:00Z"  

}  

],

"count": 1

}

"`

E assim, conseguiu! Usou com sucesso a API de Chat que o Zendesk oferece para buscar dados reais. Pode ver todo o tipo de informações úteis aqui, como o ID do chat, detalhes do visitante e o histórico completo da conversa com carimbos de data/hora.

Erros comuns a evitar ao trabalhar com a API de Chat da Zendesk

Fazer a sua primeira chamada de API funcionar é um ótimo primeiro passo, mas à medida que começa a construir integrações mais avançadas, existem algumas armadilhas comuns em que é fácil cair. Aqui ficam alguns conselhos amigáveis para o ajudar a contorná-las.

• 1. Usar a API Errada para o Trabalho: Já o mencionámos algumas vezes, mas vale a pena repetir porque é o erro número um que as pessoas cometem. Antes de escrever uma linha de código, verifique duas vezes se o seu objetivo envolve o clássico Live Chat ou o moderno Messaging. Tentar obter dados do Messaging com a API de Chat simplesmente não vai funcionar e vai deixá-lo a perguntar-se porque é que nada aparece.

• 2. Ignorar os Limites de Taxa: Para manter o seu serviço estável para todos, a API de Chat do Zendesk tem um limite de taxa, que é tipicamente de cerca de 200 pedidos por minuto. Se ultrapassar este limite, receberá um erro "429 Too Many Requests". Uma boa prática é verificar sempre o cabeçalho "X-Rate-Limit-Remaining" na resposta da API para ver quantas chamadas ainda tem, e construir alguma lógica simples na sua aplicação para pausar se estiver a aproximar-se do limite.

• 3. Construir um Novo Projeto numa API Obsoleta: Como notámos anteriormente, a API de Conversas está em modo de manutenção. Pode parecer poderosa, mas começar um novo projeto numa API que o Zendesk já não está a desenvolver ativamente é preparar-se para ter problemas no futuro. Mantenha-se nas APIs ativamente suportadas para qualquer novo trabalho.

Estes tipos de desafios destacam os custos ocultos da construção e manutenção de integrações personalizadas. Não é apenas o tempo inicial que leva a escrever o código; é o trabalho contínuo de lidar com erros, adaptar-se a alterações na API e gerir toda a manutenção técnica. É aqui que pode questionar se vale a pena construir do zero. Por uma pequena fração do esforço de engenharia, uma ferramenta como a eesel AI oferece um poderoso motor de simulação que lhe permite testar o desempenho da sua IA em milhares de tickets históricos antes que ela interaja com um cliente real. Pode implementar automação sofisticada com confiança e sem o risco de desenvolvimento.

Pule o código da API de Chat da Zendesk e automatize com IA

Parabéns! Conseguiu navegar pelo mundo por vezes confuso da API de Chat que o Zendesk oferece, desde a geração das suas credenciais até à extração de dados reais. Essa é uma base sólida para construir quaisquer ferramentas personalizadas que tenha em mente.

No entanto, se o seu objetivo final é automatizar resoluções, tornar os seus agentes mais eficientes e dar respostas instantâneas aos clientes, construir tudo por conta própria é um longo caminho que requer muito tempo de desenvolvimento. Há uma maneira muito mais rápida de lá chegar.

eesel AI liga-se diretamente à sua instância do Zendesk em apenas alguns minutos, dando-lhe um conjunto completo de ferramentas de IA prontas a usar. Desde um agente autónomo que pode resolver tickets por conta própria até um Copiloto de IA que dá superpoderes aos seus agentes humanos, pode estar a funcionar em minutos, não em meses. Obtém todos os benefícios de uma automação poderosa sem as dores de cabeça da engenharia.

Um Copiloto de IA a redigir uma resposta no Zendesk, uma alternativa à programação com a API de Chat da Zendesk.

Comece hoje o seu teste gratuito.