close_conversation

close_conversation(
    context: dict,
    reason: str | None = None,
    conversation_id: str | None = None,
) -> dict

Closes an existing conversation through Octocom's normal close pipeline. This records the close, notifies the conversation channel, and runs the same downstream close events and analytics as a normal close.

Closing also prevents future auto-resolution follow-ups and scheduled bot messages from being sent. A repeated call for an already-closed conversation is a successful no-op.

This helper is available in recurring jobs, event handlers, and sidebar actions. It is intentionally unavailable while a condition provider, system-prompt section, sidebar widget, or bot action is still executing.

A recurring job test executes this helper normally and closes the real conversation. Keep a dry_run guard enabled while testing mutating jobs.

Parameters

Returns

{
    "success": True,
    "conversationId": "conversation-uuid",
    "closed": True,
    "alreadyClosed": False,
}

alreadyClosed is True when the conversation was closed before the call. In that case Octocom does not publish duplicate close events.

Close only after customer-visible work succeeds

When an automation performs an external operation, sends a confirmation, and closes the conversation, preserve this order:

1. Perform and verify every required external operation.
2. Call send_bot_message and confirm it succeeds.
3. Call close_conversation.

def run_job(context):
    conversation_id = "RGkco8fmT"

    refund = refund_and_verify_order("order-123")
    if not refund["verified"]:
        return {"closed": False, "reason": "Refund was not verified"}

    send_bot_message(
        context,
        "Your order has been cancelled and your full refund has been issued.",
        idempotency_key="order-cancelled:order-123:confirmation:v1",
        conversation_id=conversation_id,
    )

    return close_conversation(
        context,
        reason="Order order-123 cancelled, refunded, and customer notified",
        conversation_id=conversation_id,
    )

If confirmation delivery fails, do not close the conversation. Leaving it open makes the failure visible for retry or manual follow-up.