Skip to main content

Overview

Soul Machines Insights API is designed to help our clients and business partners tell compelling data-driven business stories, by surfacing and visualising their organization's data. Our Insights API helps our clients better understand how their Digital People are conversing and performing in the wild.

The data from the Insights API helps our clients analyze how their users interact with their Digital People. It also provides some data-driven information and context around the user's perceived emotions as inferred by our AI models during such interactions.

The Insights API empowers our clients to choose the data granularity which best summarises their specific use case and allows them to iterate on optimising and improving their end-user conversation and experience based on the insights they draw from their data.

Before you begin​

  • Create an Analytics API Key from Digital DNA Studio.
  • Pass the API key in the x-sm-apikey parameter of the request header when calling any of the endpoints of the Insights API.

Note: You should revoke the key if it becomes inactive, lost, or compromised. For details see Revoke API Key.

Supported endpoints​

We currently offer the following levels of granularity for retrieving and querying Insights API data:

High-level endpoints​

  • Events Summary - This endpoint returns an organization-level events summary report between a specified start and end date.

Low-level endpoints​

  • Daily Logs - This is the primary endpoint which returns daily log sessions events data.

  • Conversation Nodes Summary - This endpoint returns an organization-level conversation nodes summary report between a specified start and end date.

V2 endpoints​

The v2 endpoints will paginate the results in the response. Responses from v2 endpoints are always returned as a JSON object and contain the meta property as a type of PaginationMeta, apart from the analytics data fetched.

Metrics retrievable from Insights APIs​

Some metrics/insights you can surface using APIs are:

The Events Summary endpoint:

  • How many conversations did my DP have in the last month?
  • When was my DP's most recent conversation?
  • How many hours of conversation did my DP engage in this today?

The Daily Logs endpoint:

  • How many users had their camera turned on whilst speaking to my DP this week?
  • What was the perceived emotional state of users while interacting with my DP?
  • How many user-DP conversational turns took place during a single interaction?

The Conversation Nodes Summary endpoint:

  • Which conversational node was hit the most during user-DP interactions?
  • At which conversational node did users experience the most confusion or positive/negative sentiment?
  • Where did most users drop off over the course of the conversation?
  • How many conversational nodes were traversed between the starting and ending nodes of the conversation?

Access and visualise the insights data​

You can now access and visualize the insights data using your favorite supported Business Intelligence tools below: