Comentarios

Objeto de comentarios en la API de Communications Mining y su relación con los mensajes en la interfaz de usuario.

Each message in Communications Mining™ is represented by a single comment object in the API. As a result, they can be considered equivalent. The developer documentation and API will refer primarily to comments, whilst the user guide and the Communications Mining UI refer primarily to messages.

Al cargar datos en Communications Mining u obtener datos de Communications Mining, es importante comprender cómo los diferentes tipos de datos (como correos electrónicos o tickets de soporte) deben representarse como comentarios. Esta página explica cómo modelar tus datos como Communications Mining comments para prepararlos para la carga, y cómo entender los datos obtenidos de Communications Mining.

Ejemplo de un comentario creado a partir de un correo electrónico

Comentario de Communications Mining™ creado a partir de una revisión

La sección Información general describe la estructura general de un objeto de comentario. Si desea cargar datos en Communications Mining™ a través de la API, o comprender cómo procesar los datos cargados en Communications Mining a través de la API, consulte la sección Comentarios creados a través de la API . Puedes encontrar descripciones detalladas para cada uno de los tipos de comentarios más utilizados (correos electrónicos o tickets de soporte).

Si desea comprender mejor cómo procesar los datos cargados en Communications Mining a través de una integración, consulte la sección Comentarios creados por integraciones . Por último, para obtener una lista completa de los campos de objeto de comentario disponibles, consulta la sección Referencia .

Información general

Communications Mining™ funciona con varios tipos de datos de texto, como correos electrónicos, respuestas de encuestas, tickets de soporte o reseñas de clientes. Lo que estos tipos de datos tienen en común es que todos consisten en unidades de comunicación (un correo electrónico, una respuesta a una encuesta, un ticket de soporte, una reseña de un cliente). En Communications Mining, un único mensaje se representa como un comentario, por ejemplo.

Independientemente del tipo de unidad de comunicación que simbolice un comentario, este mantiene de forma coherente esta estructura fundamental:

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

As shown in the previous code snippet, in addition to the actual piece of text, a comment always has an ID and a timestamp. The ID needs to be unique within the containing message. The timestamp is used in the platform UI to filter and sort by date, and to generate date-based analytics.

Además de estos campos obligatorios, se deben establecer otros campos dependiendo del tipo de comentario. Si sus datos se han cargado en Communications Mining™ a través de una integración, Communications Mining rellena automáticamente todos los campos necesarios. Consulta las siguientes secciones para obtener una descripción más detallada.

Comentarios creados a través de la API

Correos electrónicos

Aunque la forma más fácil de sincronizar correos electrónicos en Communications Mining™ es a través de la integración de Exchange, en los casos en los que realizas tu propia extracción de correo electrónico, puedes sincronizar correos electrónicos a través de la API. Utiliza el punto final sync-raw-emails para correos electrónicos sin procesar y el punto final sync para correos electrónicos procesados.

Al sincronizar correos electrónicos sin procesar, proporciona los encabezados de correo electrónico MIME extraídos y el cuerpo del correo electrónico tal cual (consulta la Referencia para obtener una descripción del formato de correo electrónico sin formato). Communications Mining analiza los encabezados y limpia el cuerpo del correo electrónico.

Nota:

El siguiente ejemplo de correo electrónico sin procesar muestra un número muy pequeño de encabezados para mayor brevedad. Envía todos los encabezados extraídos a Communications Mining, que probablemente sean mucho más largos que en el ejemplo.

Importante:

¿Cómo procesa Communications Mining los correos electrónicos sin procesar?

• Establece los campos específicos del correo electrónico en el objeto de mensaje messages[0]
• Establece el campo thread_id y el objeto thread_properties
• Limpia el cuerpo del correo electrónico eliminando los correos electrónicos entre comillas y colocando la firma en un campo signature independiente
• Rellena el objeto user_properties con metadatos extraídos de los encabezados de correo electrónico. Si un campo no está presente en el correo electrónico, no se establecerá en el comentario (en lugar de establecerse en un valor nulo o vacío). Por ejemplo, el comentario del siguiente ejemplo no contiene un campo BCC: .

Si enriqueces los correos electrónicos con otros datos antes de cargarlos en Communications Mining, puedes proporcionar estos datos adicionales en las propiedades de usuario del comentario.

