---
title: "Release thread control (Facebook & Instagram)"
method: POST
path: "/api/chats/{id}/release_thread_control"
tags: ["Direct Messages"]
---

# Release thread control (Facebook & Instagram)

`POST /api/chats/{id}/release_thread_control`

## Request

- Base URL: `https://api.postproxy.dev`
- URL: `https://api.postproxy.dev/api/chats/{id}/release_thread_control`
- Auth: HTTP bearer

Gives up control; the conversation goes idle and the Page's default app answers the next message. Only the current owner can release. Synchronous; returns the chat.

## Query parameters

- `profile_group_id` string

## Request body

- DmThreadControlRequest
  - `target_app_id` string: Numeric Meta app ID that receives the conversation. Required for pass_thread_control only.
  - `metadata` string: Free-form note forwarded to the receiving app in its handover webhook.

## Response `200`

The chat, with metadata.thread_control refreshed.

- DmChat: A 1:1 conversation between a profile and a participant.
  - `id` string: Chat hashid
  - `profile_id` string: Profile hashid this chat belongs to
  - `platform` 'facebook' | 'instagram' | 'telegram' | 'bluesky': Network ID
  - `participant_external_id` string: Platform-native participant ID
  - `participant_username` string, nullable: Participant's username (when known)
  - `participant_name` string, nullable: Participant's display name (when known)
  - `participant_avatar_url` string, nullable: Stable storage URL of the participant's profile picture (null until fetched)
  - `external_conversation_id` string, nullable: Platform's native conversation ID (when known)
  - `last_inbound_at` string, nullable: ISO 8601 timestamp of last inbound message
  - `last_outbound_at` string, nullable: ISO 8601 timestamp of last outbound message
  - `last_message_at` string, nullable: ISO 8601 timestamp of last message in either direction
  - `archived` boolean: Bluesky only — whether the chat is muted/archived
  - `metadata` DmChatMetadata, nullable: Platform-specific information about the participant, fetched asynchronously when the chat is first created and refreshed at most once per hour on inbound messages. Keys are only present when the platform returns a value — treat missing keys as unknown, not false.
    - `page_id` string: Facebook — Page ID this chat is owned by (required for sending)
    - `participant_fetched_at` string: ISO 8601 timestamp of the last recipient-info refresh
    - `language_code` string: Telegram — IETF language tag reported by Telegram for the user
    - `muted` boolean: Bluesky — whether the conversation is muted/archived
    - `is_verified_user` boolean: Instagram — participant has a verified account
    - `is_user_follow_business` boolean: Instagram — participant follows the business profile
    - `is_business_follow_user` boolean: Instagram — the business profile follows the participant
    - `follower_count` integer: Instagram — participant's follower count
    - `referral` object: Latest ig.me / m.me link referral (latest referral wins)
      - `ref` string
      - `source` string
      - `type` string
      - `received_at` string
    - `last_referral_at` string: ISO 8601 timestamp of the latest referral (opens the 24-hour messaging window)
    - `thread_control` object: Facebook & Instagram — which Meta app controls the conversation, once known. See Thread control.
      - `owner_app_id` string, nullable: Meta app ID that controls the conversation; null while idle (or when another app took it without Postproxy seeing it).
      - `expires_at` string, nullable: ISO 8601 time the owner's control lapses.
      - `updated_at` string: ISO 8601 time the value was last recorded.
  - `created_at` string: ISO 8601 timestamp of chat creation
  - `external_placement_id` string, nullable: The placement the chat runs on — the phone number id on WhatsApp, the Page id on Facebook chats that have one. Null otherwise.
  - `group` boolean: True when the chat is a WhatsApp group rather than a 1:1 conversation.
  - `within_messaging_window` boolean: WhatsApp only. Whether a free-form send is currently allowed — true for 24 hours after the customer’s last inbound message or referral. Outside it, send an approved template.

## Other responses

- `401`: Invalid, missing, or insufficient API key permissions.
- `403`: Meta refused the change (Postproxy isn't the owner, or takeover isn't allowed in the Page's settings). Meta's message is passed through.
- `404`: Resource does not exist or is not accessible.
- `422`: Validation failed.

---

[API](https://skmtc.dev/postproxy/apis/postproxy-social-media-api.md) - [All operations](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/llms.txt) - [OpenAPI document](https://skmtc.dev/postproxy/apis/postproxy-social-media-api/revisions/d54482ac4ce7?raw)