Skip to main content

Comments

Data synced into Re:infer shares a common comment format which is described in the Overview. You should be familiar with Re:infer comments if you are processing data from Re:infer, or if you are uploading data to Re:infer via the API. Data uploaded via an integration will be automatically converted into comment objects.

Overview#

Re:infer works with various types of text data such as emails, survey responses, support tickets, or customer reviews. What these types of data have in common is that they all consist of units of communication (an email, a survey response, a support ticket, a customer review). In Re:infer, we call any such unit of communication a comment.

A comment created from an email
A comment created from an email
A comment created from a customer review
A comment created from a customer review

Regardless of the type of unit of communication a comment represents, it will always have this basic structure:

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

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

In addition to these required fields, optional fields can be set. If your data has been uploaded to Re:infer via an integration, you can check this section to learn which fields Re:infer will populate. If you are uploading data via the API, you can set any fields you consider necessary. See the Reference section for a description of all available fields.

Comments created by integrations#

Emails (Microsoft Exchange)#

Microsoft Exchange emails are ingested into Re:infer in the in their raw (MIME) form via the EWS appliance or via the /sync-raw-emails API endpoint, and are automatically converted into comment objects. The example below shows what the resulting comments will look like. In particular, Re:infer will set the email-specific fields in the message object messages[0], set the thread_id field, clean up the email body by putting the signature into a separate signature field, and populate the user_properties object with metadata extracted from email headers.

Note that if a field is not present in the email, it won't be set in the comment at all (rather than being set to a null or empty value). For example, the comment below does not contain a BCC: field.

While messages is an array, there will always be exactly one message per comment.

{  "id": "456789ef",  "uid": "47194279497e141e.456789ef",  "thread_id": "0123abcd",  "timestamp": "2021-02-11T00:09:22Z",  "messages": [    {      "body": {        "text": "Hi Alice,\n\nPlease can you send the documents today.\n\nThank you in advance."      },      "subject": {        "text": "Request for documents."      },      "signature": {        "text": "Kind Regards,\n\nBob Smith"      },      "from": "\"Bob Smith\" <bob.smith@a-corp.com>",      "to": ["\"Alice Brown\" <alice.brown@b-corp.com>"],      "cc": ["\"Compliance Team\" <compliance@a-corp.com>"],      "sent_at": "2021-02-11T00:09:22Z"    }  ],  "user_properties": {    "string:Sender Domain": "a-corp.com",    "string:Folder": "Inbox",    "string:Has Signature": "Yes",    "string:Thread": "0123abcd",    "number:Position in Thread": 1,    "number:Recipient Count": 2,    "string:Sender": "bob.smith@a-corp.com",    "string:Message ID": "456789ef",    "number:Participant Count": 3  },  "created_at": "2021-02-12T14:44:25.942Z"}

Comments created via the API#

If you sync data into Re:infer via the /sync API endpoint, you can set any fields you consider necessary. The example below shows how fields for a customer review comment might be set by using a subset of fields available in the message object message[0] and custom metadata in the user_properties object.

Note that you shouldn't be setting the uid and created_at fields that are shown in the example, as they are generated by Re:infer when you upload the comment.

While messages is an array, you should set exactly one message per comment.

{  "id": "ab123456",  "uid": "47194279497e141e.ab123456",  "timestamp": "2020-02-26T16:09:00Z",  "messages": [    {      "body": {        "text": "The customer support representative was very informative and could answer all my questions. Thank you!"      },      "subject": {        "text": "Very knowledgeable service"      }    }  ],  "user_properties": {    "number:Review Stars": 5,    "string:Reference Id": "xyz"  },  "created_at": "2021-02-12T16:59:58.143Z"}

Reference#

See the table below for a list of available comment fields. If you are unfamiliar with Re:infer comment objects, please refer to the Overview.

NameTypeRequiredDescription
idstringyesIdentifies a comment uniquely within a source. Any hexadecimal string of up to 1024 characters is valid (conforms to /[0-9a-f]{1,1024}/).
timestampstringyesA 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.
messagesarray<Message>yesAn array of zero or more messages. Conversations are represented as a chronological series of messages, whilst a single piece of text should be a single-element array.
user_propertiesmap<string, string | number>noAny 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_idstringnoAn ID uniquely identifying an email thread. Any hexadecimal string of up to 1024 characters is valid (conforms to /[0-9a-f]{1,1024}/).
uidstringset by Re:inferA combined source and comment ID in the form of source_id.comment_id. You should not be setting this field directly as it's automatically generated by Re:infer for uploaded comments.
created_atstringset by Re:inferA 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 Re:infer when the comment is created.
updated_atstringset by Re:inferA 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 Re:infer when the comment is updated.

Where Message has the following format:

NameTypeRequiredDescription
bodyContentyesAn object containing the main body text of the message.
subjectContentnoAn object containing the messages's subject.
signatureContentnoAn object containing the messages's signature.
fromstringnoThe message sender.
toarray<string>noAn array of primary recipients.
ccarray<string>noAn array of carbon-copy recipients.
bccarray<string>noAn array of blind carbon-copy recipients.
sent_atstringnoA ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
languagestringnoThe original language of the message. If this is supplied, both text and translated_from should be supplied for the Content fields.

Where Content has the following format:

NameTypeRequiredDescription
textstringyesIf 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.
translated_fromstringnoIf language (other than the source's language) has been supplied, this should by the original text of the content. Supplying this field without having supplied a language will result in an error.