The AIRecommendedAction Object

Represents a recommended action based on AI analysis. It provides contextual insights and justifications for decision-making, along with confidence scoring. The structure of payload depends on the action type — see Possible payloads below.

Properties

Name	Description	Type	Required
uid	A unique identifier for the recommended action.	string	Yes
action	The type of action recommended. Possible values: `reply` (suggests responding to a user message), `estimate` (suggests providing a price estimate), `schedule` (suggests scheduling an appointment or meeting), `acknowledge` (no action or artifact is prepared; the user reviews the item and then completes or dismisses it).	string (enum: `reply`, `estimate`, `schedule`, `acknowledge`)	Yes
display	Contains display-related information for the recommendation.	object
reason	The reason why this action is recommended, providing context for decision-making.	string
payload	Additional data related to the recommended action. The structure depends on the action type.	object
evidence	A list of supporting statements or facts justifying the recommendation.	array[string]
context	The context in which the recommendation was generated.	object
confidence	A confidence score (0-1) indicating how confident the AI is in this recommendation.	number

Display Properties

Name	Description	Type	Required
btn_text	A human-readable title describing the recommendation.	string

Context Properties

Name	Description	Type	Required
context_uid	A unique identifier for the context associated with this recommendation.	string
context_type	The type of context (e.g., `matter`, `client`, `business`).	string (enum: `matter`, `client`, `business`)

Example

{
  "uid": "act-456",
  "action": "reply",
  "display": {
    "btn_text": "Generate Reply"
  },
  "reason": "User needs clarification on pricing",
  "evidence": [
    "User asked for price estimate"
  ],
  "payload": {
    "message": "Hi please send some more details"
  },
  "context": {
    "context_uid": "ctx-456",
    "context_type": "client"
  }
}

Possible payloads

The payload object is not a fixed schema — its shape is determined by the action type. The examples below illustrate the payloads produced for each action type.

Reply

Payload example

{
  "uid": "act-456",
  "action": "reply",
  "display": {
    "btn_text": "Generate Reply"
  },
  "reason": "User needs clarification on pricing",
  "payload": {
    "email_message": "I need more details to send you a quote<br/>best regards,<br/>ramster",
    "sms_message": "I need more details to send you a quote",
    "FB_message": "I need more details to send you a quote",
    "other_message": "I need more details to send you a quote"
  },
  "evidence": [
    "User asked for price estimate"
  ]
}

Payload Properties

Name	Description	Type	Required
email_message	Text to be used for email	string
sms_message	Text to be used for SMS	string
FB_message	Text to be used for Facebook	string
other_message	Text to be used as fallback for other channels	string

Schedule

Payload example

{
  "uid": "act-456",
  "action": "schedule",
  "display": {
    "btn_text": "Schedule an Appointment"
  },
  "reason": "User asked for an appointment at 6PM",
  "payload": {
    "client_availability": [
      {
        "start_time": "2025-02-05T09:00:00+01:00",
        "end_time": "2025-02-05T17:00:00+01:00"
      }
    ],
    "recommended_start_time": "2025-02-05T12:00:00+01:00",
    "service_name": "Primera Sesión Gratuita",
    "duration": 30,
    "service_uid": "6870531",
    "business_timezone": "Asia/Jerusalem"
  },
  "evidence": [
    "User asked for an appointment"
  ],
  "confidence": 0.85
}

Payload Properties

Name	Description	Type	Required
client_availability	List of intervals indicating the client's availability.	array[object]
client_availability[].start_time	Start time (ISO 8601) for a client availability window.	string
client_availability[].end_time	End time (ISO 8601) for a client availability window.	string
recommended_start_time	Recommended start time for the service (ISO 8601).	string
service_name	Name of the service being recommended.	string
duration	Duration of the service in minutes.	integer
service_uid	Unique identifier for the service.	string
business_timezone	The business's timezone.	string

Note:

ISO 8601 format commonly includes the date, time, and time zone (e.g., YYYY-MM-DDTHH:mm:ss±HH:mm).
The confidence field indicates how confident the system is about the recommendation (1.0 being highest).

Estimate

Payload example

{
  "uid": "act-456",
  "action": "estimate",
  "display": {
    "btn_text": "Generate an estimate"
  },
  "reason": "User asked for an estimate to clean her carpet",
  "evidence": [
    "I want a price estimate for carpet cleaning"
  ],
  "payload": {
    "estimate": {
      "header": "New Estimate for service",
      "purchase_order": "PO123",
      "items": [
        {
          "itemizable_subject_type": "Service",
          "itemizable_subject_uid": "service-123",
          "name": "service with taxes",
          "rate": 22,
          "quantity": 2,
          "taxes": [
            { "name": "VAT", "rate": 10 }
          ]
        },
        {
          "itemizable_subject_type": "Product",
          "itemizable_subject_uid": "product-123",
          "name": "product",
          "rate": 10,
          "quantity": 2,
          "taxes": [
            { "name": "VAT", "rate": 10 }
          ]
        },
        {
          "name": "Custom Item",
          "description": "Custom Item Description",
          "rate": 100,
          "quantity": 2
        }
      ],
      "notes": "This is a note for the estimate",
      "metadata": {
        "display_sections_total": true,
        "display_items_total": false
      }
    }
  }
}