Find contact data using GraphQL

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 of Conversation objects that are closed only.

  • conversation: which returns a Conversation object based on its id (in uuid format).

As a reminder, GraphQL doesn't explicitly expose the notion of "contact", but it's entirely possible to reconstruct this notion by exploring the lifecycle of the conversation through the various distribution events (routingEvents) or events occurring during the conversation via messages of type SystemMessagein the messages property (theConversationPushedSystemAttachmentattachment that systematically marks the start of a new contact).

Here are all the fields/properties of the Conversation object you'll need to make your request:

FieldComments

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:

  • ConversationClosedSystemAttachment

  • TransferredToUserSystemAttachment

  • TransferredToRoutingRuleSystemAttachment

  • ConversationSnoozedSystemAttachment

  • …

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": "ha@bot.iadvize.com",
                    "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": "ha2@bot.iadvize.com",
                    "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": "test@iadvize.com",
                    "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": "test@iadvize.com",
                    "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": "test2@iadvize.com",
                    "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": "test2@iadvize.com",
                    "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"
          }
        }
      ]
    }
  }
}

PreviousCreate a custom dashboardNextRetrieve conversations data

Last updated