Sign in
Messages

Hand a conversation to or from Meta Business Agent

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.

post/v1/inbox/conversations/{conversationId}/thread-control

Path parameters

conversationIdstring required

The conversation ID

Request body

accountIdstring 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.

metadatastring

Free-form note forwarded verbatim to the app receiving control (its messaging_handovers webhook).

Response

Control transferred

successboolean

Changes