Insights

Insights (also accepted as goals for backward compatibility) let you define measurable targets — such as lead capture rate or booking completion — and track them against your genies’ conversations.

Standard users can only manage their own insights. Admin users can view and manage all insights by passing adminMode: true.

List all insights

Returns all insights with full details for the authenticated user.

string

required

Must be "insights"

string

required

Must be "all"

object

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. When true, returns insights across all users.

string

Admin only. Return insights owned by this user ID.

object

Show properties

string

Filter to insights attached to a specific genie.

boolean

object

Show properties

object[]

Array of insight objects.

number

List insights

Returns a paginated list of insights for the authenticated user.

string

required

Must be "insights"

string

required

Must be "list"

object

Show properties

string

Filter insights by name (case-insensitive).

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

default:"false"

Admin only. When true, returns insights across all users.

string

Admin only. Return insights owned by this user ID.

boolean

object

Show properties

object[]

Array of insight objects.

number

Get insight

Retrieves a single insight by ID.

string

required

Must be "insights"

string

required

Must be "get"

string

required

The insight UUID.

object

Show properties

boolean

default:"false"

Admin only. When true, allows fetching insights owned by other users.

Create insight

Creates a new insight metric.

string

required

Must be "insights"

string

required

Must be "create"

object

required

Show properties

string

required

Insight name (e.g. "Lead capture rate").

string

A short description of what this insight measures.

object[]

Field definitions for the information this insight collects. Every field needs a non-empty key and label, otherwise the call returns VALIDATION_ERROR.

Show item properties

string

required

Field key in lowercase_with_underscores. Collected data is stored under this key.

string

required

Human-readable field label.

string

One of text, email, phone, textarea, select.

boolean

Whether the genie should always try to collect this field.

string[]

Choices for select fields only.

boolean

When true, marks this insight as a default template that appears as a starting point for new insights.

string

Admin only. Create the insight on behalf of this user instead of the caller.

To build an insight for a genie, call Generate insight with the genie’s agentId first, pass its name, description and fields here, then attach it. Hand-written field lists tend to drift from what the genie actually does.

boolean

object

Show properties

object

The created insight object.

