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 interface do usuário do Communications Mining se referem 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ê deseja carregar dados para o Communications Mining por meio da API ou para 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 para cada um dos tipos de comentários comumente 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 trabalha com vários tipos de dados de texto, como e-mails, respostas a 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 ticket de suporte, uma avaliação de 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": { ... },
}

Como mostrado no fragmento de código acima, além da parte real do texto, um comentário sempre tem um ID e um carimbo de data/hora. O ID precisa ser exclusivo na origem que contém a mensagem. O carimbo de data/hora é usado na IU da plataforma para filtrar e classificar por data, além de gerar análises baseadas em datas.

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

Comentários criados por meio da API

Emails

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

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

Observação: o exemplo de e-mail bruto abaixo 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 e-mail.

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 e-mail bruto processado se parece com o exemplo de e-mail processado abaixo - veja o número de campos adicionais criados pelo Communications Mining. Se você deseja 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 em 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 e a primeira resposta no tópico. A primeira resposta no tópico é o comentário mais antigo em que o remetente não é first_sender. Será definido como null se não houver respostas no tópico (ou seja, se todos os emails no tópico forem do mesmo remetente).

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

Observação: exceto thread_position, todas as propriedades são as mesmas para cada comentário em 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 abaixo 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ê coletar.

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)

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] (#FIXME). Para o exemplo acima, você busca o seguinte URL: https://cloud.uipath.com/<organização>/<organisation><tenant>/reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDneiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G.

Consulte a [Referência da API](#FIXME) 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

Consulte a tabela abaixo para uma lista dos 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 dentro de 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 | number>	não	Qualquer metadado definido do usuário que se aplique ao comentário. Há dois tipos possíveis: string e number. A chave de uma propriedade do usuário tem o formato "type:name", por exemplo, "string:Nome de Domínio" ou "número:Classificação de Estrelas". O nome da propriedade do usuário pode consistir em letras, números, espaços e sublinhados, e pode conter até 32 caracteres (em conformidade com /\w([\w ]{0,30}\w)?/). O valor deve ser uma string ou um número, dependendo do tipo de propriedade do usuário.
thread_id	String	não	Um ID que identifica exclusivamente uma thread de emails. 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](https://en.wikipedia.org/wiki/Media_type) do anexo. Para ver uma lista de valores possíveis, consulte a lista [Tipos de mídias IANA](https://www.iana.org/assignments/media-types/media-types.xhtml).
attachment_reference	String	não	Usado para recuperar o conteúdo do arquivo binário da [API de anexos](#FIXME)

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 isso for fornecido, tanto text quanto translated_from devem ser fornecidos para os campos de 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

Consulte a tabela abaixo para obter uma lista de campos de e-mail 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 | array<string>>	não	Uma das raw e parsed é necessária. Os cabeçalhos de email analisados, fornecidos como um objeto com chaves de string e valores de string ou array<string> . Cada chave deve ser ASCII e representar um cabeçalho de email. As strings de valor podem ser qualquer UTF-8 válido. Listas de valores serão concatenadas com , antes de serem definidas como um único valor de cabeçalho. Se você precisar de chaves de cabeçalho duplicadas, use raw .

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.