> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Activation Packs

> Create and manage launch packs that bundle a genie or portal with promotional copy, branding, and distribution channels

Activation packs tie a genie or portal to a collection of launch assets: channel configuration, branding overrides, promotional copy, and generated marketing materials. When a pack is created, promotional copy for all templates is automatically generated in the background.

<Note>
  Standard users can only access their own activation packs. Admin users can access any user's packs by passing `adminMode: true` and `userId`.
</Note>

***

## List activation packs

Returns a paginated list of activation packs for the authenticated user.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `list`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="agent_id" type="string">
      Filter to packs linked to a specific genie.
    </ParamField>

    <ParamField body="portal_id" type="string">
      Filter to packs linked to a specific portal.
    </ParamField>

    <ParamField body="limit" type="number" default="50">
      Results per page. Maximum 500.
    </ParamField>

    <ParamField body="offset" type="number" default="0">
      Number of results to skip.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only. Access packs belonging to another user.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="items" type="ActivationPack[]">
  Array of activation pack objects. See the `get` action for the full object shape.
</ResponseField>

<ResponseField name="count" type="number">
  Total number of matching packs.
</ResponseField>

<ResponseField name="limit" type="number">
  The limit that was applied.
</ResponseField>

<ResponseField name="offset" type="number">
  The offset that was applied.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "list",
    data: {
      agent_id: "genie-uuid",
      limit: 20,
      offset: 0,
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "list",
      "data": {
        "agent_id": "genie-uuid",
        "limit": 20,
        "offset": 0
      }
    }'
  ```
</CodeGroup>

***

## Get activation pack

Retrieves a single activation pack by ID, including nested genie and portal data.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `get`
</ParamField>

<ParamField body="id" type="string" required>
  The activation pack UUID.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">
      Admin only. Fetch a pack owned by another user.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="activationPack" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Pack UUID.</ResponseField>
    <ResponseField name="name" type="string">Pack name.</ResponseField>
    <ResponseField name="description" type="string | null">Pack description.</ResponseField>
    <ResponseField name="agent_id" type="string | null">Linked genie UUID, or `null` if linked to a portal.</ResponseField>
    <ResponseField name="portal_id" type="string | null">Linked portal UUID, or `null` if linked to a genie.</ResponseField>

    <ResponseField name="channels" type="object">
      Enabled distribution channels. Boolean flags for `web_widget`, `phone`, `sms`, `whatsapp`, and similar channels.
    </ResponseField>

    <ResponseField name="branding_overrides" type="object | null">
      Optional branding overrides applied on top of the linked genie or portal branding.
    </ResponseField>

    <ResponseField name="asset_config" type="object | null">
      Configuration for generated marketing assets (QR codes, banners, etc.).
    </ResponseField>

    <ResponseField name="generated_assets" type="object | null">
      Results of the most recent asset generation run.
    </ResponseField>

    <ResponseField name="promo_content" type="object | null">
      Generated promotional copy, keyed by template then tone. For example `promo_content.launch_email.friendly.body`.
    </ResponseField>

    <ResponseField name="touchpoints" type="object | null">
      Distribution touchpoint configuration.
    </ResponseField>

    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>

    <ResponseField name="agent" type="object | null">
      Nested genie data, present when `agent_id` is set.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Genie ID.</ResponseField>
        <ResponseField name="name" type="string">Genie name.</ResponseField>
        <ResponseField name="branding" type="object | null">Genie branding configuration.</ResponseField>
        <ResponseField name="page" type="object | null">Public page info. Contains `url_name`.</ResponseField>
        <ResponseField name="phone" type="object | null">Phone number info. Contains `phone_number`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="portal" type="object | null">
      Nested portal data, present when `portal_id` is set.

      <Expandable title="properties">
        <ResponseField name="id" type="string">Portal ID.</ResponseField>
        <ResponseField name="name" type="string">Portal name.</ResponseField>
        <ResponseField name="slug" type="string">Portal URL slug.</ResponseField>
        <ResponseField name="branding" type="object | null">Portal branding configuration.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "get",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "get",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

***

## Create activation pack

Creates a new activation pack linked to a genie or portal. After creation, promotional copy for all templates is generated automatically in the background.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `create`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Pack display name.
    </ParamField>

    <ParamField body="agent_id" type="string">
      Link this pack to a specific genie. Either `agent_id` or `portal_id` should be provided.
    </ParamField>

    <ParamField body="portal_id" type="string">
      Link this pack to a specific portal. Either `agent_id` or `portal_id` should be provided.
    </ParamField>

    <ParamField body="description" type="string">
      Pack description.
    </ParamField>

    <ParamField body="channels" type="object">
      Distribution channel flags. For example `{ "web_widget": true, "phone": false }`.
    </ParamField>

    <ParamField body="branding_overrides" type="object">
      Branding values that override the linked genie or portal branding.
    </ParamField>

    <ParamField body="asset_config" type="object">
      Configuration for marketing asset generation.
    </ParamField>

    <ParamField body="touchpoints" type="object">
      Distribution touchpoint configuration.
    </ParamField>

    <ParamField body="baseUrl" type="string">
      Base URL used when generating promotional copy. Defaults to `"https://helpgenie.ai"`. Not persisted to the pack.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only. Create on behalf of another user.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user ID when using `adminMode`.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="activationPack" type="object">
  The newly created pack. See the `get` action for the full object shape.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "create",
    data: {
      name: "Summer Launch",
      agent_id: "genie-uuid",
      description: "Launch pack for our summer campaign",
      channels: {
        web_widget: true,
        phone: true,
        sms: false,
      },
      baseUrl: "https://mycompany.com",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "create",
      "data": {
        "name": "Summer Launch",
        "agent_id": "genie-uuid",
        "channels": { "web_widget": true, "phone": true },
        "baseUrl": "https://mycompany.com"
      }
    }'
  ```
