Genies

Genies are voice AI agents managed through our agent system. Each genie has its own system prompt, voice configuration, conversation settings, and optional phone number.

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

List genies

Retrieves a paginated list of genies with essential fields. Optimized for selects, dropdowns, and summary views.

string

required

Must be "genies"

string

required

Must be "list"

object

Show properties

number

default:"30"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

string

Filter genies by name or description (case-insensitive). Can also be passed inside filters.

string

Filter by category (e.g. "Support", "Sales"). Can also be passed inside filters.

string

Filter by voice label (partial match). Can also be passed inside filters.

boolean

Filter by active status. Can also be passed inside filters.

boolean

Filter to public or private genies. Can also be passed inside filters.

boolean

Filter to demo genies only. Can also be passed inside filters.

boolean

Filter to marketplace genies. Can also be passed inside filters.

boolean

When true, return only marketplace genies (equivalent to isMarketplaceGenie: true).

boolean

When true, include marketplace genies in results (by default they are excluded).

object

Alternative nested form for any of the filter fields above (e.g. filters.searchTerm, filters.category). Also accepts the following admin-only field:

Show admin-only filter fields

string

Admin only. Filter by owner’s full name (partial, case-insensitive match). Only applies when adminMode is true.

boolean

default:"false"

Admin only. When true, includes owner profile in each item and allows userId filtering.

string

Admin only. Return genies owned by this user ID.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Unique genie identifier (UUID).

string

Owner user ID.

string

Genie display name.

string

Genie description.

boolean

Whether the genie is currently active.

string

Genie category (for example "Support", "Sales").

string

Primary purpose of the genie (e.g. "general", "support").

object

Branding configuration object, or null.

string

ISO 8601 creation timestamp.

object

Owner profile — present only when adminMode is true.

Show properties

string

User ID.

string

Full name.

string

Email address.

number

Total number of genies matching the filters.

number

The limit that was applied.

number

The offset that was applied.

const response = await ApiService.invoke("genies", "list", undefined, {
  limit: 30,
  offset: 0,
  searchTerm: "support",
  isActive: true,
});

curl -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "list",
    "data": {
      "limit": 30,
      "offset": 0,
      "searchTerm": "support"
    }
  }'

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Customer Support Bot",
        "description": "AI-powered customer support assistant",
        "is_active": true,
        "category": "Support",
        "purpose": "general",
        "branding": null,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 1,
    "limit": 30,
    "offset": 0
  }
}

Get all genies

Retrieves all genies with full configuration using cursor-based pagination. Returns complete genie objects including settings, phone, page, group, and knowledge base data.

string

required

Must be "genies"

string

required

Must be "all"

object

Show properties

number

default:"30"

Results per page, between 1 and 500.

string

Opaque pagination cursor returned from a previous request as nextCursor. Pass it unchanged to fetch the next page.

string

Filter by name or description (case-insensitive). Can also be passed inside filters.

string

Filter by category. Can also be passed inside filters.

string

Filter by voice label (partial match). Can also be passed inside filters.

boolean

Filter by active status. Can also be passed inside filters.

boolean

Filter to public or private genies. Can also be passed inside filters.

boolean

Filter to demo genies. Can also be passed inside filters.

boolean

Filter to marketplace genies. Can also be passed inside filters.

string

Filter by report mode (for example "every_conversation", "digest", "auto", "off"). Can also be passed inside filters.

string

Filter by group UUID. Pass "ungrouped" to return genies not assigned to any group.

number

Filter to genies with this specific daily call limit. Can also be passed inside filters.

string

Filter by the language model configured in the genie’s settings. Can also be passed inside filters.

boolean

default:"false"

Admin only. When true, includes owner profile information in the response.

string

Admin only. Filter genies to those owned by a specific user.

string

Admin only. Filter by owner profile role (for example "standard_user", "internal_admin"). Can also be passed inside filters.

boolean

Whether the request succeeded.

object

Show properties

array

Array of full genie objects. Each item has the same shape as the get genie response — see below.

string | null

Opaque cursor string. Pass as cursor in the next request to fetch the next page. null when there are no more results.

boolean

