---
title: "Update Handoff Connection"
method: PUT
path: "/core/handoff/connections/{connection_id}"
tags: ["Human Handoff"]
---

# Update Handoff Connection

`PUT /core/handoff/connections/{connection_id}`

## Request

- Base URL: `https://api.anyreach.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.anyreach.ai/core/handoff/connections/{connection_id}`
- Auth: HTTP bearer

Update a handoff connection; unsupplied fields keep their current value.

## Path parameters

- `connection_id` string, required

## Headers

- `x-anyreach-org` string, nullable: Organization ID for user PATs (pat_ prefix tokens)

## Request body

- HandoffConnectionUpdateRequest: Body for ``PUT /handoff/connections/{id}``. Every field is optional and only the ones actually supplied are written, so a rename never has to re-send the credentials. Credentials can be rotated through this route but not cleared — an empty ``auth_details`` is rejected by the schema.
  - `name` string, nullable
  - `auth_details` HandoffAuthDetails: Credentials for one handoff connection (``handoff_connections.auth_details``). Deliberately stored on the connection row rather than in the agent config: agent configs are versioned and snapshotted onto every conversation, so a token in there would be copied into thousands of rows (PRD §6).
    - `base_url` string, required
    - `username` string, required
    - `api_token` string, required
  - `webhook_secret` string, nullable
  - `settings` HandoffConnectionSettings: How this helpdesk behaves — as opposed to how to reach it. These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting. Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule.
    - `no_reply_after_seconds` integer: Post the rule's waiting message when no human has replied for this long.
    - `idle_close_after_minutes` integer: Close an idle handoff — and finalize the conversation — after this long with no activity.
    - `context_mode` 'summary' | 'transcript' | 'both': What the human agent is handed when the handoff opens.
    - `idle_archive_after_minutes` integer: Push every chat and email conversation on an agent that escalates through this helpdesk into it as a CLOSED conversation, once the customer has sent nothing for this long. Only what was not already pushed is sent, under the same customer identity, so a thread that picks up again lands in the same place. 0 turns it off.
    - `topics_workflow_id` string, nullable: Workflow that chooses the helpdesk topics for a conversation. Run once per record the helpdesk receives — when an escalation opens and each time the idle archive files a segment — with the conversation, the segment and the helpdesk's topic catalog as input; its `topicIds` output is added to the helpdesk conversation. Always runs the workflow's live version (else its newest published one), so publishing is deploying. Blank means no topics are set from here.
  - `enabled` boolean, nullable

## Response `200`

Successful Response

- HandoffConnectionResponse: A handoff connection as any caller is allowed to see it. Explicitly modelled rather than returning the entity, so no future field added to ``HandoffConnection`` can leak a credential by default. ``auth_details`` here is the ``{base_url, username}`` pair only.
  - `id` string, required
  - `organization_id` string, required
  - `provider` string, required
  - `name` string, required
  - `auth_details` object
  - `has_webhook_secret` boolean
  - `settings` HandoffConnectionSettings: How this helpdesk behaves — as opposed to how to reach it. These sit on the connection rather than on an escalation rule because they describe the HELPDESK, not the route: how fast that team answers and what context it wants to receive. Change one here and every agent routing through this connection follows, which is the point — an SLA is not a per-agent setting. Customer-facing copy deliberately does NOT live here. It is spoken in the agent's voice and language, and one connection is shared by every agent in the org, so a shared waiting message would put the wrong language in front of somebody. That stays on the rule.
    - `no_reply_after_seconds` integer: Post the rule's waiting message when no human has replied for this long.
    - `idle_close_after_minutes` integer: Close an idle handoff — and finalize the conversation — after this long with no activity.
    - `context_mode` 'summary' | 'transcript' | 'both': What the human agent is handed when the handoff opens.
    - `idle_archive_after_minutes` integer: Push every chat and email conversation on an agent that escalates through this helpdesk into it as a CLOSED conversation, once the customer has sent nothing for this long. Only what was not already pushed is sent, under the same customer identity, so a thread that picks up again lands in the same place. 0 turns it off.
    - `topics_workflow_id` string, nullable: Workflow that chooses the helpdesk topics for a conversation. Run once per record the helpdesk receives — when an escalation opens and each time the idle archive files a segment — with the conversation, the segment and the helpdesk's topic catalog as input; its `topicIds` output is added to the helpdesk conversation. Always runs the workflow's live version (else its newest published one), so publishing is deploying. Blank means no topics are set from here.
  - `enabled` boolean
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable
  - `created_by` string, nullable
  - `modified_by` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/anyreach/apis/anyreach-api.md) - [All operations](https://skmtc.dev/anyreach/apis/anyreach-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anyreach/apis/anyreach-api/revisions/2eddf40c8c93?raw)