---
title: "Change who answers a conversation (handover)"
method: POST
path: "/v1/messaging/inbox/conversations/{conversationId}/thread-control"
tags: ["Messages"]
---

# Change who answers a conversation (handover)

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

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/inbox/conversations/{conversationId}/thread-control`
- Auth: HTTP bearer

Meta's handover protocol on WhatsApp, Facebook and Instagram.

**WhatsApp**, on numbers with Meta Business Agent enabled:
- `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.

**Facebook and Instagram** (Messenger Platform handover between the apps on the Page, such as Page Inbox):
- `pass` with `targetAppId`: give the thread to another app (`pass_thread_control`). Page Inbox is 263902037430900.
- `take`: take the thread back (`take_thread_control`); Meta allows it only to the Page's primary receiver, and only on accounts connected through a Facebook Page. On an Instagram Login connection it answers 400 `platform_not_supported`.
- `request`: ask the current owner to pass the thread (`request_thread_control`); nothing changes until it does. Not available on Instagram Login connections (400 `platform_not_supported`).
- `release`: give the thread back to the primary receiver (`release_thread_control`).

While another app owns a Facebook or Instagram thread, inbound arrive with `metadata.standby: true` and a send answers 409 `not_thread_owner`. The conversation's `threadControl` follows the result; a `conversation.control_changed` webhook fires when Meta later reports the change.


**Billing:** Request; paid actions are priced in credits (see GET /v1/messaging/prices) · **Rate limit:** 60/min

## Path parameters

- `conversationId` string, required: The conversation ID

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `action` 'release' | 'take' | 'pass' | 'request', required: `request` is Facebook and Instagram only. `take` and `request` are refused with `platform_not_supported` on Instagram accounts connected with Instagram Login.
  - `target` 'ai_agent': WhatsApp only. 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).
  - `accountId` string, required: Social account ID
  - `targetAppId` string: Facebook and Instagram only, required with action pass: the Meta app id receiving the thread.

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `control` object
      - `owner` 'app' | 'ai_agent' | 'other'
      - `ownerAppId` string: The app that received the thread, on a Facebook or Instagram pass.
    - `success` boolean
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)