Whether more results are available beyond this page.

number

Total count of genies matching the filters.

// First page
const page1 = await ApiService.invoke("genies", "all", undefined, {
  limit: 25,
});

// Next page
const page2 = await ApiService.invoke("genies", "all", undefined, {
  limit: 25,
  cursor: page1.nextCursor,
});

curl -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "all",
    "data": {
      "limit": 25
    }
  }'

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Customer Support Bot",
        "description": "AI-powered customer support assistant",
        "brand": "Acme Corp",
        "is_active": true,
        "category": "Support",
        "voice": "EZ3epTG1EiOmx2GWRto6",
        "memory_enabled": false,
        "capture_leads": false,
        "purpose": "general",
        "settings": { "...": "full settings object" },
        "phone": { "id": "phone-123", "number": "+1234567890", "status": "active" },
        "transfer_phone": null,
        "page": { "id": "page-123", "url_name": "support-bot" },
        "group": { "id": "group-123", "name": "Support Genies" },
        "knowledge_base": [
          { "id": "doc-123", "name": "Product FAQ", "is_active": true }
        ],
        "escalation_webhook": null,
        "mailbox": null,
        "saved_qr_codes": [],
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "nextCursor": "eyJwb3NpdGlvbiI6MCwiY3JlYXRlZEF0IjoiMjAyNC0wMS0xNFQxNToyMDowMC4wMDBaIn0=",
    "hasMore": true,
    "total": 42
  }
}

When adminMode is true, each genie includes an owner field with id, full_name, email, and role. Standard users always see owner: null.

Get genie

Retrieves a single genie by ID with its full configuration, including settings, phone number, page, group, and knowledge base.

string

required

Must be "genies"

string

required

Must be "get"

string

required

The UUID of the genie to retrieve.

object

Show properties

boolean

default:"false"

Admin only. When true, includes the owner’s profile (id, full_name, email) in the response.

boolean

Whether the request succeeded.

object

Show properties

object

The full genie object.

Show properties

string

Unique genie identifier (UUID).

string

Owner user ID.

string

Genie display name.

string

Genie description.

string

Brand or company name.

string

Genie category.

object

Extended category metadata, or null.

boolean

Whether the genie is active.

boolean

Whether the genie has completed initial setup.

boolean

Whether the genie was explicitly deactivated by its owner (as opposed to being deactivated automatically by the system).

boolean

Whether the genie is publicly accessible.

boolean

Whether this genie is a marketplace genie.

boolean

Whether this genie is a demo genie.

string

Voice identifier used by the voice platform.

string

Human-readable label for the configured voice.

boolean

Whether conversation reports are sent after calls.

string

When reports are sent. One of "every_conversation", "digest", "auto", or "off".

string

Frequency for digest reports (e.g. "daily", "weekly"), or null.

number

Day of week for weekly digests (0 = Sunday), or null.

object

Escalation configuration, or null.

string

The prompt used to decide whether to send a report when report_mode is "auto". null when auto mode is not enabled or the prompt has not been generated yet.

string

ISO 8601 timestamp of when auto_report_decision_prompt was last generated, or null.

string

URL to redirect visitors after a conversation ends.

boolean

Whether lead capture is enabled.

boolean

Whether conversation memory is enabled for this genie.

boolean

Whether the voice-to-human bridge feature is enabled, allowing live handoff to a human agent during a call.

boolean

Whether the manual “Talk to a human” button is displayed on the genie page. Defaults to true. Only relevant when voice_bridge_enabled is true.

string

Primary purpose (e.g. "general").

string

URL-friendly slug for the genie’s web page.

string

Welcome message shown before a call begins.

array

Informational links attached to this genie, or null.

string

Genie type, or null.

object

Goal or lead info presets, or null.

object

Insights configuration, or null.

string

Associated persona ID, or null.

string[]

Email addresses of active report recipients (users who receive conversation report emails).

string[]

Email addresses of active escalation recipients (users who receive escalation notifications).

string[]

Email addresses of blocked report recipients (opted out of report emails).

string[]

Email addresses of blocked escalation recipients (opted out of escalation emails).

object

