Submitting Tickets from Third-Party Apps

The Problem

When a third-party app (like a form builder, CRM, or bug reporting tool) sends a notification email on behalf of a user, the email comes from the app’s noreply@ address — not the actual customer. This means Halo creates the contact as [email protected] instead of the real user, and:

The ticket is linked to the wrong contact
The AI agent can’t pull up the customer’s history or context
Replies go to the notification address instead of the customer
You lose all the structured data from the original form submission

This guide covers two approaches to solve this, depending on your integration capabilities.

Approach 1: Tickets API (Recommended)

If you can make HTTP requests from your app or webhook handler, use the Tickets API to create tickets with proper user association. This is the cleanest solution and what tools like Intercom recommend for programmatic integrations.

How it works

Basic example

curl -X POST https://api.haloagents.ai/api/sdk/tickets/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Doe",
    "subject": "Bug: SEO settings missing from Share page",
    "message": "The SEO settings were previously available on the Share page but are now missing.",
    "metadata": {
      "severity": "major",
      "area": "Form Editor"
    },
    "source": "bug_report"
  }'

The ticket is created in your Halo inbox, linked to [email protected], and the AI agent has full context to respond.

Integration examples

Form Builder (Webhook)
Zapier / Make
CRM Webhook
Bug Report Tool

Most form builders (Typeform, Tally, JotForm, OrbitForms) support sending webhooks when a form is submitted. Point the webhook at a handler on your backend that calls the Halo Tickets API:

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 submission = await request.json();

  const response = await fetch(`${HALO_API_URL}/tickets/create`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${HALO_API_KEY}`,
    },
    body: JSON.stringify({
      email: submission.email,
      name: submission.name,
      subject: `${submission.type}: ${submission.title}`,
      message: submission.description,
      metadata: {
        severity: submission.severity,
        area: submission.area,
        form_id: submission.form_id,
      },
      source: "contact_form",
    }),
  });

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

Use Zapier or Make to connect your form builder to Halo without writing code:

Trigger: New form submission (Typeform, Google Forms, etc.)
Action: HTTP POST to https://api.haloagents.ai/api/sdk/tickets/create
Headers: Authorization: Bearer ab_live_... and Content-Type: application/json
Body:

{
  "email": "{{respondent_email}}",
  "name": "{{respondent_name}}",
  "subject": "{{form_title}}: {{summary_field}}",
  "message": "{{description_field}}",
  "source": "zapier"
}

Forward events from your CRM (HubSpot, Salesforce, Pipedrive) to Halo:

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

  if (event.type === "deal.lost" || event.type === "ticket.created") {
    const contact = event.data.contact;

    await fetch(`${HALO_API_URL}/tickets/create`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${HALO_API_KEY}`,
      },
      body: JSON.stringify({
        user_id: contact.id,
        email: contact.email,
        name: contact.name,
        subject: event.data.subject || event.data.title,
        message: event.data.description,
        metadata: {
          crm_id: event.data.id,
          deal_value: event.data.amount,
          reason: event.data.close_reason,
        },
        source: "hubspot",
        priority: event.data.priority === "high" ? "priority" : "normal",
      }),
    });
  }

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

Integrate bug reporting tools (Sentry, Linear, custom forms):

import requests

def create_halo_ticket(bug_report):
    response = requests.post(
        "https://api.haloagents.ai/api/sdk/tickets/create",
        headers={
            "Content-Type": "application/json",
            "Authorization": "Bearer ab_live_xxxxxxxxxxxxxxxx",
        },
        json={
            "email": bug_report["reporter_email"],
            "name": bug_report["reporter_name"],
            "subject": f"[Bug] {bug_report['title']}",
            "message": bug_report["description"],
            "metadata": {
                "severity": bug_report["severity"],
                "area": bug_report["area"],
                "steps_to_reproduce": bug_report["steps"],
                "browser": bug_report["browser"],
                "os": bug_report["os"],
            },
            "source": "bug_report",
            "priority": "priority" if bug_report["severity"] == "critical" else "normal",
        },
    )
    return response.json()

Enabling AI responses

Set "ai_enabled": true to have Halo’s AI agent automatically respond to tickets created via the API. The AI uses your configured email agent and replies to the user’s email address:

{
  "email": "[email protected]",
  "subject": "How do I export my data?",
  "message": "I need to export all my form responses as a CSV.",
  "ai_enabled": true
}

