Picker

When to Use

• AI entity disambiguation ("Which customer did you mean?")
• Workflow routing ("Which team should handle this ticket?")
• Category assignment by a human reviewer
• Multi-select tagging of records
• Selecting recipients for a follow-up notification

Live Mockup — Single Selection

Selection Modes

Request Payload Schema

interface PickerPayload {
  /** Instruction shown above the option list */
  title: string;

  /** Optional context / explanation */
  description?: string;

  /** The list of options to display */
  options: PickerOption[];

  /** 'single' | 'multiple' (default: 'single') */
  selectionMode?: 'single' | 'multiple';

  /** Minimum selections required (multiple mode only; default: 1) */
  minSelections?: number;

  /** Maximum selections allowed (multiple mode only; default: options.length) */
  maxSelections?: number;
}

interface PickerOption {
  id:           string;   // returned in selectedIds on response
  label:        string;   // primary display text
  description?: string;   // secondary display text
  metadata?:    Record<string, any>;   // arbitrary display data (not returned in response)
}

Full Request Example

const response = await sendInteraction({
  type: 'picker',
  targetUserId: 'usr_billing_team',
  title: 'Select the correct customer account',
  payload: {
    title: 'Select the correct customer account',
    description: 'The invoice references "Acme" — which account should this be applied to?',
    selectionMode: 'single',
    options: [
      { id: 'cust_001', label: 'Acme Supplies Ltd',     description: 'Dublin, IE' },
      { id: 'cust_008', label: 'Acme Technologies Inc', description: 'New York, US' },
      { id: 'cust_017', label: 'Acme Global Ltd',       description: 'London, UK' }
    ]
  },
  timeoutMs: 3_600_000,   // 1 hour
  priority: 'high'
});

if (response.outcome === 'selected') {
  const [customerId] = response.data.selectedIds;
  await invoiceService.assignToCustomer(invoiceId, customerId);
}

Multiple Selection Example

const response = await sendInteraction({
  type: 'picker',
  targetUserId: 'usr_hr_manager',
  title: 'Assign this issue to support teams',
  payload: {
    title: 'Which teams should be notified about this security incident?',
    selectionMode: 'multiple',
    minSelections: 1,
    maxSelections: 3,
    options: [
      { id: 'team_security', label: 'Security',      description: 'Primary incident team' },
      { id: 'team_legal',    label: 'Legal',         description: 'For regulatory exposure' },
      { id: 'team_comms',    label: 'Communications',description: 'Customer communications' },
      { id: 'team_it',       label: 'IT Operations', description: 'Infrastructure team' }
    ]
  },
  timeoutMs: 1_800_000
});

const teamsToNotify = response.data.selectedIds;   // e.g. ['team_security', 'team_legal']
await notifyTeams(teamsToNotify, incidentId);

Response Schema

interface PickerResponse {
  interactionId: string;
  respondedBy:   string;
  outcome:       'selected';
  data: {
    /** IDs of selected options (always an array, even for single selection) */
    selectedIds: string[];
  };
  timestamp: string;
}

Validation Rules