Meetings

A meeting is a confirmed, scheduled face-to-face interaction between a human representative and a lead. Meetings are the core unit of value in HumanConnection — they represent the moment where a data point becomes a relationship.

Overview

After your AI agent finds an event and a human representative, the next step is sending a calendar invite to both participants with send_meeting_invite — the invite is the booking. Meetings take place at events or places. After the meeting, a report is submitted and the human is rewarded.

The Meeting type

1
interface Meeting {
2
  id: string;              // Unique identifier, prefixed with "mtg_"
3
  event_id: string;        // The event where the meeting takes place
4
  human_id: string;        // The human taking the meeting
5
  human_name: string;      // Name of the human representative
6
  guest: Person;           // The person being met
7
  location: {
8
    name: string;          // Venue or meeting place name
9
    address: string;       // Street address
10
    lat?: number;          // Latitude
11
    lng?: number;          // Longitude
12
  };
13
  scheduled_at: string;    // ISO 8601 datetime
14
  duration_minutes: number; // Duration in minutes
15
  status: "scheduled" | "completed" | "cancelled" | "no_show";
16
  notes?: string;          // Pre-meeting notes for the human
17
  created_at: string;      // ISO 8601 timestamp
18
  updated_at: string;      // ISO 8601 timestamp
19
}

Tools

send_meeting_invite

Send a Google Calendar invite to all meeting participants via email. Uses gcalcli under the hood.

Status lifecycle

scheduled --> completed --> (report submitted) --> (reward issued)
    |
    +--> cancelled
    |
    +--> no_show

• scheduled: Meeting is confirmed and upcoming.
• completed: The meeting happened.
• cancelled: The meeting was cancelled before it took place.
• no_show: The lead or human did not show up.

Example usage

1
import { send_meeting_invite } from '@humanconnection/toolkit';
2
3
// Send calendar invite to both participants — the invite is the booking
4
await send_meeting_invite({
5
  title: "Coffee with Sarah Chen — SaaStr Annual",
6
  attendee_emails: ["sarah@acme.com", "elena@humanconnection.sh"],
7
  scheduled_at: "2026-05-12T14:00:00Z",
8
  duration_minutes: 30,
9
  location: "San Mateo Event Center, 1346 Saratoga Dr, San Mateo, CA",
10
  description: "Quick intro at SaaStr. Topics: CI/CD pain points, 60% faster deploys, free pilot."
11
});

After the meeting: report and reward

Once a meeting is completed, two more tools close the loop:

send_meeting_report

Submits the post-meeting report with transcript, outcome, and next steps.

send_meeting_payment

Pays the human based on the meeting outcome.

Reward types

How meetings relate to other resources

• Events: Meetings are linked to an event via event_id. Event-based meetings have the highest show rates.
• Places: When no event is available, places provide the venue via the location field.
• Humans: The human representative is found via search_humans.
• Interests: Use search_interests to find personal signals that help pick the right event or venue.

Best practices

• Provide notes. Give the human context about where and how to find the lead. “Sarah will be at the SaaStr booth area from 1-3 PM” is far more useful than no notes.
• Send the invite immediately. Use send_meeting_invite as soon as the meeting is confirmed so both parties get the calendar event. No invite = forgotten meeting.
• Keep meetings short. 15-30 minute meetings have the highest completion rates. A 20-minute coffee is easier to say yes to than a 90-minute lunch.
• Think about the relationship, not just the deal. The best meetings aren’t just about closing — they’re about starting a relationship that compounds into renewals, referrals, and lifetime value.