Full genie configuration including conversation config, TTS settings, and turn settings.

Show properties

string

Genie name in settings.

object

Show properties

object

Show properties

string

Initial greeting message.

object

Show properties

string

System prompt.

string

Language model identifier.

number

Model temperature (0–2).

number

Maximum response tokens.

object

Show properties

string

Voice synthesis model identifier.

string

Voice identifier used by the voice platform.

number

Voice stability (0–1).

number

Voice similarity (0–1).

number

Speech speed multiplier.

object

Show properties

boolean

Whether voice is disabled.

number

Maximum conversation duration in seconds.

object

Show properties

number

Seconds before a turn times out.

number

Seconds of silence before ending the call.

string

Turn detection mode (for example "silence").

object

Branding configuration, or null.

number

Display order position.

string

UUID of the group this genie belongs to, or null.

number

Maximum number of concurrent calls allowed.

object

Inbound phone number attached to this genie, or null.

Show properties

string

Phone record ID.

string

Genie ID linked to this number.

string

Phone number in E.164 format.

string

Human-readable label for the number.

string

Phone status (e.g. "active").

string

Two-letter country code.

object

Additional provider metadata, or null.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object

Phone number used for call transfers, or null. Same shape as phone.

object

Dedicated escalation phone number, or null. Same shape as phone. Distinct from transfer_phone — used for escalation flows rather than general call transfers.

object

Web page configuration, or null.

Show properties

string

Page record ID.

string

Genie ID linked to this page.

string

URL-friendly page slug.

string

Welcome message displayed on the page.

string

Target audience descriptor, or null.

string

URL of the genie’s avatar image, or null.

object

Page-level branding overrides, or null.

object

Feature flags for the page.

Show properties

boolean

Whether conversation feedback is enabled.

boolean

Whether business lead capture is enabled.

boolean

Whether consumer lead capture is enabled.

object

Page metadata.

Show properties

string

Post-conversation redirect URL.

string

Link to the genie sandbox preview, or null.

array

Informational links shown on the page, or null.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object

Escalation webhook status, or null.

Show properties

boolean

Whether the escalation webhook is active.

object

Email inbox attached to this genie, or null if no mailbox has been provisioned.

Show properties

string

Mailbox UUID.

string

UUID of the owning genie.

string

The provisioned mailbox email address.

string | null

Internal account reference used by the mail system, or null if not yet provisioned.

string | null

Connection grant identifier, or null.

string

Current status. One of "provisioned", "suspended", or "failed".

string | null

Most recent provisioning error, or null if healthy.

string | null

Fallback email address for messages the genie cannot handle, or null if not set.

boolean

Whether the mailbox is operating in test mode (emails are not delivered externally).

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object

Group the genie belongs to, or null.

Show properties

string

Group ID.

string

Group name.

string

Group description.

number

Group display order.

string

ISO 8601 creation timestamp.

array

Documents attached to this genie.

Show item properties

string

Document ID.

string

Document name.

boolean

Whether the document is active.

string

External knowledge base document ID used by the voice platform, or null.

string

Processing status of the document.

string

Source type (e.g. "file", "url").

string

Original source path or URL, or null.

string

Internal path to the parsed document, or null.

string

Internal path to the optimized document version, or null.

string

Folder this document belongs to, or null.

string

Owner user ID.

object

Document metadata, or null.

object

Document owner profile — present only when adminMode is true.

Show properties

string

User ID.

string

Full name.

string

Email address.

string

ISO 8601 creation timestamp.

array

QR codes saved for this genie (excludes deleted codes).

object

Owner profile — present only when adminMode is true.

Show properties

string

User ID.

string

Full name.

string

Email address.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

const response = await ApiService.invoke(
  "genies",
  "get",
  "550e8400-e29b-41d4-a716-446655440000"
);
const genie = response?.agent;

