set_conversation

set_conversation_metadata(context: dict, key: str, value: str) -> dict

Stores a metadata key-value pair on the conversation. If the key already exists, the value is updated.

Parameters

Name	Type	Description
`context`	`dict`	The context object passed to your action
`key`	`str`	The metadata key (max 200 characters)
`value`	`str`	The value to store (max 50,000 characters)

Returns

dict — {"success": bool, "message": str, "key": str, "value": str}

Limits

Maximum key length: 200 characters
Maximum value length: 50,000 characters
Maximum 200 key-value pairs per conversation

Behavior

If the key already exists, its value is overwritten.
In test/mock environments, returns a mock success response without persisting.

Special keys

Some metadata keys change platform behavior when set:

Key	Effect
`email:botFooterOverride`	Replaces the email configuration's bot footer for all bot-sent emails in this conversation (all email-based channels, including help desk integrations). Raw HTML is supported, so this can inject styled banners or signatures. Set an empty string to suppress the default footer entirely. Agent-sent emails are unaffected.

Examples

Track a refund amount for analytics

def execute_action(context):
    # ... process refund ...
    set_conversation_metadata(context, "refund_amount", "49.99")
    set_conversation_metadata(context, "refund_reason", "damaged_product")
    return {"success": True, "amount": 49.99}

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

    # Show a promo banner only to eligible customers
    if order["type"] == "one_time" and order["payment_method"] != "klarna":
        banner = '<a href="https://example.com/offer" style="display:block;padding:16px;background:#e9f8ee;border-radius:12px;">Get 70% off your next order</a>'
        set_conversation_metadata(context, "email:botFooterOverride", banner)

    return {"success": True}

Store a computed value for later use

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

    set_conversation_metadata(context, "risk_score", str(risk_score))

    return {"riskScore": risk_score, "order": order}

set_conversation_metadata