id: lead.submit
version: 2
kind: action
sideEffect: write
title:
  de: Anfrage senden
  en: Submit a lead
description:
  de: "Reicht eine Kontaktanfrage (Name, E-Mail, Nachricht) beim Gewerbe ein. Die Anfrage wird asynchron zugestellt — die Bestätigung signalisiert Annahme, nicht Zustellung."
  en: "Submit a contact request (name, email, message) to the business. The request is delivered asynchronously — the confirmation signals acceptance, not delivery."
input:
  type: object
  required: [name, email, message]
  additionalProperties: false
  properties:
    name:
      type: string
      minLength: 1
      maxLength: 200
    email:
      type: string
      format: email
      maxLength: 254
    message:
      type: string
      minLength: 1
      maxLength: 5000
output:
  type: object
  required: [receiptId, status, duplicate, submittedAt]
  additionalProperties: false
  properties:
    receiptId:
      type: string
      format: uuid
    status:
      type: string
      minLength: 1
      maxLength: 16
    duplicate:
      type: boolean
    submittedAt:
      type: string
      minLength: 20
      maxLength: 32
integration:
  eventKind: lead
  source: agent
requires:
  entitlements: [agent.actions]
  sections: [send-message]
humanEquivalent:
  sectionType: send-message
limits:
  perMinutePerIp: 3
  maxPayloadBytes: 10240
agentGuidance:
  sideEffect: write
  whenToUse: "a visitor wants to contact the business — a question, a request, or a booking inquiry that needs a human reply."
  whenNotToUse: the visitor only needs information already published on the site — answer from the knowledge files or search instead of creating a lead.
  retrySemantics: safe to retry with the same Idempotency-Key — a repeated submission returns the original receipt instead of creating a duplicate lead.