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. - 'chat_with_bizai': Hands the item off to BizAI (the business AI chat assistant) to handle on the user's behalf. | string (enum: reply, estimate, schedule, acknowledge, chat_with_bizai) | Yes |
| display | Presentation-only 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 of strings | |
| confidence | A confidence score (0-1) indicating how confident the AI is in this recommendation. | number |
Display Properties
| Name | Description | Type | Required |
|---|---|---|---|
| btn_text | Label for the control that triggers the action (e.g., "Generate Reply"). | string | |
| body_markdown | Markdown describing what the action proposes, for the consumer to render. Optional and available for every action type; absent is valid, and the consumer decides how to present the recommendation without it. Presentation only - execution always reads payload, never this field, so a mismatch between the two is a producer bug. Consumers must sanitise it before rendering it as markup. Not a copy of reason: reason explains why the recommendation surfaced (e.g., "Suggested reply:\n\nHi Elizabeth - Friday 6:00PM works for a 2 hour slot."). | string |
Example
{
"uid": "act-456",
"action": "reply",
"display": {
"btn_text": "Generate Reply",
"body_markdown": "**Suggested reply:**\n\nHi Elizabeth - Friday 6:00PM works for a 2 hour slot."
},
"reason": "User needs clarification on pricing",
"evidence": [
"User asked for price estimate"
],
"payload": {
"message": "Hi please send some more details"
},
"confidence": 0.85
}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
confidencefield indicates how confident the system is about the recommendation (1.0being 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
}
}
}
}