Uso de metadados de mensagens com SDKs e o Web Widget do Zendesk

Qual é o meu plano?

Suite

Qualquer plano

Os metadados de mensagens utilizam campos e tags de conversa (também conhecidos como campos de ticket personalizados e tags de ticket personalizadas) para coletar mais informações sobre o problema de suporte ou o produto ou serviço. Você também pode usar esses metadados para um melhor encaminhamento de tickets no Espaço de trabalho do agente, criando gatilhos na Central de administração. É possível adicionar metadados de mensagens aos tickets e incluí-los no formulário Enviar uma solicitação, na central de ajuda, se quiser que os usuários finais vejam os campos personalizados.

Você também pode utilizar campos e tags de conversa para enviar ao agente os metadados de mensagens de SDKs e do Web Widget do Zendesk por meio de APIs do lado do cliente. Isso permite a transferência automática de informações relevantes, como SKU do produto, número de confirmação ou ID do pedido, para o agente. Esses metadados adicionais ajudam a fornecer um contexto abrangente e a melhorar a qualidade do suporte prestado.

Os benefícios dos metadados de mensagens incluem:

• Contexto melhor para o agente. Os agentes dependem de informações contextuais corretas apresentadas na visualização do Espaço de trabalho do agente. Dados ausentes ou fornecidos pelo usuário final podem ser suscetíveis a erros. Fornecer informações relevantes de modo programático reduz os erros e o tempo gasto pedindo informações.
• Encaminhamento aprimorado. Os negócios dependem de informações nos campos e tags de ticket para encaminhar rapidamente o ticket ao grupo de agentes correto. Fornecer dados mais completos faz com que o encaminhamento do ticket ao grupo de agentes correto seja mais eficiente.
• Experiência otimizada para o usuário final. Os usuários finais não precisam inserir novamente dados já disponíveis no lado do cliente.
• Fluxos de automação aperfeiçoados. Os criadores de bots podem utilizar os dados adicionais para proporcionar uma melhor experiência aos usuários finais.
• Paridade de recursos com SDKs do Support para Web Widget (clássico), compatíveis com campos e tags de ticket.

Este artigo inclui os tópicos a seguir:

• Visão geral dos metadados de mensagens
• Configuração dos metadados de mensagens
• Adição de um campo de conversa
• Uso das APIs de metadados
• Criador de bots (agentes de IA legados)

Visão geral dos metadados de mensagens

Suponha que você tem uma loja online e um usuário final está procurando um sapato específico. Nessa página, estão o SKU do produto, o tamanho e as opções de cor. Quando o usuário final tem dúvidas sobre esse sapato, é necessário saber as informações mencionadas para que o agente saiba exatamente em qual sapato o usuário final tem interesse. Sem os campos de ticket personalizados, o agente em tempo real ou de IA deve solicitar todas essas informações ao usuário final antes de responder à pergunta.

Com os metadados de mensagens, você obtém esses dados de modo programático da página, solicitando que o usuário final preencha um formulário ou uma combinação disso. Por exemplo, usando um campo de ticket personalizado, você pode utilizar uma API para recuperar o SKU do produto da página do produto. Como o usuário final pode ter selecionado ou não a cor e o tamanho, um agente de IA, por exemplo, pode consultar essas informações usando campos de ticket personalizados e exibir os respectivos valores padrão. O usuário final pode atualizar os valores ou deixá-los como estão.

Esse processo é diferente de usar variáveis ​​e campos personalizados em respostas padrão do agente de IA ou no criador de bots (legado). Com os metadados de mensagens:

• Os usuários finais não precisam inserir manualmente os dados que existem na página que estão visitando. Por exemplo, se um usuário final estiver em um formulário de devolução de pedido e o ID do pedido existir nessa página, você poderá recuperar de modo programático esse número em vez de solicitar que o usuário final digite a informação.
• Contexto extra pode ser adicionado automaticamente para auxiliar o agente. Por exemplo, se um usuário final estiver com o carrinho aberto, você pode definir um campo de conversa “Carrinho ativo” como verdadeiro.
• É possível controlar o caminho que um agente de IA segue. Por exemplo, se um usuário final estiver em uma página da Marca A, você pode definir isso em um campo para que o bot percorra o caminho da Marca A.

Configuração dos metadados de mensagens

Os campos de conversa precisam ser configurados na Central de administração para permitir que seus valores sejam definidos por um usuário final quando os campos são criados. As tags de conversa não precisam de etapas prévias para que a API de metadados seja utilizada.

A primeira etapa para usar os metadados de mensagens é determinar os dados que você deseja coletar e como utilizá-los. Isso depende do seu caso de uso. Você precisa entender por completo a experiência do usuário final quando seu desenvolvedor definir os valores de campo e tag de ticket de modo programático no Web Widget e SDKs do Zendesk.

Assim que você tiver compreensão dos seus dados, as seguintes etapas são executadas:

1. Um administrador do Zendesk cria um campo de ticket personalizado e passa o nome do campo e o ID para um desenvolvedor, junto com o uso e os dados que deseja coletar.
2. Um desenvolvedor cria o código da chamada para a API de metadados usando o ID do campo para conectar o valor a esse campo.
3. Os dados são definidos de modo programático na API de metadados em tempo de execução e ficam disponíveis na próxima sessão.
4. Os dados de campo e tag de ticket são adicionados ao ticket de suporte no momento da criação do ticket.

Observação: os metadados de mensagens são aplicados apenas a um ticket. Se for criado um ticket subsequente relacionado à mesma conversa, os metadados de mensagens serão aplicados somente ao primeiro ticket.

Os metadados de campos e tags de ticket são aplicados ao ticket na criação dele. Por exemplo, se você configurar seu widget para conversar de imediato com um agente em tempo real (e não com um agente de IA), abrir o widget criará automaticamente um novo ticket e só os campos e tags do ticket definidos antes da criação do ticket serão adicionados a ele.

Depois que um ticket é fechado, os metadados de mensagens no back-end (como tickets) são redefinidos para um estado nulo vazio. Atualmente, os metadados de mensagens persistem no lado do cliente e serão abordados em uma versão futura.

Adição de um campo de conversa

Clientes em qualquer plano do Support podem criar campos de conversa, mas é preciso ter as mensagens configuradas e estar usando o Web Widget de mensagens ou SDKs para mensagens.

Campos de ticket do sistema, como o campo Prioridade, não são compatíveis. Eles aparecem no formulário de contato padrão, e em qualquer outro formulário de ticket, quando acessados pela central de ajuda, mas não aparecem no Web Widget.

Observação: campos personalizados de expressão regular, data e seleção múltipla podem ser definidos por meio de APIs de metadados, mas não são exibidos na conversa.

Você pode verificar se um campo de conversa foi definido visualizando as informações do ticket no Espaço de trabalho do agente do Zendesk ou com as APIs do Zendesk. Consulte Uso de metadados de mensagens para ver um exemplo.

Como adicionar um campo de conversa

1. Na Central de administração, clique em Objetos e regrasna barra lateral e selecione Tickets > Campos.
2. Clique em Adicionar campo.
3. Selecione um tipo de campo e insira um Nome de exibição.
4. (Opcional) Insira uma Descrição para o campo personalizado. Ela fica visível apenas para administradores.
5. Em Permissões, selecione Os clientes podem editar.
   Observação: como os valores podem ser definidos por meio de uma chamada pública de API do lado do cliente, os dados sempre devem ser tratados como se tivessem sido fornecidos por um usuário final. Não é recomendado utilizar essas APIs para dados confidenciais.
6. Insira um Título exibido para os clientes.
7. Se o agente precisar preencher o campo para resolver o ticket, selecione Obrigatório para resolver um ticket. Essa opção está indisponível em todos os tipos de campo.
   Observação: quando os agentes fazem a fusão de tickets, eles não precisam preencher os campos obrigatórios, pois os tickets fundidos ignoram o status Resolvido e avançam direto para o Fechado. Essa configuração também é ignorada se uma regra de negócios muda o ticket para Resolvido, pois é um processo do sistema que resolve o ticket, não um agente.
8. Se o usuário final precisar preencher o campo para enviar o ticket, selecione Obrigatório para enviar uma solicitação.
9. Configure as opções adicionais, dependendo do tipo de campo.
10. (Opcional) Especifique um Valor padrão para o campo personalizado.
    Observação: o valor padrão em uma lista suspensa se aplica apenas aos tickets novos que são criados por agentes pela interface do Support ou criados por usuários sempre que um formulário de ticket é exibido. Se você altera um formulário de ticket existente para um que contém uma lista suspensa com uma opção padrão, a opção padrão não é exibida (aparece em branco).
11. Clique em Salvar ou, para criar outro campo personalizado, clique no ícone suspenso, selecione Salvar e adicione outro.
12. Salve o ID do campo que acabou de criar, pois será necessário para usar a API de metadados.

Depois de criado, os desenvolvedores podem usar a API /api/v2/ticket_fields para visualizar os dados do campo de conversa. Eis um exemplo de resposta:

[
 {
   url: "https://z3n-lhills.zendesk.com/api/v2/ticket_fields/10093547287955.json",
   id: 10093547287955,
   type: "integer",
   title: "Bike Order id",
   raw_title: "Bike Order id",
   description:
     "An API will populate this bike order id value",
   raw_description:
     "An API will populate this bike order id value",
   position: 9999,
   active: true,
   required: false,
   collapsed_for_agents: false,
   regexp_for_validation: "\A[-+]?\d+\z",
   title_in_portal: "Bike Order Id",
   raw_title_in_portal: "Bike Order Id",
   visible_in_portal: true,
   editable_in_portal: true,
   required_in_portal: false,
   tag: null,
   created_at: "2022-10-04T04:48:05Z",
   updated_at: "2022-10-04T04:48:05Z",
   removable: true,
   agent_description: "Order id from our bikes catalog",
 },
]

Limpeza do campo de conversa

Pode haver vezes em que é necessário limpar os valores do campo de conversa. Isso depende do seu caso de uso e é feito quando os dados recuperados não são mais válidos. Por exemplo, suponha que você esteja usando campos de conversa para coletar dados do carrinho online de um usuário final. Se o usuário final apagar todos os itens no carrinho, seus dados coletados não serão mais válidos, e você pode limpar essas valores do campo de conversa.

Use a API clearConversationFields( ) para limpar os campos de conversa.

Adição de uma tag de conversa

Tags são palavras ou combinações de palavras que você pode usar para adicionar mais contexto a tópicos e tickets. Você pode aplicar tags a tickets, usuários e organizações. Por exemplo, identificar todas as solicitações que são, na verdade, perguntas sobre vendas com uma tag "vendas" ou "sobre_vendas". Você pode então criar uma visualização ou relatório para acompanhar essas solicitações.

Para obter mais informações, consulte Sobre tags.

Uso das APIs de metadados

Consulte a documentação do desenvolvedor sobre o uso de metadados de mensagens (em inglês) para ter um exemplo de como usar as APIs de metadados.

Configuração de campos e tags de conversa

Use a API setConversationFields para definir os valores do campo de conversa. Por exemplo, se o ID do seu campo de ticket personalizado fosse 10093547287955 e você quisesse definir esse valor com a cadeia de caracteres 548832222, então chamaria:

zE('messenger:set', 'conversationFields', [{ id: '10093547287955', value: '548832222'}]);

Se você usa um campo suspenso personalizado ou qualquer campo que seja associado a um valor de campo com uma tag, definir o valor do campo personalizado também define o valor da tag personalizada no ticket resultante.

	API do lado do cliente para definir campos de conversa
Web Widget	zE('messenger:set', 'conversationFields', [{ id: '{field ID}', value: '{value}'}])
iOS	Zendesk.instance.setConversationFields(["{field ID}” : “{field ID}"])
Android	Zendesk.instance.setConversationFields(listOf( TicketField(id="{field ID}", value="{value}" )))
Unity	ZendeskSdk.Instance.Messaging.SetConversationFieldsAsync(Dictionary<string, object> ticketFields)

Este é um exemplo de resposta para setConversationFields:

conversation: {
  ...
  metadata: {
        "zen:ticket_field": "30289064739483",
        ...
  },
}

Observação: {field ID} deve ser uma cadeia de caracteres. Caso contrário, será convertido para uma cadeia de caracteres. {value} deve ser uma cadeia de caracteres, um número ou um booliano.

Use a API setConversationTags para definir os valores da tag de conversa. Semelhante à API setConversationFields, se você definir uma tag personalizada associada a um campo personalizado editável, o campo personalizado será definido. Se a tag personalizada for associada a um campo personalizado privado (não editável), o campo personalizado não será definido.

	API do lado do cliente para definir tags de conversa
Web Widget	zE('messenger:set', 'conversationTags', ['{tag value}', '{tag value}'])
iOS	Zendesk.instance.setConversationTags(["{tag value}", "{tag value}"])
Android	Zendesk.instance.setConversationTags(listOf("{tag value}", "{tag value}"))
Unity	ZendeskSdk.Instance.Messaging.SetConversationTags(List<string> tags)

Eis um exemplo de resposta usando setConversationTags:

conversation: {
  ...
  metadata: {
    "zen:ticket:tags": "likes-nike-trainers, frequent-shopper",
  },
}

Limpeza de campos e tags de conversa

É possível limpar valores de campos de conversa e tags quando o contexto do lado do cliente muda. Por exemplo, o usuário final sai de uma página de produto e vai para a página inicial da sua loja. Quaisquer dados coletados da página de produto não são mais válidos.

Para fazer isso, use as APIs ClearConversationFields e ClearConversationTags. Elas limpam todos os campos e tags de conversa. Não é possível limpar um campo ou uma tag individual.

	API do lado do cliente para limpar campos e tags de conversa
Android	Zendesk.instance.clearConversationFields() Zendesk.instance.removeConversationTags()
Unity	ZendeskSdk.Instance.Messaging.ClearConversationFields() ZendeskSdk.Instance.Messaging.ClearConversationTags()

Criador de bots (agentes de IA legados)

Os campos atualizados usando as APIs de metadados são preenchidos com dados existentes e podem ser editados por usuários finais quando apresentados nessa etapa. Para obter mais informações, consulte Noções básicas sobre os tipos de etapas de fluxos de resposta e Criação de campos de ticket personalizados.