Comments

Cada mensagem no Communications Mining™ é representada por um único objeto de comentário na API. Como resultado, eles podem ser considerados equivalentes. A documentação do desenvolvedor e a API se referirão principalmente a comments, enquanto o guia do usuário e a UI do Communications Mining se referirão principalmente a messages.

Ao carregar dados para o Communications Mining ou buscar dados no Communications Mining, é importante entender como diferentes tipos de dados (como emails ou tickets de suporte) devem ser representados como comentários. Esta página explica como modelar seus dados como Communications Mining comments para prepará-los para upload e como entender os dados obtidos no Communications Mining.

Exemplo de um comentário criado a partir de um e-mail

Comentário do Communications Mining™ criado a partir de uma revisão

A seção Visão geral descreve a estrutura geral de um objeto de comentário. Se você quiser carregar dados para o Communications Mining™ por meio da API ou entender como processar dados carregados para o Communications Mining por meio da API, consulte a seção Comentários criados por meio da API . Você pode encontrar descrições detalhadas de cada um dos tipos de comentários mais usados (e-mails ou tickets de suporte). Se você quiser entender melhor como processar dados carregados para o Communications Mining por meio de uma integração, consulte a seção Comentários criados por integrações . Por fim, para obter uma lista completa de campos de objeto de comentário disponíveis, consulte a seção Referência .

Visão geral

O Communications Mining™ funciona com vários tipos de dados de texto, como e-mails, respostas de pesquisas, tickets de suporte ou avaliações de clientes. O que esses tipos de dados têm em comum é que todos consistem em unidades de comunicação (um e-mail, uma resposta de pesquisa, um tíquete de suporte, uma avaliação de um cliente). No Communications Mining, uma única mensagem é representada como um comentário, por exemplo.

Não importa o tipo de unidade de comunicação que um comentário represente, ele mantém consistentemente essa estrutura fundamental:

{
  "id": <UNIQUE ID>,
  "timestamp": <TIMESTAMP>,
  "messages": [
    {
      "body": { "text": <TEXT> },
      ...
    }
  ],
  "user_properties": { ... },
}

Conforme mostrado no fragmento de código anterior, além da parte real do texto, um comentário sempre tem um ID e um carimbo de data/hora. O ID precisa ser único dentro da mensagem. O carimbo de data/hora é usado na interface do usuário da plataforma para filtrar e classificar por data, além de gerar análises baseadas em data.

Além desses campos obrigatórios, outros campos devem ser definidos dependendo do tipo de comentário. Se seus dados forem carregados para o Communications Mining™ por meio de uma integração, o Communications Mining preencherá automaticamente todos os campos necessários. Confira as seções a seguir para obter uma descrição mais detalhada.

Comentários criados por meio da API

Emails

Embora a maneira mais fácil de sincronizar emails com o Communications Mining™ seja por meio da integração do Exchange, nos casos em que você faz sua própria extração de email, é possível sincronizar emails por meio da API. Use o endpoint sync-raw-emails para e-mails brutos e o ponto de extremidade sync para e-mails processados.

Ao sincronizar emails brutos, forneça os cabeçalhos de email MIME extraídos e o corpo do email como está (verifique a Referência para uma descrição do formato de email bruto). O Communications Mining analisa os cabeçalhos e limpa o corpo do e-mail.

Observação:

O seguinte exemplo de e-mail bruto mostra um número muito pequeno de cabeçalhos para abreviação. Envie todos os cabeçalhos extraídos para o Communications Mining, que provavelmente serão muito mais longos do que no exemplo.

Importante:

Como o Communications Mining processa e-mails brutos?

• Define os campos específicos do email no objeto da mensagem messages[0]
• Define o campo thread_id e o objeto thread_properties
• Limpa o corpo do email removendo emails entre aspas e colocando a assinatura em um campo signature separado
• Preenche o objeto user_properties com metadados extraídos de cabeçalhos de email. Se um campo não estiver presente no email, ele não será definido no comentário (em vez de ser definido como um valor nulo ou vazio). Por exemplo, o comentário no exemplo a seguir não contém um campo BCC: .

Se você enriquecer e-mails com outros dados antes de carregá-los para o Communications Mining, é possível fornecer esses dados adicionais nas propriedades do usuário do comentário.

O email bruto processado se parece com o seguinte exemplo de email processado. Verifique o número de campos adicionais que o Communications Mining criou. Se você quiser carregar e-mails processados, estruture-os como no exemplo de e-mail processado.

Exemplo de email

Email Bruto