AI responses require AI email auto-reply to be enabled in Settings > AI Agents. The AI agent uses your trained knowledge base to respond, just like it would for email tickets.

Enriching user data

For richer AI context, call the identify endpoint before creating the ticket. This gives the AI access to the user’s plan, role, company, and custom attributes:

// Step 1: Identify the user with full context
await fetch(`${HALO_API_URL}/users/identify`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${HALO_API_KEY}`,
  },
  body: JSON.stringify({
    user_id: "user_123",
    traits: {
      name: "Jane Doe",
      email: "[email protected]",
      plan: "pro",
      role: "admin",
    },
  }),
});

// Step 2: Create the ticket (user is already identified)
await fetch(`${HALO_API_URL}/tickets/create`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${HALO_API_KEY}`,
  },
  body: JSON.stringify({
    user_id: "user_123",
    subject: "Need help with SSO setup",
    message: "We're trying to configure SAML SSO but getting an error.",
    ai_enabled: true,
  }),
});

Approach 2: Email Best Practices

If your integration must send emails (e.g., you can’t modify the third-party app’s webhook behavior), follow these guidelines to help Halo identify the real sender.

Use the customer’s email as the From address

The most effective approach is configuring your notification system to send emails from the customer’s actual email address, not from a noreply@ address:

From: [email protected]           <-- Halo creates the contact as Jane
To: [email protected]
Subject: Bug Report: SEO settings missing

vs.

From: [email protected]   <-- Halo creates the contact as noreply@
To: [email protected]
Subject: Bug Report: SEO settings missing

Sending emails from a customer’s address you don’t control may cause deliverability issues (SPF/DKIM failures). Only do this if you’re sending from a domain you have DNS control over, or if the email provider supports “send as” with proper authentication.

Use the Reply-To header

If you can’t change the From address, set the Reply-To header to the customer’s email. This ensures that when your team replies from Halo, the response goes to the right person:

From: [email protected]
Reply-To: [email protected]
To: [email protected]
Subject: Bug Report: SEO settings missing

Enable forwarded customer detection

If your notification emails include a From: line in the body (common with email forwarding), Halo can automatically extract the original sender.

Go to Settings > Emails > Email Settings
Enable Detect forwarded customers

This works when the email body contains a line like:

From: Jane Doe <[email protected]>

Halo parses this and creates the contact as [email protected] instead of the envelope sender.

Include structured data in the subject

When sending notification emails, put key information in the subject line so it’s visible in the Halo inbox at a glance:

Subject: [Bug Report] Major - Form Editor - SEO settings missing (reporter: [email protected])

Limitations of email-based integrations

Issue	Impact
Sender is `noreply@`	Contact linked to wrong email, AI can’t identify the customer
No structured metadata	Form fields are buried in email body text
No AI context	AI agent can’t access user’s plan, history, or company info
Reply threading	Replies may not thread correctly if headers are stripped

For these reasons, the Tickets API is strongly recommended over email for third-party integrations.

Comparison

Feature	Tickets API	Email
User identity preserved	Always	Only if From is the customer
Structured metadata	Full JSON support	Plain text only
AI agent context	Full (user, company, history)	Limited
AI auto-reply	Supported (`ai_enabled`)	Supported (if sender is identified)
No code required	No (HTTP request needed)	Yes (email forwarding)
Works with Zapier/Make	Yes	Yes
Email threading	N/A	Native

Next Steps

Tickets API Reference

Full API reference for creating tickets programmatically.

Identify Users

Enrich user records with traits and context before creating tickets.

Receiving Emails

Set up email forwarding from your existing support address.

Automatic Ticket Creation

Create tickets through the AI chat pipeline for triage and auto-response.

​The Problem

​Approach 1: Tickets API (Recommended)

​How it works

​Basic example

​Integration examples

​Enabling AI responses

​Enriching user data

​Approach 2: Email Best Practices

​Use the customer’s email as the From address

​Use the Reply-To header

​Enable forwarded customer detection

​Include structured data in the subject

​Limitations of email-based integrations

​Comparison

​Next Steps

Tickets API Reference

Identify Users

Receiving Emails

Automatic Ticket Creation

The Problem

Approach 1: Tickets API (Recommended)

How it works

Basic example

Integration examples

Enabling AI responses

Enriching user data

Approach 2: Email Best Practices

Use the customer’s email as the From address

Use the Reply-To header

Enable forwarded customer detection

Include structured data in the subject

Limitations of email-based integrations

Comparison

Next Steps