Change the Identity or Template of a bound Channel pairing record.
Channel pairing is currently in Beta. API definitions, response structures, and behavior may change. Check the documentation for updates.
POST /api/v1/forward/channel_pairings/{pairing_id}
Change the Identity or Template of a bound (active) record. For pending records, use Pair a channel.
Request parameters
Use Authorization: Bearer <PAT or SAT> and Content-Type: application/json. The required path parameter pairing_id is the pairing record's id.
| Body parameter | Type | Description |
|---|---|---|
identity_id | string | New Identity ID. |
template_id | string | New Template ID. |
null, non-string values, control characters, and unknown fields are not supported. The Channel and pairing scope cannot be changed. scope_display_name comes from channel messages and cannot be edited manually.
Example request
Response
Returns HTTP 200 OK on success with the updated pairing object, using the same structure as Get a channel pairing. The status remains active.
After the binding changes, new messages use the new execution configuration and existing sessions are no longer reused. Submitting the same values again does not change the binding again.
HTTP error codes
| HTTP | Type | Trigger |
|---|---|---|
| 400 | invalid_request_error | Request parameters violate the constraints above, pairing_id is blank or contains control characters, or the Channel is not in pairing mode. |
| 401 | authentication_error | PAT or SAT is invalid or expired. |
| 403 | permission_error | The caller does not have permission to invoke the API. |
| 404 | not_found_error | The active pairing binding, Channel, Identity, or Template does not exist or is inaccessible, or the Channel is archived. |
| 409 | conflict_error | The pairing status conflicts, the binding was modified concurrently, or the target Identity is disabled. |