</CodeGroup>

<Note>
  Creating a pack triggers background generation of promotional copy for all five templates at their default tones. By the time you navigate to the pack detail, copy is usually ready.
</Note>

***

## Update activation pack

Updates fields on an existing activation pack. Only provided fields are written; omitted fields remain unchanged.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `update`
</ParamField>

<ParamField body="id" type="string" required>
  The activation pack UUID.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string">Updated pack name.</ParamField>
    <ParamField body="description" type="string">Updated description.</ParamField>
    <ParamField body="agent_id" type="string">Link to a different genie.</ParamField>
    <ParamField body="portal_id" type="string">Link to a different portal.</ParamField>
    <ParamField body="channels" type="object">Updated channel flags.</ParamField>
    <ParamField body="branding_overrides" type="object">Updated branding overrides.</ParamField>
    <ParamField body="asset_config" type="object">Updated asset configuration.</ParamField>
    <ParamField body="touchpoints" type="object">Updated touchpoints.</ParamField>
    <ParamField body="promo_content" type="object">Updated promo content map.</ParamField>
    <ParamField body="adminMode" type="boolean">Admin only.</ParamField>
    <ParamField body="userId" type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="activationPack" type="object">
  The updated pack object.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "update",
    id: "pack-uuid",
    data: {
      name: "Summer Launch v2",
      channels: { web_widget: true, phone: true, sms: true },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update",
      "id": "pack-uuid",
      "data": {
        "name": "Summer Launch v2",
        "channels": { "web_widget": true, "phone": true, "sms": true }
      }
    }'
  ```
</CodeGroup>

***

## Delete activation pack

Permanently deletes an activation pack.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `delete`
</ParamField>

<ParamField body="id" type="string" required>
  The activation pack UUID.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">Admin only.</ParamField>
    <ParamField body="userId" type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` when the pack was deleted.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "delete",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "delete",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

<Warning>
  This action is permanent and cannot be undone.
</Warning>

***

