add_conversation

add_conversation_event(context: dict, event: str, subtext: str = None, details: str = None) -> dict

Records a timestamped event in the conversation's timeline. Events appear in the conversation detail view in the dashboard, making them useful for auditing what happened during a conversation.

Parameters

Name	Type	Description
`context`	`dict`	The context object passed to your action
`event`	`str`	The event text to record (max 1000 characters)
`subtext`	`str`	Optional secondary text (max 1000 characters)
`details`	`str`	Optional plain-text hover details (max 12000 characters)

Returns

dict — {"success": bool, "message": str, "eventId": str}

Behavior

Skipped in test/mock environments.
Initiator information is assigned by the server from the authenticated execution.
New records use event: "event" with metadata.version: 1; historical records retain their original formats. See ticket activity events.

Examples

Log when a refund is processed

def execute_action(context):
    order_id = context["args"]["orderId"]
    amount = process_refund(order_id)

    add_conversation_event(context, f"Refund of ${amount} processed for order {order_id}")
    return {"success": True, "amount": amount}

Record a decision point

def execute_action(context):
    order = fetch_order(context["args"]["orderId"])

    if order["daysOld"] > 30:
        add_conversation_event(context, "Order outside 30-day return window — denied")
        return {"eligible": False, "reason": "Outside return window"}

    add_conversation_event(context, "Order eligible for return")
    return {"eligible": True}