Analytics API · Mavenoid help center

For more information about Mavenoid analytics, see Understand analytics.

The analytics API is currently in BETA. Please share any suggestions for improvements through this form.

Using the API

Authentication

Every request to Mavenoid's Analytics API must be authenticated using a bearer token. To obtain a token, please contact your Mavenoid representative or email [email protected].

To authenticate your API requests, include the following header with your token in place of {{ACCESS_TOKEN}}:

Authorization: Bearer {{ACCESS_TOKEN}}

Here's an example authenticated API call using curl:

curl \
  -H "Authorization: Bearer ma_15prljrk6_uvsb2u6aknvutrr6cvtu9t43odabsdd0o2vg" \
  "https://analytics-api.mavenoid.com/v1/assistant-conversations.json?days=30"

Rate limits

Requests for data within the last 24 hours (i.e., the days parameter is set to 1) are limited to 60 per minute. All other requests are limited to 10 per minute.

To ensure your request is tracked properly, put the days parameter last.

Testing

For ease of testing, we provide a Postman collection: Mavenoid-Analytics-API.postman_collection.json

This collection includes sample calls for all the endpoints discussed on this page. To use it, import it into Postman and replace the Bearer token with your own (Mavenoid Analytics API → Authorization, replace the displayed Token with your own, and then save your changes).

If you don't change the bearer token, you’ll get dummy data rather than your organization's actual data.

Assistant conversations

The assistant conversations endpoint returns data about all assistant conversations for a selected period of up to 120 days. If a conversation involved any live chats, the data includes the latest live support session's status and the agent's resolution label.

A conversation occurs when a user opens the Mavenoid assistant and interacts with it in a meaningful way. If the assistant is embedded in a website or mobile app, this requires clicking/tapping a button (on a node that does not have "Step is triage" checked) or performing a search. If the assistant is in a Dynamic Help Center, where solution nodes may be presented as the result of an internet search, leaving the page open for ten seconds (on a non-autogenerated page) also counts as an interaction.

If the user opens the assistant but does not interact with it or visits a Dynamic Help Center page and closes it within ten seconds without interacting, this is considered a "bounce" and is not counted or tracked as a conversation.

Individual conversations

To retrieve all data for each individual conversation within the selected period, make the request without using the group_by parameter.

Endpoint

GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

How many days of data to fetch. Here a day is a period of 24 hours rather than a calendar day. If you set days=1 that will fetch the last 24 hours of data rather than the data for the current calendar day.

Response

A JSON Array where each record in the array has this schema:

interface AssistantConversation {
  id: string
  created_at: string // ISO8601 Timestamp
  updated_at: string // ISO8601 Timestamp
  flow_name: string
  touchpoint_name: string // This feature is still in private beta testing
  status:
    | "OPEN"
    | "RESOLVED"
    | "ESCALATED"
  label: string // The label, if set by a SetAnalyticsStatus node, otherwise the empty string
  lang_code: string

  latest_search_query: string | null // The search query the user typed, if any
  latest_search_result_chosen: string | null // The label of the result chosen, if any
  latest_search_shortcut_chosen: string | null // The label of the shortcut chosen, if any
  
  latest_live_support_session_status:
    | "WAITING_FOR_AGENT"
    | "ACTIVE"
    | "AGENT_TIMEOUT"
    | "CUSTOMER_SKIPPED"
    | "DECLINED_BY_AGENT"
    | "INACTIVITY_TIMEOUT"
    | "NO_AGENT_CAPACITY"
    | "RESOLVED"
    | null
  latest_live_support_session_resolution_label: string | null
    
  feedback_topics: string[] // Array of topics chosen by the user at the end of the session
  feedback_comments: string // Feedback entered by the user at the end of the session
  feedback_rating: 1 | 2 | 3 | 4 | null
  
  form_data: Record<string, JSON>
}

Examples

Request

Get all assistant conversations from the past 30 days:

GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json?days=30

Response

[
  {
    "id": "F1246",
    "created_at": "2023-05-03T10:59:03.000Z",
    "updated_at": "2023-05-03T11:02:10.000Z",
    "flow_name": "Scooter Support",
    "touchpoint_name": "Support Website",
    "status": "RESOLVED",
    "label": "",
    "lang_code": "en",
    "latest_search_query": "End my ride",
    "latest_search_result_chosen": "How do I end my ride?",
    "latest_search_shortcut_chosen": null,
    "latest_live_support_session_status": null,
    "latest_live_support_session_resolution_label": null,
    "feedback_topics": [],
    "feedback_comments": "This automated assistant was really helpful",
    "feedback_rating": 4,
    "form_data": {
      "$customer-email": "[email protected]",
      "$created-on-page-url": "https://example.com/support",
      "ride-end-api-response": "ok"
    }
  },
  {
    "id": "G2467",
    "created_at": "2023-05-04T10:59:03.000Z",
    "updated_at": "2023-05-04T11:02:10.000Z",
    "flow_name": "Scooter Support",
    "touchpoint_name": "Support Website",
    "status": "RESOLVED",
    "label": "",
    "lang_code": "en",
    "latest_search_query": "End my ride",
    "latest_search_result_chosen": "How do I end my ride?",
    "latest_search_shortcut_chosen": null,
    "latest_live_support_session_status": null,
    "latest_live_support_session_resolution_label": null,
    "feedback_topics": [],
    "feedback_comments": "Solved my problem",
    "feedback_rating": 4,
    "form_data": {
      "$customer-email": "[email protected]",
      "$created-on-page-url": "https://example.com/support",
      "ride-end-api-response": "ok"
    }
  },
]

Conversation summaries

To retrieve summary data including counts of conversations within the selected period grouped by particular criteria, use the group_by parameter in the request.

Endpoint

GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

`group_by`

A comma-separated list of fields by which to group data.

Available fields:

date
week
month
flow_name
touchpoint_name (This feature is still in private beta testing)
status
label
lang_code
latest_live_support_session_status
latest_live_support_session_resolution_label
feedback_rating

Response

A JSON Array where each record in the array contains the fields by which that record is grouped and the count of conversations that occurred in that group.

Grouping by any of date, week, or month will result in the response including the date field in each record, formatted as yyyy-mm-dd. If grouping by date this will be that day's date; if grouping by week it will be the Monday of that week; if grouping by month it will be the first of that month.

Examples

Request

Get the counts of conversations for each combination of flow and status for the past 24 hours.

GET https://analytics-api.mavenoid.com/v1/assistant-conversations.json?group_by=flow_name,status&days=1

Response

[
  {
    "flow_name": "Scooter Support",
    "status": "self_service_resolution",
    "count": 512
  },
  {
    "flow_name": "Scooter Support",
    "status": "live_support_resolution",
    "count": 256
  },
  {
    "flow_name": "Scooter Support",
    "status": "escalated",
    "count": 128
  },
  {
    "flow_name": "Washing Machine Support",
    "status": "self_service_resolution",
    "count": 1024
  },
  {
    "flow_name": "Washing Machine Support",
    "status": "live_support_resolution",
    "count": 64
  },
  {
    "flow_name": "Washing Machine Support",
    "status": "escalated",
    "count": 32
  }
]

Live support sessions

The live support sessions endpoint returns data about all live support sessions for a selected period of up to 120 days.

Individual sessions

To retrieve all data for each individual session within the selected period, make the request without using the group_by parameter.

Endpoint

GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

Response

A JSON Array where each record in the array has this schema:

interface LiveSupportSession {
  assistant_conversation_id: string
  assistant_conversation_created_at: string // ISO8601 Timestamp
  created_at: string // ISO8601 Timestamp
  updated_at: string // ISO8601 Timestamp
  agent_email: string | null
  agent_group_name: string | null
  queue_duration_ms: number // The time between the end user starting the session, and an agent accepting the conversation
  first_response_ms: number // The time between the end user starting the session, and the first message from an agent
  chat_duration_ms: number // The time between the end user starting the session, and the agent ending it
  status:
    | "WAITING_FOR_AGENT"
    | "ACTIVE"
    | "AGENT_TIMEOUT"
    | "CUSTOMER_SKIPPED"
    | "DECLINED_BY_AGENT"
    | "INACTIVITY_TIMEOUT"
    | "NO_AGENT_CAPACITY"
    | "RESOLVED"
    | "TRANSFERRED"
  resolution_label: string | null // custom resolutions can be added in the model
  debrief_labels: string[] // Array of labels chosen by agent after the session ends
  debrief_summary: string // Summary entered by agent after the session ends
  feedback_rating: 1 | 2 | 3 | 4 | null // The feedback rating the end user gave to the assistant conversation that this live support session belongs to
}

Examples

Request

Get all live support sessions from the past 30 days:

GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json?days=30

Response

[
  {
    "assistant_conversation_id": "F54321",
    "assistant_conversation_created_at": "2023-05-03T15:02:10.000Z",
    "created_at": "2023-05-03T15:03:00.000Z",
    "updated_at": "2023-05-03T15:08:00.000Z",
    "agent_email": "[email protected]",
    "agent_group_name": "Europe",
    "queue_duration_ms": 30000,
    "chat_duration_ms": 300000,
    "status": "RESOLVED",
    "resolution": "worked",
    "debrief_labels": ["scooter_breakdown"],
    "debrief_summary": "The scooter was broken and I had to order replacement parts for the customer"
  },
  {
    "assistant_conversation_id": "G65432",
    "assistant_conversation_created_at": "2023-05-04T15:02:10.000Z",
    "created_at": "2023-05-04T15:03:00.000Z",
    "updated_at": "2023-05-04T15:08:00.000Z",
    "agent_email": "[email protected]",
    "agent_group_name": "Europe",
    "queue_duration_ms": 30000,
    "chat_duration_ms": 300000,
    "status": "RESOLVED",
    "resolution": "worked",
    "debrief_labels": ["ride_refund"],
    "debrief_summary": "Ride refund issues for customer"
  },
]

