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

Changed in 4 of the 55 revisions of this API.8

  • 2c04683ce6944See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3e6ddf2a99ea1See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 0dba7d004d752See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 41eff0cffb2d1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog