# conversation.owner_changed

HTML: https://www.app2email.com/docs/api/webhooks/conversation.owner_changed · Index: https://www.app2email.com/docs/api/llms.txt

Who handles a contact changed: human, agent, paused or back to normal; or WhatsApp's AI agent took or passed on the conversation (owner whatsapp_ai).

Group: Conversations. Header `X-App2email-Event: conversation.owner_changed`. Inside the envelope `{id, type, created, number, test?, data}` ([envelope, headers, signature](https://www.app2email.com/docs/api/webhooks.md)). Every webhook of the number gets every number event: filter by `type`.

## data

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data.contact` | string | yes |  |
| `data.owner` | string | yes | agent, human, paused, whatsapp_ai (WhatsApp's AI agent holds it), or empty (normal handling). |
| `data.previous_owner` | string |  |  |
| `data.reason` | string |  |  |
| `data.summary` | string |  |  |
| `data.until` | string |  |  |
| `data.set_by` | string |  | api, dashboard, agent ..., or whatsapp (a handover of WhatsApp's AI agent). |
| `data.timestamp` | string |  |  |
| `data.handover` | string |  | Only for set_by whatsapp.; one of: `control_passed`, `control_taken` |
| `data.whatsapp_roles` | object |  | Meta's owner roles, eg ai_agent, escalation. |
| `data.whatsapp_roles.previous` | string |  |  |
| `data.whatsapp_roles.new` | string |  |  |

## Samples

### human

```json
{
  "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
  "type": "conversation.owner_changed",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "contact": "61412345678",
    "owner": "human",
    "previous_owner": "agent",
    "reason": "The customer asked for a person",
    "summary": "Asked about a late delivery",
    "set_by": "dashboard",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

### whatsapp ai

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs015",
  "type": "conversation.owner_changed",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "contact": "61412345678",
    "owner": "",
    "previous_owner": "whatsapp_ai",
    "reason": "asked for a person",
    "summary": "Asked about a late delivery of order 1234.",
    "set_by": "whatsapp",
    "handover": "control_passed",
    "whatsapp_roles": {
      "previous": "ai_agent",
      "new": "escalation"
    },
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

## Caused by

- [Hand a contact over: human, agent, paused, or back to normal](https://www.app2email.com/docs/api/conversations/set-conversation-owner.md): `PUT /v1/{number}/conversations/{contact}/owner`

Send it to your URL: https://www.app2email.com/docs/api/webhooks/tester?type=conversation.owner_changed