Session summaries

To retrieve summary data including the count and aggregate statistics of sessions within the selected period grouped by particular criteria, use the group_by parameter in the request.

Endpoint

GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

`group_by`

A comma-separated list of fields to group data by to generate a summary.

Available fields:

date
week
month
agent_email
agent_group_name
status
resolution_label
feedback_rating

Response

A JSON Array where each record in the array contains the fields by which that record is grouped and the count of and statistics for sessions that occurred in that group.

The statistics for each group are:

queue_duration_ms_max
queue_duration_ms_mean
queue_duration_ms_sum
first_response_ms_max
first_response_ms_mean
first_response_ms_sum
chat_duration_ms_max
chat_duration_ms_mean
chat_duration_ms_sum

Examples

Request

Get counts and statistics for the sessions went to each agent on each day for the past 48 hours:

GET https://analytics-api.mavenoid.com/v1/live-support-sessions.json?group_by=date,agent_email&days=2

Response

[
  {
    "date": "2023-05-03",
    "agent_email": "[email protected]",
    "count": 256,
    "queue_duration_ms_max": 40000,
    "queue_duration_ms_mean": 30000,
    "queue_duration_ms_sum": 7680000,
    "first_response_ms_max": 41000,
    "first_response_ms_mean": 31000,
    "first_response_ms_sum": 7780000,
    "chat_duration_ms_max": 400000,
    "chat_duration_ms_mean": 300000,
    "chat_duration_ms_sum": 76800000
  },
  {
    "date": "2023-05-02",
    "agent_email": "[email protected]",
    "count": 300,
    "queue_duration_ms_max": 40000,
    "queue_duration_ms_mean": 30000,
    "queue_duration_ms_sum": 9000000,
    "first_response_ms_max": 41000,
    "first_response_ms_mean": 31000,
    "first_response_ms_sum": 7780000,
    "chat_duration_ms_max": 400000,
    "chat_duration_ms_mean": 300000,
    "chat_duration_ms_sum": 90000000
  }
]

Agent availability

The agent availability endpoint returns data about the times when each agent was available in the agent dashboard for a selected period of up to 120 days.

Individual availability periods

To retrieve all data for each individual availability period within the selected period, make the request without using the group_by parameter.

Endpoint

GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

Response

A JSON Array where each record in the array has this schema:

interface AgentAvailability {
  agent_email: string
  start_timestamp: string // ISO8601 Timestamp
  end_timestamp: string | null // ISO8601 Timestamp or null if agent is currently available
  duration_ms: number // How long was the agent marked as available for
  active_duration_ms: number // How long was the agent active in one or more session
}

Examples

Request

Get all agent availability information from the past 30 days:

GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?days=30

Response

[
  {
    "agent_email": "[email protected]",
    "start_timestamp": "2023-05-03T9:00:00.000Z",
    "end_timestamp": "2023-05-03T17:00:00.000Z",
    "duration_ms": 28800000,
    "active_duration_ms": 28000000
  },
  {
    "agent_email": "[email protected]",
    "start_timestamp": "2023-05-04T9:00:00.000Z",
    "end_timestamp": "2023-05-04T17:00:00.000Z",
    "duration_ms": 28800000,
    "active_duration_ms": 28000000
  }
]

Availability summaries

To retrieve summary data of availability periods within the selected period grouped by particular criteria, use the group_by parameter in the request.

Endpoint

GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json

Required parameters

`days`

An integer between 1 and 120 (inclusive).

`group_by`

A comma-separated list of fields to group data by to generate a summary.

Available fields:

date
week
month
agent-email

Response

A JSON Array where each record in the array contains the fields by which that record is groups and the statistics for that group.

The statistics for reach record are:

agent_count (if not grouping by agent_email)
duration_ms_sum
active_duration_ms_sum

Examples

Request

Get statistics for each agent's availability by date for the past 48 hours:

GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?group_by=date,agent_email&days=2

Response

[
  {
    "date": "2023-05-03",
    "agent_email": "[email protected]",
    "duration_ms_sum": 28800000,
    "active_duration_ms_sum": 28000000
  },
  {
    "date": "2023-05-02",
    "agent_email": "[email protected]",
    "duration_ms_sum": 28800000,
    "active_duration_ms_sum": 28000000
  }
]

Request

Get statistics for total agent availability by date for the past 48 hours:

GET https://analytics-api.mavenoid.com/v1/agent-availabilities.json?group_by=date&days=2

Response

[
  {
    "date": "2023-05-03",
    "agent_count": 2,
    "duration_ms_sum": 28800000,
    "active_duration_ms_sum": 28000000
  },
  {
    "date": "2023-05-02",
    "agent_count": 2,
    "duration_ms_sum": 28800000,
    "active_duration_ms_sum": 28000000
  }
]