---
title: "Pass or release thread control"
method: POST
path: "/partner/app/{appId}/thread/control"
tags: ["Operate — Thread Control"]
---

# Pass or release thread control

`POST /partner/app/{appId}/thread/control`

## Request

- Base URL: `https://partner.gupshup.io`
- URL: `https://partner.gupshup.io/partner/app/{appId}/thread/control`
- Auth: API key in header `Authorization`

A dedicated Partner Portal route, **not** part of the `/bizai/**` catch-all. The Postman
collection's `/bizai/thread_control` is only a sub-path the catch-all would forward; use this one.

Partner Portal forwards the body unchanged to WASS, which fills `phone_number_id` from the app and
calls Meta `POST /{phone_number_id}/thread_control`. Passing control changes who answers a **live**
conversation. `release` hands it back and, per Meta, emits no handover webhook.

Meta errors on this route are Graph-style (`(#100) ...`, code `2494191` when take is not permitted),
not the `{title, detail}` envelope used on `/bizai/**`.

Rate limit: 500 requests per 60 seconds per app, separate from `/bizai/**`. Only `application/json`
is accepted (415 otherwise).

## Request body

- ThreadControlRequest
  - `messaging_product` 'whatsapp', required
  - `to` string, required: Consumer phone number.
  - `action` 'pass' | 'release' | 'take', required
  - `metadata` string: Optional context passed to the new owner.
  - `control_pass` object: Only valid with `action` = `pass`.
    - `target_role` 'ai_agent', required: The Business Agent reference accepts only `ai_agent`.

## Response `200`

Control changed. Meta documents `{"messaging_product":"whatsapp"}`; the Partner Portal source's
OpenAPI example shows `{"success": true}`. Neither has been observed on this route.

- object
  - `messaging_product` 'whatsapp'
  - `success` boolean

## Other responses

- `400`: Rejected by WASS (app state) or Meta (payload).
- `401`: Missing, invalid, or foreign-app token. Raised by Partner Portal before any forwarding.
- `405`: Method not routed (for example `PATCH`).
- `415`: Body was not `application/json`.
- `429`: Per-app rate limit exceeded. Retry after the 60-second window.

---

[API](https://skmtc.dev/gupshup/apis/partner-portal-meta-business-agent-bizai-api.md) - [All operations](https://skmtc.dev/gupshup/apis/partner-portal-meta-business-agent-bizai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gupshup/apis/partner-portal-meta-business-agent-bizai-api/revisions/4c52185f2153?raw)