curl -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "get",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "data": {
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Customer Support Bot",
      "description": "AI-powered customer support assistant",
      "brand": "Acme Corp",
      "category": "Support",
      "is_active": true,
      "is_setup": false,
      "is_public": false,
      "is_marketplace_genie": false,
      "is_demo_genie": false,
      "voice": "EZ3epTG1EiOmx2GWRto6",
      "voice_label": "Rachel",
      "send_conv_reports": true,
      "report_mode": "every_conversation",
      "capture_leads": false,
      "memory_enabled": false,
      "voice_bridge_enabled": false,
      "voice_bridge_show_button": true,
      "purpose": "general",
      "url_name": "support-bot",
      "welcome_message": "Let's connect with our support team",
      "redirect_url": null,
      "settings": {
        "name": "Customer Support Bot",
        "conversation_config": {
          "agent": {
            "first_message": "Hello! Welcome to our support team. How can I help you today?",
            "prompt": {
              "prompt": "You are a helpful customer support representative...",
              "llm": "gemini-3-flash-preview",
              "temperature": 0.7,
              "max_tokens": 8000
            }
          },
          "tts": {
            "model_id": "multilingual_v2",
            "voice_id": "550e8400-e29b-41d4-a716-446655440009",
            "stability": 0.5,
            "similarity_boost": 0.8,
            "speed": 1.0
          },
          "conversation": {
            "text_only": false,
            "max_duration_seconds": 600
          },
          "turn": {
            "turn_timeout": 7,
            "silence_end_call_timeout": 30,
            "mode": "silence"
          }
        }
      },
      "branding": null,
      "position": 0,
      "group_id": null,
      "call_limit": 10,
      "phone": {
        "id": "phone-123",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "number": "+1234567890",
        "friendly_name": "Support Line",
        "status": "active",
        "country_code": "US",
        "metadata": null,
        "created_at": "2024-01-10T08:00:00.000Z",
        "updated_at": "2024-01-10T08:00:00.000Z"
      },
      "transfer_phone": null,
      "page": {
        "id": "page-123",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "url_name": "support-bot",
        "welcome_message": "Let's connect with our support team",
        "target_audience": null,
        "genie_image_url": null,
        "branding": null,
        "flags": {
          "feedback": true,
          "business_lead": false,
          "consumer_lead": false
        },
        "metadata": { "redirect_url": null },
        "sandbox_link": null,
        "info_links": null,
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      },
      "escalation_webhook": null,
      "mailbox": {
        "id": "mbx-uuid-001",
        "agent_id": "550e8400-e29b-41d4-a716-446655440000",
        "email_address": "support-bot@mail.helpgenie.ai",
        "account_id": "acct-abc123",
        "grant_id": null,
        "status": "provisioned",
        "last_error": null,
        "escalation_address": null,
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      },
      "group": null,
      "knowledge_base": [
        {
          "id": "doc-123",
          "name": "Product FAQ",
          "is_active": true,
          "status": "processed",
          "source_type": "file",
          "folder_id": null,
          "user_id": "660e8400-e29b-41d4-a716-446655440001",
          "metadata": null,
          "created_at": "2024-01-12T09:00:00.000Z"
        }
      ],
      "saved_qr_codes": [],
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Create genie

Creates a new voice AI genie with the specified configuration. The genie is automatically provisioned in the voice agent system.

string

required

Must be "genies"

string

required

Must be "create"

object

required

Show properties

string

required

Display name for the genie.

string

required

Primary use case describing what the genie does.

string

required

System prompt defining the genie’s behavior and personality.

string

required

Initial greeting message spoken when a conversation starts.

string

required

Welcome message displayed on the web interface before a call begins.

string

Voice identifier. Defaults to the platform default voice.

string

default:"gemini-3-flash-preview"

Language model identifier.

number

default:"0.7"

Model temperature between 0 and 2.

number

default:"8000"

Maximum number of tokens in the response.

boolean

default:"true"

Enable multilingual voice support.

number

default:"0.5"

Voice stability between 0 and 1.

number

default:"0.8"

Voice similarity between 0 and 1.

number

default:"1.0"

Speech speed multiplier.

object

Show properties

number

default:"600"

Maximum conversation duration in seconds.

number

default:"7"

Seconds before a turn times out.

number

default:"30"

Seconds of silence before ending the call.

string

default:"silence"

Turn detection mode.

string

Brand or company name.

string

Genie category or type.

string

Detailed description of the genie.

string[]

Email addresses for the support team.

string

default:"en"

Primary language code for the genie (e.g. "en", "es", "fr").

boolean

default:"false"

Enable lead capture — the genie will collect contact details from callers.

string

URL to redirect visitors to after a conversation ends.

string

Two-letter ISO country code (e.g. "US", "GB", "AU").

string

Descriptive voice style preference when voiceId is not a specific ID (e.g. "professional", "friendly", "calm", "energetic").

object[]

Custom pronunciation overrides. Each item must include word and pronunciation.

object

Key-value pairs injected into the system prompt at runtime (e.g. { "customer_name": "Jane", "order_number": "ORD-001" }).

string

UUID of an insight/goal to attach to this genie. Each genie supports one goal.

string

UUID of a persona to attach to this genie.

boolean

Enable conversation memory so the genie remembers context across sessions.

boolean

default:"true"

Send email reports after each conversation. Alias for sendConversationReports.

boolean

default:"true"

Send email reports after each conversation.

boolean

default:"false"

Provision and attach a phone number to this genie.

boolean

Whether the request succeeded.

string

Confirmation message.

object

Show properties

string

Genie UUID.

string

Owner user ID.

string

Genie name.

string

Genie description.

string

Brand name.

string

Category.

boolean

Active status.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

const response = await ApiService.invoke("genies", "create", undefined, {
  genieName: "Customer Support Bot",
  useCase: "Handle customer support inquiries",
  systemPrompt:
    "You are a helpful customer support representative. Be friendly and professional.",
  firstMessage:
    "Hello! Welcome to our support team. How can I help you today?",
  webWelcomeMessage: "Let's connect with our support team",
  voiceId: "EZ3epTG1EiOmx2GWRto6",
  llmModel: "gemini-3-flash-preview",
  temperature: 0.7,
  maxTokens: 8000,
  brand: "Acme Corp",
  category: "Support",
  description: "AI-powered customer support assistant",
  supportEmails: ["support@acme.com"],
  sendConversationReports: true,
  attachPhoneNumber: false,
});

curl -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "create",
    "data": {
      "genieName": "Customer Support Bot",
      "useCase": "Handle customer support inquiries",
      "systemPrompt": "You are a helpful customer support representative. Be friendly and professional.",
      "firstMessage": "Hello! Welcome to our support team. How can I help you today?",
      "webWelcomeMessage": "Let us connect with our support team",
      "voiceId": "EZ3epTG1EiOmx2GWRto6",
      "brand": "Acme Corp",
      "category": "Support",
      "description": "AI-powered customer support assistant",
      "supportEmails": ["support@acme.com"],
      "sendConversationReports": true,
      "attachPhoneNumber": false
    }
  }'

