Understand conversation data 2/2
Unlike our Rest API, which provides contact indicators, our GraphQL API provides conversation indicators. However, you may wish to go down to a per-contact granularity also for GraphQL indicators.
Contact vs conversation definition
- A contact is an exchange between a visitor and an operator (agent, expert or bot). It can be a chat, call or video contact.
- A conversation can include several contacts, especially if they have been transferred or snoozed.
A conversation can therefore include several contacts when it is ended.
Fields to be used
The fields/properties mentioned are available in the Conversation type/object. This Conversation object is available through (depending on your needs) two queries:
closedConversations: which returns a paginated list ofConversationobjects that are closed only.conversation: which returns aConversationobject based on its id (in uuid format).
Here are all the fields/properties of the Conversation object you'll need to make your request:
DATE/TIME (opening)
The goal is to retrieve the start date of each contact for which a ConversationPushedSystemAttachment message occurs systematically.
DATE/TIME (close)
See point above.
If you need to retrieve the conversation's closing date, it is available in the closedAt property.
ID_
CONTACT (unique)
There's no such thing as a contact id, but it's possible to build one by concatenating various pieces of information, such as the conversation id and the date (createdAt) of the ConversationPushedSystemAttachment attachment.
SITE_ID
This is the id property in the conversation's project property.
CHANNEL (chat/wa/ etc.)
This is the channel property
ID_
OPERATOR
It is possible to retrieve the information (id, name, email, etc.) of the user who has processed a contact. This information can be accessed in the toUser property of the system message whose attachment is of type ConversationPushedSystemAttachment.
ID_
CONVERSATION
This information is available in the id property of the Conversation object.
ROUTING_RULES
The goal is to determine which group(s) of respondents actually handled the contact.
This information is available in the routingEvents property, which retrieves the date on which the event occurred (createdAt), as well as details of the rule and targeting group (routingRule and routingGroup) to which the conversation was distributed.
Chronologically, a distribution event necessarily occurs before one or more ConversationPushedSystemAttachment messages (corresponding to the sending of the conversation to the advisor's console or the reception of the conversation by a bot).
For example, a conversation with two contacts handled by the same operator. We can clearly see two ConversationPushedSystemAttachments that can be linked to distribution information (routingRule and routingGroup).
11:00:00 routingEvent (routingRule+routingGroup)
11:00:01 ConversationPushedSystemAttachment
11:00:05 ConversationSnoozedSystemAttachment
— conversation returns 5 minutes after snooze
11:05:05 ConversationPushedSystemAttachment
…
…
11:10:00 ConversationClosedSystemAttachment
CONTACT_
STATUS (answered, unanswered, transferred, snoozed...)
This involves retrieving events that have occurred during the conversation.
iAdvize exposes all these events in the messages property with the SystemMessage type. It's possible to retrieve the name of this event using the __typename property, as well as information specific to each event, which you can find in our Apollo tool.
Here is an example of some of the events you may encounter:
ConversationClosedSystemAttachmentTransferredToUserSystemAttachmentTransferredToRoutingRuleSystemAttachmentConversationSnoozedSystemAttachment…
ENDING_
CONTACT (reason)
The need is to determine whether the contacts have resulted in :
- a closing
- a transfer
- a snooze
- ...
This information can be retrieved via the SystemMessage mentioned above.
Find conversation contacts through SystemMessage
Example of a query
In the following example, we retrieve the distribution information as well as the events in the conversation's lifecycle (marking, in particular, the beginning and end of contacts).
We therefore find 3 contacts symbolized by the presence of 3 attachments of type: ConversationPushedSystemAttachment.
As the conversation has been transferred to distribution rules, we also find 3 distribution events in the routingEvents property.
Query
query MyQuery {
conversation(id: "b90f9039-f993-4221-9293-0000000000fb") {
id
channel
messages {
edges {
node {
__typename
... on SystemMessage {
attachments {
__typename
... on ConversationPushedSystemAttachment {
toUser {
id
email
firstName
}
}
... on ConversationClosedSystemAttachment {
byUser {
__typename
id
email
firstName
lastName
}
}
... on TransferredToUserSystemAttachment {
reason
toUser {
__typename
id
email
firstName
lastName
}
fromUser {
__typename
id
email
firstName
lastName
}
}
... on TransferredToRoutingRuleSystemAttachment {
reason
fromUser {
__typename
id
email
firstName
lastName
}
}
... on ConversationSnoozedSystemAttachment {
until
byUser {
__typename
id
email
firstName
lastName
}
}
}
createdAt
}
}
}
}
routingEvents {
routingGroup {
id
name
}
createdAt
routingRule {
id
name
}
}
}
}
Response / result
{
"data": {
"conversation": {
"id": "b90f9039-f993-4221-9293-0000000000fb",
"channel": "CHAT",
"messages": {
"edges": [
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "EngagementRuleTriggeredSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:04.774429Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "NavigationChangedSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:05Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [],
"createdAt": "2023-10-08T08:33:05.411381Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "ConversationPushedSystemAttachment",
"toUser": {
"id": 44000,
"email": "[email protected]",
"firstName": null
}
}
],
"createdAt": "2023-10-08T08:33:05.490789Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "NavigationChangedSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:05.559807Z"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "TransferredToRoutingRuleSystemAttachment",
"reason": "",
"fromUser": {
"__typename": "Bot",
"id": 434024,
"email": "[email protected]",
"firstName": null,
"lastName": "Page contact"
}
}
],
"createdAt": "2023-10-08T08:33:10.646767Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "VisitorNotificationSettingsRequestedSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:15.949558Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "VisitorNotificationSettingsSetSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:19.587015Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "VisitorNotificationSettingsConfirmedSystemAttachment"
}
],
"createdAt": "2023-10-08T08:33:19.879399Z"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [],
"createdAt": "2023-10-08T08:38:58.366868Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "ConversationPushedSystemAttachment",
"toUser": {
"id": 268289,
"email": "[email protected]",
"firstName": "Pierre HACK"
}
}
],
"createdAt": "2023-10-08T08:39:02.422185Z"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "TransferredToRoutingRuleSystemAttachment",
"reason": "j’aimerais faire réparer l’écran de mon téléphone qui est cassé",
"fromUser": {
"__typename": "Professional",
"id": 260000,
"email": "[email protected]",
"firstName": "Pierre HACK",
"lastName": "MU"
}
},
{
"__typename": "UnsupportedSystemMessageAttachment"
}
],
"createdAt": "2023-10-08T08:40:03.249159Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "VisitorNotificationSettingsRequestedSystemAttachment"
}
],
"createdAt": "2023-10-08T08:40:09.326441Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [],
"createdAt": "2023-10-08T08:43:03.373263Z"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "ConversationPushedSystemAttachment",
"toUser": {
"id": 380000,
"email": "[email protected]",
"firstName": "AnnH PLEVIN"
}
}
],
"createdAt": "2023-10-08T08:43:04.311492Z"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "ParticipantConversationMessage"
}
},
{
"node": {
"__typename": "SystemMessage",
"attachments": [
{
"__typename": "ConversationClosedSystemAttachment",
"byUser": {
"__typename": "Professional",
"id": 383512,
"email": "[email protected]",
"firstName": "AnnH PLEVIN",
"lastName": "CA"
}
}
],
"createdAt": "2023-10-08T08:52:11Z"
}
}
]
},
"routingEvents": [
{
"routingGroup": {
"id": "f3485cc1-2a31-00e2-bc0e-000fd57dcf19",
"name": "Page contact - chatbot routing group"
},
"createdAt": "2023-10-08T08:33:04Z",
"routingRule": {
"id": "594ee64b-b888-4f1a-8273-47eae1f0a566",
"name": "Distribuer à bot Page Contact puis au service client"
}
},
{
"routingGroup": {
"id": "007fce95-561c-000b-89ff-9b5846398d11",
"name": "Groupe Service client 1"
},
"createdAt": "2023-10-08T08:33:10Z",
"routingRule": {
"id": "fed7f40a-0000-43e3-85cd-13eff3c8d64e",
"name": "Transfert Bot vers Service client commercial"
}
},
{
"routingGroup": {
"id": "cbf887b7-e33b-000e-ad2c-33fb7025c03f",
"name": "Groupe Assistance technique"
},
"createdAt": "2023-10-08T08:40:03Z",
"routingRule": {
"id": "6b91bba2-78bc-48d2-a5ff-d9f391f0000",
"name": "Assistance technique"
}
}
]
}
}
}
Last updated
Was this helpful?