Thread handover (thread.handover)
Meta raises messaging_handovers when control of a conversation moves between roles (pass, release, take), including a change you make with POST /v1/numbers/{phone_number_id}/thread-control(/reference/
Meta raises messaging_handovers when control of a conversation moves between roles (pass, release, take), including a change you make with POST /v1/numbers/{phone_number_id}/thread-control. data is Meta's value, verbatim, with field. The sender and recipient sub-shape is not fully published, so read raw for the exact fields. Meta reference: https://developers.facebook.com/documentation/business-messaging/whatsapp/conversation-routing/thread-control
Event type: thread.handover. Fixture payloads are the WhaBuzz Demo tenant's real ids with a fictional customer number; id, tenant_id and created_at in envelopes are illustrative.
#Control passed to another role
What Meta POSTs to WhaBuzz (fixtures/meta/messaging_handover_passed.json):
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "26059971920328384",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"sender": {
"phone_number_id": "1013622581841046"
},
"recipient": {
"wa_id": "16505551234"
},
"type": "control_passed",
"timestamp": "1761120120",
"previous_owner_role": "customer_service",
"new_owner_role": "escalation",
"metadata": "escalated from billing chat",
"conversation_context": {
"type": "summary",
"summary": {
"text": "Customer asks about a duplicate charge on the 7am batch plan."
}
}
},
"field": "messaging_handovers"
}
]
}
]
}What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.
{
"id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
"type": "thread.handover",
"api_version": "2026-10-16",
"created_at": "2025-10-22T08:02:00.481Z",
"tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
"waba_id": "26059971920328384",
"phone_number_id": null,
"display_phone_number": null,
"wamid": null,
"wa_id": "16505551234",
"user_id": null,
"dedupe_key": "handover:<sha256 of the canonical value>",
"data": {
"messaging_product": "whatsapp",
"sender": {
"phone_number_id": "1013622581841046"
},
"recipient": {
"wa_id": "16505551234"
},
"type": "control_passed",
"timestamp": "1761120120",
"previous_owner_role": "customer_service",
"new_owner_role": "escalation",
"metadata": "escalated from billing chat",
"conversation_context": {
"type": "summary",
"summary": {
"text": "Customer asks about a duplicate charge on the 7am batch plan."
}
},
"field": "messaging_handovers"
},
"raw": {
"…": "the complete Meta POST body, byte for byte, as shown above"
},
"raw_path": "entry[0].changes[0].value"
}#Control taken
What Meta POSTs to WhaBuzz (fixtures/meta/messaging_handover_taken.json):
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "26059971920328384",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"sender": {
"phone_number_id": "1013622581841046"
},
"recipient": {
"wa_id": "16505551234"
},
"type": "control_taken",
"timestamp": "1761120180",
"previous_owner_role": "customer_service",
"new_owner_role": "escalation"
},
"field": "messaging_handovers"
}
]
}
]
}What your endpoint receives, as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.
{
"id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
"type": "thread.handover",
"api_version": "2026-10-16",
"created_at": "2025-10-22T08:03:00.481Z",
"tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
"waba_id": "26059971920328384",
"phone_number_id": "1013622581841046",
"display_phone_number": null,
"wamid": null,
"wa_id": "16505551234",
"user_id": null,
"dedupe_key": "handover:<sha256 of the canonical value>",
"data": {
"messaging_product": "whatsapp",
"sender": {
"phone_number_id": "1013622581841046"
},
"recipient": {
"wa_id": "16505551234"
},
"type": "control_taken",
"timestamp": "1761120180",
"previous_owner_role": "customer_service",
"new_owner_role": "escalation",
"field": "messaging_handovers"
},
"raw": {
"…": "the complete Meta POST body, byte for byte, as shown above"
},
"raw_path": "entry[0].changes[0].value"
}This page as Markdown: /events/thread-handover.md. All docs in one file: /llms-full.txt. Status.