{
  "success": true,
  "message": "Genie created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Customer Support Bot",
    "description": "AI-powered customer support assistant",
    "brand": "Acme Corp",
    "category": "Support",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

Admin users can create genies on behalf of other users by including impersonatedUserId in the data object.

Update genie

Updates an existing genie’s configuration. Supports partial updates — only the fields you include will be changed.

string

required

Must be "genies"

string

required

Must be "update"

string

required

The UUID of the genie to update.

object

required

Show properties

string

Updated genie name. Also accepted as genieName.

string

Updated description.

boolean

Enable or disable the genie.

boolean

Toggle lead capture.

string

Change the post-conversation redirect URL.

string

UUID of the group to move the genie into.

boolean

Mark as a demo genie.

boolean

Mark as a marketplace genie.

boolean

Make the genie publicly accessible.

number

Reorder the genie in the list (zero-indexed position).

boolean

Toggle conversation report emails.

boolean

Enable or disable conversation memory.

string

UUID of the persona to attach. Pass null to remove the current persona.

string

Genie type.

string

Admin only. Transfer ownership to another user.

string

URL slug for the live-agent page. Automatically sanitised and made unique.

string

Welcome text shown before a conversation begins (top-level shorthand).

object

Informational links shown on the genie page (top-level shorthand).

string

Shorthand for settings.conversation_config.agent.first_message.

string

Voice synthesis model ID used when isMultilingual is true (e.g. "eleven_multilingual_v2").

object

Update agent page fields directly.

Show properties

string

Page URL slug.

string

Welcome message on the page.

object

Info links on the page.

string

Page name.

string

Brand colour hex.

boolean

Toggle page visibility.

object

Nested settings object. Fields are merged, not replaced.

Show properties

object

Show properties

object

Show properties

string

Updated greeting.

object

Show properties

string

Updated system prompt.

number

Model temperature (0–2).

number

Max response tokens.

object

Show properties

string

New voice identifier for the voice platform.

number

Voice stability (0–1).

number

Voice similarity (0–1).

number

Speech speed multiplier.

object

Branding configuration. Merged with existing branding.

boolean

Whether the request succeeded.

string

Confirmation message.

object

Show properties

string

Genie UUID.

string

Updated genie name.

string

Updated description.

string

ISO 8601 timestamp.

const response = await ApiService.invoke(
  "genies",
  "update",
  "550e8400-e29b-41d4-a716-446655440000",
  {
    name: "Updated Bot Name",
    description: "Updated description",
    settings: {
      conversation_config: {
        agent: {
          first_message: "Updated greeting message",
          prompt: {
            prompt: "You are an advanced customer support AI...",
            temperature: 0.8,
            max_tokens: 2048,
          },
        },
        tts: {
          voice_id: "new-voice-id",
          stability: 0.8,
          similarity_boost: 0.9,
          speed: 1.05,
        },
      },
    },
  }
);

{
  "resource": "genies",
  "action": "update",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "name": "Updated Bot Name",
    "description": "Updated description",
    "settings": {
      "conversation_config": {
        "agent": {
          "first_message": "Updated greeting message",
          "prompt": {
            "prompt": "You are an advanced customer support AI...",
            "temperature": 0.8,
            "max_tokens": 2048
          }
        },
        "tts": {
          "voice_id": "new-voice-id",
          "stability": 0.8,
          "similarity_boost": 0.9,
          "speed": 1.05
        }
      }
    }
  }
}