const response = await ApiService.invoke({
  resource: "insights",
  action: "create",
  data: {
    name: "Lead capture rate",
    description: "Percentage of conversations that result in a captured lead",
    fields: [
      { key: "full_name", label: "Full name", type: "text", required: true },
      { key: "email", label: "Email", type: "email", required: true },
    ],
    is_default: false,
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "create",
    "data": {
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [
        { "key": "full_name", "label": "Full name", "type": "text", "required": true },
        { "key": "email", "label": "Email", "type": "email", "required": true }
      ],
      "is_default": false
    }
  }'

Update insight

Updates an existing insight. Supports partial updates — send only the fields you want to change.

string

required

Must be "insights"

string

required

Must be "update"

string

required

The insight ID. Must be numeric — a non-numeric value returns VALIDATION_ERROR.

object

Show properties

string

New insight name.

string

New description of what this insight measures.

object[]

Replaces the whole field list — same shape as on create. Every field needs a non-empty key and label, otherwise the call returns VALIDATION_ERROR. Keep the key of an existing field unchanged: collected data is stored under it.

Show item properties

string

required

Field key in lowercase_with_underscores. Collected data is stored under this key.

string

required

Human-readable field label.

string

One of text, email, phone, textarea, select.

boolean

Whether the genie should always try to collect this field.

string[]

Choices for select fields only.

boolean

When true, marks this insight as a default template that appears as a starting point for new insights.

boolean

default:"false"

Admin only. When true, allows updating insights owned by other users and includes the owner profile in the response.

Only name, description, fields, and is_default are applied. If data contains none of them — for example when it carries only unrelated keys — nothing is written and the insight is returned unchanged, with the same response shape as a successful update.

boolean

object

Show properties

object

The updated insight.

Show properties

number

Insight ID.

string | null

Insight name.

string | null

Insight description.

object[] | null

Field definitions for the tracked metrics.

boolean | null

Whether this insight is a default template.

string

ISO 8601 creation timestamp.

object[]

Genies this insight is attached to. Omitted when there are none.

Show item properties

string

Genie ID.

string

Genie name.

object

Owner profile — present only when adminMode is true.

Show properties

string

User ID.

string

Full name.

string

Email address.

object

The same object as insight, kept for backward compatibility.

const response = await ApiService.invoke({
  resource: "insights",
  action: "update",
  id: "42",
  data: {
    name: "Lead capture rate",
    is_default: true,
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "update",
    "id": "42",
    "data": {
      "name": "Lead capture rate",
      "is_default": true
    }
  }'

{
  "success": true,
  "data": {
    "insight": {
      "id": 42,
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [{ "label": "Leads captured", "key": "leads_captured" }],
      "is_default": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    "goal": {
      "id": 42,
      "name": "Lead capture rate",
      "description": "Percentage of conversations that result in a captured lead",
      "fields": [{ "label": "Leads captured", "key": "leads_captured" }],
      "is_default": true,
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Delete insight

Permanently deletes an insight. A default insight (is_default: true) cannot be deleted — update it with is_default: false first.

string

required

Must be "insights"

string

required

Must be "delete"

string

required

The insight UUID.

This action is irreversible.

Attach insight to genie

Links an insight to a genie. Each genie can have only one insight attached at a time — attaching a new one replaces the existing attachment.

string

required

Must be "insights"

string

required

Must be "attach"

object

required

Show properties

string

required

UUID of the genie to attach the insight to.

number

required

ID of the insight to attach. Required unless goalId is given.

number

deprecated

Backward-compatible alias for insightId. Used only when insightId is absent.

boolean

await ApiService.invoke({
  resource: "insights",
  action: "attach",
  data: {
    agentId: "agent-uuid",
    insightId: 42,
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "attach",
    "data": {
      "agentId": "agent-uuid",
      "insightId": 42
    }
  }'

Detach insight from genie

Removes the insight attachment from a genie.

string

required

Must be "insights"

string

required

Must be "detach"

object

required

Show properties

string

required

UUID of the genie to detach the insight from.

Generate insight

Builds a tailored insight — name, description and fields — matched to a genie’s business, audience and job. Nothing is saved: review the result, then pass it to Create insight and attach it to the genie.

string

required

Must be "insights"

string

required

Must be "generate"

object

required

Show properties

string

Recommended. UUID of the genie the insight is for. Its brand, category, purpose and instructions are loaded server-side so the fields match what the genie actually does. Returns AGENT_NOT_FOUND if you don’t have access to the genie.

string

What you want to collect or achieve, in your own words (e.g. "Track how often callers book an appointment"). Anything you name is always included. Required unless agentId is given.

object

Context for a genie that is not saved yet. Non-empty values override what agentId loads.

Show properties

string

Genie name.

string

Genie description.

string

Genie’s primary purpose.

string

Genie’s instructions.

Without agentId or genieContext, fields are inferred from the description alone and come out more generic. The call fails with INTERNAL_ERROR when fewer than 3 usable fields can be produced.

boolean

object

Show properties

string

Suggested insight name.

string

Suggested description.

object[]

Suggested field definitions, ready to pass to create.

Show item properties

string

Field key in lowercase_with_underscores.

string

Human-readable label.

string

One of text, email, phone, textarea, select.

boolean

Whether the field should always be collected.

string[]

Choices — present for select fields only.

number

Confidence score between 0 and 1.

string | null

What the generator understood the genie to be for.

const result = await ApiService.invoke({
  resource: "insights",
  action: "generate",
  data: {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    description: "Track how often callers book an appointment",
  },
});

curl -X POST https://api.helpgenie.ai/v1/insights \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "insights",
    "action": "generate",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "description": "Track how often callers book an appointment"
    }
  }'

{
  "success": true,
  "data": {
    "name": "Appointment bookings",
    "description": "Details captured when a caller books or asks about an appointment",
    "fields": [
      { "key": "full_name", "label": "Full name", "type": "text", "required": true },
      { "key": "phone", "label": "Phone number", "type": "phone", "required": true },
      { "key": "service_type", "label": "Service", "type": "select", "required": false, "options": ["Consultation", "Follow-up"] },
      { "key": "preferred_date", "label": "Preferred date", "type": "text", "required": false }
    ],
    "confidence": 0.8,
    "geniePurpose": "Books appointments for a dental clinic"
  }
}

Error codes

Code	Meaning
`VALIDATION_ERROR`	Missing or invalid required parameter
`NOT_FOUND`	Insight not found
`AGENT_NOT_FOUND`	Genie not found or not accessible (`generate`)
`FORBIDDEN`	Access denied
`INTERNAL_ERROR`	Unexpected server error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List all insights

List insights

Get insight

Create insight

Update insight

Delete insight

Attach insight to genie

Detach insight from genie

Generate insight

Error codes

​List all insights

​List insights

​Get insight

​Create insight

​Update insight

​Delete insight

​Attach insight to genie

​Detach insight from genie

​Generate insight

​Error codes

List all insights

List insights

Get insight

Create insight

Update insight

Delete insight

Attach insight to genie

Detach insight from genie

Generate insight

Error codes