{
  "raw_email": {
    "body": {
      "plain": "Hi Bob,\n\nCould you send me the figures for today?\n\nThanks,\nAlice"
    },
    "headers": {
      "raw": "From: Alice Smith <[e-mail]>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <[e-mail]>\nSubject: Figures for today\nTo: Bob <[e-mail]>\nCc: Joe <[e-mail]>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}

Email processado

{
  "comment": {
    "id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
    "timestamp": "2021-08-03T09:57:42Z",
    "user_properties": {
      "string:Has Signature": "Yes",
      "string:Sender": "[e-mail]",
      "string:Thread": "<[e-mail]>",
      "string:Message ID": "<[e-mail]>",
      "number:Recipient Count": 2,
      "number:Participant Count": 3,
      "number:Position in Thread": 1,
      "string:Sender Domain": "example.com",
      "string:Team": "Team XYZ"
    },
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me the figures for today?"
        },
        "signature": {
          "text": "Thanks,\nAlice"
        },
        "subject": {
          "text": "Figures for today"
        },
        "to": ["\"Bob\" <[e-mail]>"],
        "cc": ["\"Joe\" <[e-mail]>"],
        "sent_at": "2021-08-03T09:57:42Z",
        "from": "\"Alice Smith\" <[e-mail]>"
      }
    ],
    "thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
  },
  "thread_properties": {
    "duration": null,
    "response_time": null,
    "num_messages": 1,
    "num_participants": 3,
    "first_sender": "[e-mail]",
    "thread_position": 0
  }
}

Propriedades da thread

As seguintes propriedades de thread estão disponíveis.

Nome	Descrição
thread_position	Posição do comentário no thread, calculada ordenando o comentário por timestamp . Inicia às 0 .
num_messages	Número de comentários no thread.
num_participants	Número total de participantes únicos (De, Para, CC, BCC) no thread.
first_sender	Remetente do primeiro comentário no tópico.
duration	Diferença (em segundos) entre o timestamps do primeiro e último comentário no tópico. Será definido como null se num_messages é 1 (ou seja thread contém apenas 1 comentário). Observação: o timestamp de um comentário corresponde ao campo sent_at do email bruto correspondente.
response_time	Diferença (em segundos) entre o primeiro comentário no thread e a primeira resposta no thread. A primeira resposta no thread é o comentário mais antigo no qual o remetente não é first_sender . Será definido como null se não houver respostas no thread (ou seja, se todos os e-mails no thread forem do mesmo remetente).

Cada vez que um novo comentário é adicionado à plataforma, as propriedades do thread correspondente são atualizadas.

Observação:

Além de thread_position, todas as propriedades são as mesmas para cada comentário no thread.

Tíquetes de suporte

Além do texto principal, um ticket de suporte típico enviado por meio de um formulário pode ter um assunto, informações sobre o remetente (como nome ou endereço de e-mail) e dados estruturados adicionais (como o tópico do ticket) que podem ser carregados como parte das propriedades de usuário do comentário.

O exemplo a seguir mostra como formatar um ticket de suporte como um comentário do Communications Mining™ e como esse comentário é exibido na interface gráfica da plataforma. Suas propriedades de usuário podem ser diferentes, dependendo dos dados que você coleta.

Exemplo de ticket de suporte

{
  "id": "dbcb03ad",
  "timestamp": "2020-02-26T16:09:00Z",
  "messages": [
    {
      "body": {
        "text": "Hi Support Team\n\nPlease could you look into my broadband service network status. I don't have any signal."
      },
      "subject": {
        "text": "Network Outage for over 24 hours - Customer account number 1234567"
      },
      "from": "[e-mail]"
    }
  ],
  "user_properties": {
    "string:Customer Name": "Alice Smith",
    "string:Source": "Support Form",
    "string:Topic": "Broadband"
  }
}

Comentários criados por integrações

E-mails (Microsoft Exchange)

Os e-mails do Microsoft Exchange ingeridos no Communications Mining por meio da integração do Exchange são convertidos automaticamente em objetos de comentário da mesma forma que e-mails brutos.

Anexos e conteúdos de anexos

Os comentários podem ter arquivos anexados. Se um comentário tiver anexos, o campo attachments contém metadados sobre eles:

json
{ "id": "3c484531505230324d423", "attachments": [ { "name": "account-statement.pdf", "size": 49078, "content_type": "application/pdf", } ], // other comment fields omitted ... },

Além disso, você também pode baixar o conteúdo do anexo. Baixar o conteúdo do anexo retorna o campo attachment_reference :

json
{ "id": "3c484531505230324d423", "attachments": [ { "name": "account-statement.pdf", "size": 49078, "content_type": "application/pdf", "attachment_reference": "CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G" } ], // other comment fields omitted ... },

Use attachment_reference para recuperar o conteúdo do arquivo binário da API de anexos. Para o exemplo anterior, você busca o seguinte URL: https://cloud.uipath.com///reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G.

Consulte a Referência da API para obter mais detalhes sobre esse tipo de solicitação.

Se o objeto de anexo não tiver uma propriedade attachment_reference , você não poderá baixar o conteúdo do anexo. Isso pode ocorrer porque:

• O Communications Mining™ não recebeu o conteúdo do anexo.
• O conteúdo do anexo excedeu o limite de tamanho para ser carregado no Communications Mining.
• O Communications Mining processou o anexo antes de oferecer suporte ao conteúdo do arquivo.

Saiba mais sobre o Conteúdo do anexo na página Anexo.

Referência

Comments

Verifique a tabela a seguir para uma lista de campos de comentário disponíveis. Se você não estiver familiarizado com os objetos de comentário do Communications Mining™, consulte a Visão geral.

Nome	Tipo	Required	Descrição
id	String	sim	Identifica um comentário exclusivamente em uma origem. Qualquer string hexadecimal de até 1024 caracteres é válida (em conformidade com /[0-9a-f]{1,1024}/).
timestamp	String	sim	Um carimbo de data/hora ISO-8601 que indica quando o comentário foi criado. Se o carimbo de data/hora não especificar um fuso horário, o UTC será utilizado. O carimbo de data/hora deve estar no intervalo de 1950-01-01T00:00:00Z a 2049-12-31T23:59:59Z, inclusive.
messages	array<Message>	sim	Uma matriz de zero ou uma mensagem.
user_properties	`map<string, string	número >`	não
thread_id	String	não	Um ID que identifica exclusivamente um thread de email. Qualquer string hexadecimal de até 1024 caracteres é válida (em conformidade com /[0-9a-f]{1,1024}/).
uid	String	definido pelo Communications Mining™	Uma ID combinada de origem e comentário na forma de source_id.comment_id. Você não deve definir esse campo diretamente, pois ele é gerado automaticamente pelo Communications Mining para comentários carregados.
created_at	String	definido pelo Communications Mining	Um carimbo de data/hora ISO-8601 com as mesmas restrições que o campo timestamp . Você não deve definir esse campo diretamente, pois ele é gerado automaticamente pelo Communications Mining quando o comentário é criado.
updated_at	String	definido pelo Communications Mining	Um carimbo de data/hora ISO-8601 com as mesmas restrições que o campo timestamp . Você não deve definir esse campo diretamente, pois ele é gerado automaticamente pelo Communications Mining quando o comentário é atualizado.
attachments	array<Attachment>	não	Uma matriz de zero ou mais anexos. Um anexo representa um arquivo anexado a um comentário.

Nome	Tipo	Required	Descrição
name	String	sim	O nome de arquivo do anexo.
size	Número	sim	O tamanho do conteúdo de arquivo do anexo em bytes.
content_type	String	sim	O tipo de Mídia do anexo. Para obter uma lista de valores possíveis, consulte a lista Tipos de mídia da IANA .
attachment_reference	String	não	Usado para recuperar o conteúdo do arquivo binário da API de anexos

Onde Message tem o seguinte formato:

Nome	Tipo	Required	Descrição
body	Content	sim	Um objeto que contém o texto do corpo principal da mensagem.
subject	Content	não	Um objeto que contém o assunto da mensagem.
signature	Content	não	Um objeto que contém a assinatura da mensagem.
from	String	não	O remetente da mensagem.
to	array<string>	não	Uma matriz de destinatários primários.
cc	array<string>	não	Uma matriz de destinatários em cópia.
bcc	array<string>	não	Uma matriz de destinatários em cópia oculta.
sent_at	String	não	Um carimbo de data/hora ISO-8601 que indica quando a mensagem foi criada. Se o carimbo de data/hora não especificar um fuso horário, o UTC será utilizado.
language	String	não	O idioma original da mensagem. Se for fornecido, text e translated_from devem ser fornecidos para os campos Conteúdo.

Onde Content tem o seguinte formato:

Nome	Tipo	Required	Descrição
text	String	sim	Se language (outro que não o da origem language) tiver sido fornecido, esse deverá ser o texto traduzido do conteúdo. Caso contrário, deve estar no idioma original que foi coletado; ele será traduzido se não estiver no language da origem e a origem tiver should_translate definido como true. Máximo de 65.536 caracteres.
translated_from	String	não	Se language (outro que não o da origem language) tiver sido fornecido, isso deverá estar junto ao texto original do conteúdo. Fornecer este campo sem ter fornecido um language resultará em um erro. No máximo, 65536 caracteres.

E-mails brutos

Verifique a tabela a seguir para uma lista de campos de email bruto disponíveis.

Nome	Tipo	Required	Descrição
headers	Cabeçalhos	sim	Um objeto que contém os cabeçalhos do email.
body	Corpo	sim	Um objeto que contém o corpo principal do email.

Onde Headers tem o seguinte formato:

Nome	Tipo	Required	Descrição
raw	String	não	Uma das raw e parsed é necessária. Os cabeçalhos de email brutos, fornecidos como uma única string, com cada cabeçalho em sua própria linha.
parsed	`map<string, string	Matriz>`	não

Onde Body tem o seguinte formato:

Nome	Tipo	Required	Descrição
plain	String	não	Pelo menos um dos plain e html são necessários. O conteúdo de texto simples do email. No máximo, 65536 caracteres.
html	String	não	Pelo menos um dos plain e html são necessários. O conteúdo HTML do email.