Automatic Ticket Creation

When a user submits an application, fills out a form, or triggers an action in your app, you can automatically create a support ticket in Halo — no manual intervention required. This guide walks through the recommended approaches from simplest to most flexible.

How Ticket Creation Works

Halo creates tickets through the AI chat pipeline. When you send a message to the chat API with the right context, the AI agent evaluates the request and creates a ticket when it detects an issue that needs human follow-up. There are two approaches:

Approach	Best For	How It Works
Chat API with context	Form submissions, applications, support requests	Send the submission as a chat message with structured context. The AI triages, creates a ticket, and responds to the user.
Chat API with forced escalation	Cases where you always want a ticket	Send a message that explicitly requests human help. The AI creates a ticket immediately.

Both approaches use the same Chat API endpoint and benefit from the full AI pipeline — the ticket includes conversation context, user data, and company information automatically.

Prerequisites

A HaloAgents widget key (ab_live_...) — copy yours from Setup > Install in the dashboard
An agent with ticket escalation enabled (configure in AI Agents > [Your Agent] > Actions > Ticket Escalation)
Optionally, an Identity Secret (ha_secret_...) if you use identity verification

The widget key is publishable and safe in your install snippet. For server-side REST calls in this guide, call from your backend and enable identity verification when scoping by user_id.

Approach 1: Chat API with Context

This is the recommended approach. Send the form/application data as structured context alongside a chat message describing the request. The AI agent triages the submission and creates a ticket with full context attached.

Step 1: Identify the User

Before sending the submission, make sure the user exists in Halo. Call the identify endpoint so the ticket is linked to the right person:

curl -X POST https://api.haloagents.ai/api/sdk/users/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "traits": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "role": "admin",
      "plan": "enterprise"
    }
  }'

If the user already exists, their record is updated. If they’re new, they’re created.

Step 2: Send the Submission as a Chat Message

Use the Chat API to send the submission data. Pass the form fields as context entries so the AI (and your team) can see exactly what was submitted:

curl -X POST https://api.haloagents.ai/api/sdk/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "message": "New partnership application submitted by Jane Doe from Acme Corp. Please review and follow up.",
    "context": {
      "application": {
        "label": "Partnership Application",
        "type": "custom",
        "value": {
          "company_name": "Acme Corp",
          "contact_name": "Jane Doe",
          "contact_email": "[email protected]",
          "application_type": "Technology Partner",
          "annual_revenue": "$2M-$10M",
          "use_case": "Integrate our analytics platform with Halo for mutual customers",
          "submitted_at": "2026-03-15T10:30:00Z"
        }
      }
    }
  }'

The AI agent processes the message, sees the application context, and — if escalation is enabled — creates a ticket that includes all the submitted data.

What Happens Next

The AI creates a ticket with the application details in the metadata
Your team sees the ticket in the Halo dashboard with the full submission
If Slack notifications are configured, your team gets notified immediately
The AI responds with a confirmation (returned in the text field)
You can store the session_id to send follow-up messages to the same conversation

Approach 2: Chat API with Forced Escalation

If you want a ticket created every time (no AI triage), phrase the message to explicitly request human follow-up. The AI recognizes escalation intent and creates a ticket immediately:

curl -X POST https://api.haloagents.ai/api/sdk/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "user_id": "user_123",
    "message": "Please create a support ticket: New enterprise onboarding request from Acme Corp. They need help setting up SSO integration and custom reporting. This requires human assistance.",
    "context": {
      "onboarding_request": {
        "label": "Onboarding Request",
        "type": "custom",
        "value": {
          "company": "Acme Corp",
          "plan": "enterprise",
          "requested_services": ["SSO Setup", "Custom Reporting", "API Integration"],
          "preferred_start_date": "2026-04-01",
          "contact": "[email protected]"
        }
      }
    }
  }'

Phrases like “please create a support ticket”, “I need human help”, or “please escalate this” trigger the AI’s escalation logic, which creates a ticket and routes it to your team.

Full Integration Example

Here’s a complete example of handling a form submission in a Next.js API route and automatically creating a ticket in Halo:

import { NextRequest, NextResponse } from "next/server";

const HALO_API_URL = "https://api.haloagents.ai/api/sdk";
const HALO_API_KEY = process.env.HALOAGENTS_API_KEY!;

