---
title: "Hand a conversation to or from Meta Business Agent"
method: POST
path: "/v1/inbox/conversations/{conversationId}/thread-control"
tags: ["Messages"]
---

# Hand a conversation to or from Meta Business Agent

`POST /v1/inbox/conversations/{conversationId}/thread-control`

WhatsApp only, on numbers with Meta Business Agent enabled. Wraps Meta's thread control:
- `release`: hand the conversation back to the agent so it resumes answering. You must currently hold control (sending any message takes it implicitly).
- `take`: take control before sending anything, so the agent stops replying while an operator reads the thread. Meta accepts this only from the business configured as the number's escalation partner; other apps take control by sending a message.
- `pass`: transfer control to the number's configured escalation partner, or to the agent with `target: ai_agent`. Meta's Cloud API currently rejects it ("Pass action is not supported", verified 2026-09-08); use `release` to hand a thread back to the agent.

The conversation's `threadControl` follows the result; a `conversation.control_changed` webhook fires when Meta later reports the change.

## Path parameters

- `conversationId` string, required

## Request body

- object
  - `accountId` string, required — Social account ID
  - `action` 'release' | 'take' | 'pass', required
  - `target` 'ai_agent' — With action pass: send control to Meta Business Agent instead of the escalation partner.
  - `metadata` string — Free-form note forwarded verbatim to the app receiving control (its messaging_handovers webhook).

## Response `200`

Control transferred

- object
  - `success` boolean
  - `control` object
    - `owner` 'app' | 'ai_agent' | 'other'

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Inbox addon required
- `404` — Account or conversation not found

## Changes

- **2026-09-25** `2c04683ce694` — 4 info
  - added the optional property `details/adAccountId` to the response with the `400` status
  - added the optional property `details/createdObjects` to the response with the `400` status
  - added the optional property `details/stage` to the response with the `400` status
  - added the optional property `details/unconfirmedWrite` to the response with the `400` status
- **2026-09-16** `3e6ddf2a99ea` — 1 info
  - added the optional property `details/budgetScope` to the response with the `400` status
- **2026-09-15** `0dba7d004d75` — 2 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaScope` to the response with the `400` status
- **2026-09-09** `41eff0cffb2d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/inbox/conversations/:conversationId/thread-control/post.md)

---

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