Skip to main content

HumanClarificationRead

A human-in-the-loop clarification: when the bot is unsure mid-dialogue, it can ask a human operator a question and wait for the answer before replying to the lead. This record tracks the question, the operator's response, and how the answer was sourced.

idIdrequired

Unique numeric identifier of the record.

clarification_idClarification Idrequired

External/string identifier of the clarification request.

dialogue_idDialogue Idrequired

ID of the dialogue (conversation) this record relates to.

agent_idAgent Idrequired

ID of the agent (a configured AI assistant / bot persona) this record belongs to.

product_idProduct Idrequired

ID of the product (workspace) that owns this record. Most endpoints scope access by product.

statusStatusrequired

Lifecycle status of the clarification.

user_message objectrequired

The lead message that triggered the clarification.

anyOf
string
user_message_id objectrequired

ID of that lead message.

anyOf
integer
question_textQuestion Textrequired

The question posed to the human operator.

dialogue_history objectrequired

Snapshot of dialogue history provided as context.

anyOf
string
lead_field_snapshot object[]required

Ordered snapshot of selected lead fields captured when the clarification was opened.

  • Array [
    • nameNamerequired

    Lead CRM field key shown to the manager.

    value objectrequired

    Raw value captured from lead.crm_fields when the clarification was created.

    anyOf
    string
  • ]
    • manager_response objectrequired

    The operator's answer.

    anyOf
    string
    answer_sourceHumanClarificationAnswerSourcerequired

    Where the answer came from — a manager, or recalled from a previous clarification.

    Possible values: [manager, hitl_recall]

    answer_source_clarification_idsstring[]required

    IDs of prior clarifications a recalled answer was drawn from.

    answer_source_reason objectrequired

    Why this answer source was chosen.

    anyOf
    string
    response_message_id objectrequired

    ID of the bot message that delivered the answer to the lead.

    anyOf
    integer
    response_text objectrequired

    The text ultimately sent to the lead.

    anyOf
    string
    reformulated_question objectrequired

    A reformulated version of the question, if produced.

    anyOf
    string
    rag_entry objectrequired

    Knowledge-base entry produced from this clarification, if any.

    anyOf
    string
    rag_statusRag Statusrequired

    Status of turning this clarification into a knowledge entry.

    rag_error objectrequired

    Error detail for the knowledge-entry step, if any.

    anyOf
    string
    error objectrequired

    General error detail, if any.

    anyOf
    string
    created_atdate-timerequired

    Creation time (UTC, ISO 8601).

    completed_at objectrequired

    When the clarification was completed (UTC).

    anyOf
    date-time
    HumanClarificationRead
    {
      "id": 0,
      "clarification_id": "string",
      "dialogue_id": 0,
      "agent_id": 0,
      "product_id": 0,
      "status": "string",
      "user_message": "string",
      "user_message_id": 0,
      "question_text": "string",
      "dialogue_history": "string",
      "lead_field_snapshot": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "manager_response": "string",
      "answer_source": "manager",
      "answer_source_clarification_ids": [
        "string"
      ],
      "answer_source_reason": "string",
      "response_message_id": 0,
      "response_text": "string",
      "reformulated_question": "string",
      "rag_entry": "string",
      "rag_status": "string",
      "rag_error": "string",
      "error": "string",
      "created_at": "2024-07-29T15:51:28.071Z",
      "completed_at": "2024-07-29T15:51:28.071Z"
    }