Transfer thread control

Transfer thread control for a consumer conversation: release it back to Meta Business Agent as the automatic responder, pass it to Meta Business Agent or the configured escalation partner, or take it from the current owner.

post

Authorizations

D360-API-KEYstringRequired

API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.

Header parameters

X-API-Versionstring · enumOptional

Meta Business Agent API version

Possible values:

Body

Thread control action to perform

actionstring · enumRequired

The thread control action to perform. "release" relinquishes thread control and hands the conversation back to Meta Business Agent as the automatic responder; you must currently hold thread control. "take" acquires thread control from the current owner and is restricted to the configured escalation partner. "pass" transfers thread control to Meta Business Agent when control_pass.target_role is "ai_agent", or to the configured escalation partner when control_pass is omitted; you must currently hold thread control.

Possible values:

messaging_productstring · enumRequired

Messaging service used for the request. Must be "whatsapp".

Possible values:

metadatastringOptional

Optional free-form string forwarded verbatim to the receiving app in the resulting messaging_handovers webhook.

recipientstringOptional

Business-scoped user ID of the consumer whose thread control is being transferred. Accepted but not yet wired; provide "to" instead.

tostringOptional

Consumer identifier (phone number or WhatsApp ID) whose thread control is being transferred.

Responses

200

Thread control action result with messaging product identifier

application/json

Thread control action result with messaging product identifier

messaging_productstring · enumRequired

Messaging service used for the response. Always "whatsapp".

Possible values:

400

Bad request

application/json

401

Unauthorized

application/json

429

Too many requests

application/json

500

Server error

application/json

post/agent_thread_control

POST /agent_thread_control HTTP/1.1
Host: waba-v2.360dialog.io
D360-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "action": "pass",
  "control_pass": {
    "target_role": "ai_agent"
  },
  "messaging_product": "whatsapp",
  "metadata": "text",
  "recipient": "text",
  "to": "text"
}

{
  "messaging_product": "whatsapp"
}