El correo electrónico sin procesar procesado se parece al siguiente ejemplo de correo electrónico procesado. Comprueba el número de campos adicionales que ha creado Communications Mining. Si quieres cargar correos electrónicos procesados, estructúralos como en el ejemplo de correo electrónico procesado.

Ejemplo de correo electrónico

Correo electrónico sin procesar

{
  "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"
  }
}

Correo electrónico procesado

{
  "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
  }
}

Propiedades del hilo

Las siguientes propiedades de hilo están disponibles.

Nombre	Descripción
thread_position	Posición del comentario en el hilo, calculada ordenando el comentario por timestamp . Comienza en 0 .
num_messages	Número de comentarios en el hilo.
num_participants	Número total de participantes únicos (De, Para, CC, CCO) en el hilo.
first_sender	Remitente del primer comentario en el hilo.
duration	Diferencia (en segundos) entre el timestamps del primer y último comentario en el hilo. Se establecerá en null si num_messages es 1 (es decir, hilo contiene solo 1 comentario). Nota: el timestamp de un comentario corresponde al campo sent_at del correo electrónico sin formato correspondiente.
response_time	Diferencia (en segundos) entre el primer comentario del hilo y la primera respuesta del hilo. La primera respuesta en el hilo es el comentario más antiguo donde el remitente no es first_sender . Se establecerá en null si no hay respuestas en el hilo (es decir, si todos los correos electrónicos en el hilo son del mismo remitente).

Cada vez que se añade un nuevo comentario a la plataforma, se actualizan las propiedades del hilo correspondiente.

Nota:

Aparte de thread_position, todas las propiedades son las mismas para cada comentario en el hilo.

Tickets de soporte

Además del texto principal, un ticket de soporte típico enviado a través de un formulario puede tener un asunto, información sobre el remitente (como el nombre o la dirección de correo electrónico) y datos estructurados adicionales (como el tema del ticket) que se pueden cargar como parte de las propiedades de usuario del comentario.

El siguiente ejemplo muestra cómo formatear un ticket de soporte como un comentario de Communications Mining™ y cómo se muestra ese comentario en la interfaz de usuario de la plataforma. Tus propiedades de usuario pueden ser diferentes dependiendo de los datos que recopiles.

Ejemplo de ticket de soporte

{
  "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"
  }
}

Comentarios creados por integraciones

Correos electrónicos (Microsoft Exchange)

Los correos electrónicos de Microsoft Exchange incorporados a Communications Mining a través de la integración de Exchange se convierten automáticamente en objetos de comentario de la misma manera que los correos electrónicos sin procesar.

Archivos adjuntos y contenido de los archivos adjuntos

Los comentarios pueden tener archivos adjuntos. Si un comentario tiene archivos adjuntos, el campo attachments contiene metadatos sobre ellos:

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

Además, también puedes descargar el contenido del archivo adjunto. La descarga del contenido del archivo adjunto devuelve el 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 ... },

Utiliza attachment_reference para recuperar el contenido del archivo binario de la API de archivos adjuntos. Para el ejemplo anterior, obtienes la siguiente URL: https://cloud.uipath.com///reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G.

Consulta la Referencia de la API para obtener más información sobre este tipo de solicitud.

Si el objeto adjunto no tiene una propiedad attachment_reference , no puedes descargar el contenido del archivo adjunto. Esto puede deberse a que:

• Communications Mining™ no ha recibido el contenido del archivo adjunto.
• El contenido del archivo adjunto superó el límite de tamaño para cargarlo en Communications Mining.
• Communications Mining procesó el archivo adjunto antes de que admitiera el contenido del archivo.

Más información sobre el contenido de los archivos adjuntos en la página Archivos adjuntos.

Referencia

Comentarios

Consulta la siguiente tabla para obtener una lista de campos de comentarios disponibles. Si no estás familiarizado con los objetos de comentario de Communications Mining™, consulta la Información general.

Nombre	Tipo	Obligatorio	Descripción
id	String	Sí	Identifica un comentario de forma única dentro de un origen. Cualquier cadena hexadecimal de hasta 1024 caracteres es válida (se ajusta a /[0-9a-f]{1,1024}/).
timestamp	String	Sí	An ISO-8601 timestamp indicating when the comment was created. If the timestamp does not specify a timezone, UTC will be assumed. The timestamp must be in the range 1950-01-01T00:00:00Z to 2049-12-31T23:59:59Z inclusive.
messages	array<Message>	Sí	Una matriz de cero o un mensaje.
user_properties	map<string, string | number>	No	Any user-defined metadata that applies to the comment. There are two possible types: string and number. The key of a user property has the format "type:name", eg. "string:Domain Name" or "number:Star Rating". The user property name may consist of letters, numbers, spaces, and underscores, and may contain up to 32 characters (conforms to /\w([\w ]{0,30}\w)?/). The value must be a string or a number depending on the type of the user property.
thread_id	String	No	Un ID que identifica de forma única un hilo de correo electrónico. Cualquier cadena hexadecimal de hasta 1024 caracteres es válida (se ajusta a /[0-9a-f]{1,1024}/).
uid	String	establecido por Communications Mining™	Un ID combinado de fuente y comentario en forma de source_id.comment_id. No deberías establecer este campo directamente, ya que Communications Mining lo genera automáticamente para los comentarios cargados.
created_at	String	establecido por Communications Mining	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is created.
updated_at	String	establecido por Communications Mining	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is updated.
attachments	array<Attachment>	No	Una matriz de cero o más archivos adjuntos. Un archivo adjunto representa un archivo adjunto a un comentario.

Nombre	Tipo	Obligatorio	Descripción
name	String	Sí	El nombre del archivo adjunto.
size	Número	Sí	El tamaño del contenido del archivo adjunto en bytes.
content_type	String	Sí	El tipo de archivo multimedia del archivo adjunto. Para obtener una lista de valores posibles, consulta la lista Tipos de medios de IANA .
attachment_reference	String	No	Se utiliza para recuperar el contenido del archivo binario de la API de archivos adjuntos

Donde Message tiene el siguiente formato:

Nombre	Tipo	Obligatorio	Descripción
body	Contenido	Sí	Un objeto que contiene el texto del cuerpo principal del mensaje.
subject	Contenido	No	Un objeto que contiene el asunto del mensaje.
signature	Contenido	No	Un objeto que contiene la firma del mensaje.
from	String	No	El remitente del mensaje.
to	array<string>	No	Una matriz de destinatarios principales.
cc	array<string>	No	Una matriz de destinatarios en copia carbón.
bcc	array<string>	No	Una matriz de destinatarios en copia oculta.
sent_at	String	No	An ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
language	String	No	El idioma original del mensaje. Si se proporciona, tanto text como translated_from deben proporcionarse para los campos de Contenido.

Donde Content tiene el siguiente formato:

Nombre	Tipo	Obligatorio	Descripción
text	String	Sí	If language (other than the source's language) has been supplied, this should be the translated text of the content. Otherwise, it should be in the original language it was collected; it will be translated if not in the source's language and the source has should_translate set to true. Maximum 65536 characters.
translated_from	String	No	If language (other than the source's language) has been supplied, this should be the original text of the content. Supplying this field without having supplied a language will result in an error. At most 65536 characters.

Correos electrónicos sin procesar

Consulta la siguiente tabla para obtener una lista de campos de correo electrónico sin procesar disponibles.

Nombre	Tipo	Obligatorio	Descripción
headers	Encabezados	Sí	Un objeto que contiene los encabezados del correo electrónico.
body	Cuerpo	Sí	Un objeto que contiene el cuerpo principal del correo electrónico.

Donde Headers tiene el siguiente formato:

Nombre	Tipo	Obligatorio	Descripción
raw	String	No	Se requiere uno de raw y parsed . Los encabezados de correo electrónico sin formato, proporcionados como una sola cadena, con cada encabezado en su propia línea.
parsed	map<string, string | array<string>>	No	One of raw and parsed is required. The parsed email headers, given as an object with string keys and string or array<string> values. Each key must be ASCII, and represents one email header. Value strings may be any valid UTF-8. Lists of values will be concatenated with , before being set as a single header value. If you require duplicate header keys, please use raw instead.

Donde Body tiene el siguiente formato:

Nombre	Tipo	Obligatorio	Descripción
plain	String	No	Se requiere al menos uno de plain y html . El contenido de texto sin formato del correo electrónico. Como máximo 65536 caracteres.
html	String	No	Se requiere al menos uno de plain y html . El contenido HTML del correo electrónico.