{
  "success": true,
  "message": "Genie updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Bot Name",
    "description": "Updated description",
    "updated_at": "2024-01-15T11:00:00.000Z"
  }
}

Delete genie

Permanently deletes a genie, removes it from the voice agent system, and releases any associated phone numbers.

string

required

Must be "genies"

string

required

Must be "delete"

string

required

The UUID of the genie to delete.

boolean

Whether the request succeeded.

string

Confirmation message.

This action is irreversible. The genie, its external agent instance, and any attached phone numbers will be permanently removed.

const response = await ApiService.invoke(
  "genies",
  "delete",
  "550e8400-e29b-41d4-a716-446655440000"
);

{
  "resource": "genies",
  "action": "delete",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "success": true,
  "message": "Genie deleted successfully"
}

Clone genie

Creates a copy of an existing genie with all its configuration. Optionally rename the clone and apply text replacements to the system prompt and first message.

string

required

Must be "genies"

string

required

Must be "clone"

string

required

The UUID of the genie to clone.

object

Show properties

string

Name for the cloned genie. Defaults to "Copy of {original name}".

array

Array of string replacements applied to the system prompt and first message. Useful for white-labeling.

Show item properties

string

required

Text to find.

string

required

Replacement text.

string

Admin only. Create the clone under this user’s account instead of the caller’s.

boolean

Whether the request succeeded.

object

Show properties

boolean

object

The newly created clone.

curl -s -X POST https://api.helpgenie.ai/v1/genies \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "clone",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "name": "Support Bot v2",
      "promptReplacements": [
        { "from": "Acme Corp", "to": "New Brand" }
      ]
    }
  }'

{
  "resource": "genies",
  "action": "clone",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "name": "Support Bot v2",
    "promptReplacements": [
      { "from": "Acme Corp", "to": "New Brand" }
    ]
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "agent": {
      "id": "new-genie-uuid",
      "name": "Support Bot v2",
      "created_at": "2024-01-15T12:00:00.000Z"
    }
  }
}

Attached knowledge base documents are cloned and linked to the new genie automatically. If a document clone fails (for example due to a transient error), the genie itself is still created — only that document is skipped. Goal associations from the original genie are also copied to the clone.

Reorder genies

Updates the display order of genies. Pass an object mapping genie IDs to their desired position (zero-indexed).

string

required

Must be "genies"

string

required

Must be "reorder"

object

required

Show properties

object

required

An object where keys are genie UUIDs and values are integer positions starting from 0.

boolean

Whether the request succeeded.

string

Confirmation message.

const response = await ApiService.invoke("genies", "reorder", undefined, {
  sort: {
    "550e8400-e29b-41d4-a716-446655440000": 0,
    "990e8400-e29b-41d4-a716-446655440004": 1,
    "aa0e8400-e29b-41d4-a716-446655440005": 2,
  },
});

{
  "resource": "genies",
  "action": "reorder",
  "data": {
    "sort": {
      "550e8400-e29b-41d4-a716-446655440000": 0,
      "990e8400-e29b-41d4-a716-446655440004": 1,
      "aa0e8400-e29b-41d4-a716-446655440005": 2
    }
  }
}

{
  "success": true,
  "message": "Genies reordered successfully"
}

Analytics

Returns conversation analytics per genie — total conversations, recent conversations (last 7 days), and last-used timestamp.

string

required

analytics

object

Show properties

boolean

Admin only. Return analytics across all users.

string

Admin only. Scope to a specific user.

Response

Returns an array of analytics objects (one per genie):

array

Show Item properties

string

Genie UUID.

string

Genie name.

number

Total conversation count.

number

Conversations in the last 7 days.

string | null

ISO 8601 timestamp of most recent conversation.

string | null

Brand name.

boolean

Whether this genie belongs to a workspace owner rather than the authenticated user directly.

object | null

Owner profile (admin mode only).

Limits

Returns the genie quota for the authenticated user’s personal account and, if applicable, their workspace (team).

string

required

limits

Response

object

Show properties

object

Quota for the authenticated user’s own account.

Show properties

number

Number of genies currently owned by the user.

number

Maximum genies allowed. Admin users have no enforced cap.

boolean

Whether currentCount has reached maxGenies.

object | null

Quota for the workspace owner’s account — present when the caller is a team owner or team member, null otherwise. Same shape as personal.

const response = await ApiService.invoke("genies", "limits");
const { personal, team } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource": "genies", "action": "limits"}'

{
  "success": true,
  "data": {
    "personal": {
      "currentCount": 3,
      "maxGenies": 4,
      "isAtLimit": false
    },
    "team": null
  }
}

Timeline

Returns a day-by-day conversation count for a genie over a specified date range.

string

required

timeline

string

required

Genie UUID.

object

required

Show properties

string

required

ISO 8601 start date (inclusive).

string

required

ISO 8601 end date (inclusive).

Response

{
  "agentId": "agent-uuid",
  "agentName": "Support Genie",
  "data": [
    { "date": "2024-01-01", "conversations": 3 },
    { "date": "2024-01-02", "conversations": 7 }
  ]
}

URL lookup (authenticated)

Loads a genie by its URL slug. Used by authenticated surfaces (the widget, the genie page, team members) to bootstrap a conversation. Returns the full genie object and, for consumer users where memory is enabled, the caller’s stored memory context. Access is granted when the caller is the genie’s owner, an admin, a workspace team member, holds a valid time-limited access grant, or the genie is public or a marketplace genie. Inactive genies return NOT_FOUND even when access would otherwise be allowed.

For fully public (unauthenticated) genie loading — used by embedded widgets before a user signs in — use the url action on the public genies resource instead.

string

required

Must be "genies"

string

required

Must be "url"

object

required

Show properties

string

required

URL slug of the genie. Can also be passed as a query parameter.

boolean

Whether the request succeeded.

object

Show properties

object

Full genie object. Same shape as the get action response — see above.

string | null

Formatted memory context string for the authenticated consumer, or null. Only populated for consumer-role users when the genie has memory_enabled: true and the user has granted memory consent.

The consumer’s current memory consent state. One of "unset", "granted", or "revoked". Always present; "unset" means the user has not yet been asked.