export async function POST(request: NextRequest) {
  const form = await request.json();

  // Step 1: Identify the user in Halo
  await fetch(`${HALO_API_URL}/users/identify`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${HALO_API_KEY}`,
    },
    body: JSON.stringify({
      user_id: form.user_id,
      traits: {
        name: form.name,
        email: form.email,
        role: form.role,
      },
    }),
  });

  // Step 2 (optional): Identify the company
  if (form.company_id) {
    await fetch(`${HALO_API_URL}/companies/identify`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${HALO_API_KEY}`,
      },
      body: JSON.stringify({
        company_id: form.company_id,
        user_id: form.user_id,
        traits: {
          name: form.company_name,
          plan: form.plan,
        },
      }),
    });
  }

  // Step 3: Send the submission to Halo via the chat API
  const haloResponse = await fetch(`${HALO_API_URL}/chat`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${HALO_API_KEY}`,
    },
    body: JSON.stringify({
      user_id: form.user_id,
      message: `New ${form.request_type} request submitted by ${form.name}. Please review and create a ticket for follow-up.`,
      context: {
        submission: {
          label: `${form.request_type} Submission`,
          type: "custom",
          value: form.fields,
        },
      },
    }),
  });

  const data = await haloResponse.json();

  return NextResponse.json({
    success: true,
    session_id: data.session_id,
    message: "Your request has been submitted and a support ticket has been created.",
  });
}

Using Webhooks from Other Systems

If you receive webhooks from external systems (Stripe, HubSpot, your own app, etc.), you can forward them to Halo the same way:

export async function POST(request: NextRequest) {
  const event = await request.json();

  if (event.type === "subscription.cancelled") {
    const customer = event.data.customer;

    await fetch(`${HALO_API_URL}/chat`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${HALO_API_KEY}`,
      },
      body: JSON.stringify({
        user_id: customer.id,
        message: `Customer ${customer.name} has cancelled their subscription. Please create a ticket for the retention team to follow up.`,
        context: {
          cancellation: {
            label: "Cancellation Details",
            type: "custom",
            value: {
              customer_name: customer.name,
              plan: customer.plan,
              reason: event.data.reason,
              mrr_lost: event.data.mrr,
              cancelled_at: event.data.cancelled_at,
            },
          },
        },
      }),
    });
  }

  return NextResponse.json({ received: true });
}

Configuring Ticket Behavior

Escalation Settings

The AI’s ticket creation behavior is controlled by your agent’s escalation settings. Configure these in the dashboard under AI Agents > [Your Agent] > Actions > Ticket Escalation:

Setting	Effect
Mode	`always` creates tickets on every escalation signal. `conditional` adds gates (must search knowledge base first).
Default Assignee	Automatically assign new tickets to a specific team member.
Priority Filters	Segment rules that mark matching users’ tickets as “priority” (e.g., enterprise plan customers).
Escalation Filters	Only create tickets for users matching specific segments.

Ticket Consolidation

If a user already has an open ticket, new escalations are merged into the existing ticket instead of creating duplicates. This keeps your inbox clean when the same user submits multiple requests.

Notifications

When a ticket is created, Halo can notify your team via:

Slack — instant notifications in your configured channel
Email — notification emails to assigned team members
Dashboard — real-time updates in the Halo inbox

Context Types for Submissions

Use context entries to structure submission data so it’s readable by both the AI and your team. Here are common patterns:

Application / Form Submission

{
  "application": {
    "label": "Partner Application",
    "type": "custom",
    "value": {
      "applicant_name": "Jane Doe",
      "company": "Acme Corp",
      "type": "Technology Partner",
      "details": "Integration with analytics platform"
    }
  }
}

Support Request

{
  "support_request": {
    "label": "Support Request",
    "type": "error",
    "value": [
      { "area": "billing", "message": "Invoice #1234 charged incorrectly" }
    ]
  }
}

Feature Request

{
  "feature_request": {
    "label": "Feature Request",
    "type": "custom",
    "value": {
      "title": "Custom dashboard widgets",
      "description": "Ability to create custom widgets on the main dashboard",
      "priority": "high",
      "requested_by": "[email protected]"
    }
  }
}

Order / Transaction

{
  "order": {
    "label": "Order Details",
    "type": "list",
    "value": [
      { "name": "Pro Plan Annual", "quantity": 1, "amount": "$599" },
      { "name": "API Add-on", "quantity": 1, "amount": "$99" }
    ]
  }
}

Checking Ticket Status

After a ticket is created, you can view it in the Halo dashboard. The ticket includes:

The original submission message
All structured context data from the request
User and company information
The AI’s triage notes and conversation history
Priority status (based on your escalation filters)

Tickets created through the chat API appear in your Halo inbox just like any other ticket. Your team can respond, reassign, snooze, or resolve them using the standard workflow.

Next Steps

Chat API Reference

Full reference for the chat endpoint used to create tickets.

Context Entries

Learn about all context types for structuring submission data.

Identify Users

API reference for creating and updating user records.

Identify Companies

API reference for creating and updating company records.

​How Ticket Creation Works

​Prerequisites

​Approach 1: Chat API with Context

​Step 1: Identify the User

​Step 2: Send the Submission as a Chat Message

​What Happens Next

​Approach 2: Chat API with Forced Escalation

​Full Integration Example

​Using Webhooks from Other Systems

​Configuring Ticket Behavior

​Escalation Settings

​Ticket Consolidation

​Notifications

​Context Types for Submissions

​Application / Form Submission

​Support Request

​Feature Request

​Order / Transaction

​Checking Ticket Status

​Next Steps

Chat API Reference

Context Entries

Identify Users

Identify Companies

How Ticket Creation Works

Prerequisites

Approach 1: Chat API with Context

Step 1: Identify the User

Step 2: Send the Submission as a Chat Message

What Happens Next

Approach 2: Chat API with Forced Escalation

Full Integration Example

Using Webhooks from Other Systems

Configuring Ticket Behavior

Escalation Settings

Ticket Consolidation

Notifications

Context Types for Submissions

Application / Form Submission

Support Request

Feature Request

Order / Transaction

Checking Ticket Status

Next Steps