## Generate assets

Triggers the asset generation workflow for an activation pack (QR codes, banners, and other visual materials). The actual generation is performed client-side by the asset generation workflow after this endpoint confirms the pack exists.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `generate-assets`
</ParamField>

<ParamField body="id" type="string" required>
  The activation pack UUID.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">Admin only.</ParamField>
    <ParamField body="userId" type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  `true` when the pack was found and the asset generation signal was sent.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="activationPackId" type="string">
  The pack ID that should receive the generated assets.
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "generate-assets",
    id: "pack-uuid",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-assets",
      "id": "pack-uuid"
    }'
  ```
</CodeGroup>

***

## Generate promotional copy

Generates a single piece of promotional copy for an activation pack and persists it to the pack's `promo_content` field. Use this to regenerate a specific template/tone combination on demand.

<ParamField body="resource" type="string" required>
  `activation-packs`
</ParamField>

<ParamField body="action" type="string" required>
  `generate-promo`
</ParamField>

<ParamField body="id" type="string" required>
  The activation pack UUID.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="template" type="string" required>
      The promotional template to generate. One of:

      * `launch_email` — 90–140 word customer-facing launch email body
      * `social_post` — LinkedIn-ready post (70–110 words)
      * `customer_sms` — SMS message (160 characters or fewer)
      * `team_announcement` — Internal staff announcement (100–160 words)
      * `website_banner` — Two-line homepage banner headline + supporting copy
    </ParamField>

    <ParamField body="tone" type="string">
      Copy tone. One of `professional`, `friendly`, `punchy`. Default varies by template (`friendly` for most, `professional` for team announcements, `punchy` for banners).
    </ParamField>

    <ParamField body="targetUrl" type="string">
      URL included in the generated copy for readers to act on. Defaults to `"https://helpgenie.ai"`.
    </ParamField>

    <ParamField body="adminMode" type="boolean">Admin only.</ParamField>
    <ParamField body="userId" type="string">Admin only. Target user ID.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="template" type="string">
  The template that was generated.
</ResponseField>

<ResponseField name="tone" type="string">
  The tone that was used.
</ResponseField>

<ResponseField name="content" type="object">
  The generated copy.

  <Expandable title="properties">
    <ResponseField name="body" type="string">
      The main copy body.
    </ResponseField>

    <ResponseField name="subject" type="string">
      Email subject line. Present only for `launch_email` and `team_announcement` templates.
    </ResponseField>

    <ResponseField name="generated_at" type="string">
      ISO 8601 timestamp of when the copy was generated.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Request theme={null}
  const response = await ApiService.invoke({
    resource: "activation-packs",
    action: "generate-promo",
    id: "pack-uuid",
    data: {
      template: "launch_email",
      tone: "friendly",
      targetUrl: "https://mycompany.com/chat",
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/activation-packs \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "generate-promo",
      "id": "pack-uuid",
      "data": {
        "template": "launch_email",
        "tone": "friendly",
        "targetUrl": "https://mycompany.com/chat"
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "template": "launch_email",
      "tone": "friendly",
      "content": {
        "subject": "Say hello to our new smart assistant",
        "body": "We have some exciting news to share. We have just launched a new assistant that is available 24/7 to answer your questions about our products and services...",
        "generated_at": "2024-06-26T10:00:00.000Z"
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Generated copy is automatically persisted to the pack's `promo_content` field under `promo_content[template][tone]`. Subsequent requests for the same template/tone overwrite the stored copy.
</Note>

***

## Error responses

| Status | Code               | Description                                      |
| ------ | ------------------ | ------------------------------------------------ |
| 400    | `VALIDATION_ERROR` | Missing required fields (e.g. pack ID, template) |
| 403    | `FORBIDDEN`        | Non-admin user attempted to target another user  |
| 404    | `NOT_FOUND`        | Activation pack not found                        |
| 500    | `INTERNAL_ERROR`   | Server error, including copy generation failure  |