Private genie error (when access is not allowed):

{
  "success": false,
  "error": {
    "code": "GENIE_PRIVATE",
    "message": "This Genie is private",
    "status": 403,
    "genieName": "Support Genie"
  }
}

const response = await ApiService.invoke("genies", "url", undefined, {
  url_name: "support-bot",
});
const { agent, userMemory, memoryConsent } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "url",
    "data": { "url_name": "support-bot" }
  }'

{
  "success": true,
  "data": {
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support Bot",
      "url_name": "support-bot",
      "is_active": true,
      "is_public": true
    },
    "userMemory": null,
    "memoryConsent": "unset"
  }
}

Embed code

Returns an HTML embed snippet for embedding a genie on an external website.

string

required

embed-code

string

required

Genie UUID.

Request access

Submits an access request for a private genie. Used when a visitor wants to access a genie they don’t have permission for.

string

required

request-access

string

required

Genie UUID.

Accept invite

Accepts an invitation to access a genie using an access token.

string

required

accept-invite

string

required

Genie UUID.

Signature style

Retrieves and, if necessary, initializes a genie’s email signature style. Fills in a default signatureStyle object when absent, and always refreshes the phoneNumber and liveUrl snapshots within signatureStyle to match the genie’s current phone and public URL. Once signatureStyle exists, only the snapshot fields are ever refreshed — layout preferences and toggle states set by the user are never overwritten. Other branding fields (colors, logo) are never modified by this action.

string

required

Must be "genies"

string

required

Must be "signature-style"

string

required

The UUID of the genie.

boolean

Whether the request succeeded.

object

Show properties

object

The genie’s full branding object after healing. If signatureStyle was absent it has now been added; all other branding fields are returned as-is.

Show signatureStyle properties

boolean

Whether the email signature block is enabled.

string

Signature layout variant (e.g. "standard").

boolean

Whether the genie description is shown in the signature.

boolean

Whether the genie avatar is shown.

boolean

Whether the QR code is shown.

boolean

Whether channel badges are shown.

string | null

Custom text override for the signature body, or null.

string | null

Snapshot of the genie’s primary phone number, or null.

string | null

Snapshot of the genie’s public live-agent URL, or null.

boolean

true if any defaults were applied or snapshots were refreshed; false if the branding was already fully initialised and up to date.

const response = await ApiService.invoke(
  "genies",
  "signature-style",
  "550e8400-e29b-41d4-a716-446655440000"
);
const { branding, healed } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "genies",
    "action": "signature-style",
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "data": {
    "branding": {
      "primaryColor": "#4E9CFF",
      "signatureStyle": {
        "enabled": true,
        "layout": "standard",
        "showDescription": true,
        "showMascot": true,
        "showQrCode": true,
        "showChannelBadges": true,
        "textOverride": null,
        "phoneNumber": "+1234567890",
        "liveUrl": "https://helpgenie.ai/live-agent/support-bot"
      }
    },
    "healed": true
  }
}

Error codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid token
`INVALID_TOKEN`	401	Token validation failed
`FORBIDDEN`	403	User lacks required permissions
`AGENT_NOT_FOUND`	404	Genie not found or access denied
`VALIDATION_ERROR`	400	Invalid request parameters
`INTERNAL_ERROR`	500	Server error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List genies

Get all genies

Get genie

Create genie

Update genie

Delete genie

Clone genie

Reorder genies

Analytics

Response

Limits

Response

Timeline

Response

URL lookup (authenticated)

Embed code

Request access

Accept invite

Signature style

Error codes

​List genies

​Get all genies

​Get genie

​Create genie

​Update genie

​Delete genie

​Clone genie

​Reorder genies

​Analytics

​Response

​Limits

​Response

​Timeline

​Response

​URL lookup (authenticated)

​Embed code

​Request access

​Accept invite

​Signature style

​Error codes

List genies

Get all genies

Get genie

Create genie

Update genie

Delete genie

Clone genie

Reorder genies

Analytics

Response

Limits

Response

Timeline

Response

URL lookup (authenticated)

Embed code

Request access

Accept invite

Signature style

Error codes