chat.assigned

Sent when a chat changes agent or team. Someone assigns it in the app or over the API, the chatbot passes it on, or it comes back to the bot because an agent resumed it or it was closed. Use it to keep your own tools in step with who has the chat.

Called Chat assigned in the app. Part of the plan feature webhooks.chats. To subscribe over the API, the key needs chats:write.

PayloadPOST to your endpoint

{
  "id": "evt_7a33656e45e7061194330b88bcb6047b",
  "type": "chat.assigned",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:14:36.205Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
    "team_id": null,
    "by": {
      "type": "api_key",
      "id": "5e1d2c3b-4a59-4f68-8e7d-6c5b4a392817",
      "name": "Order system"
    }
  }
}

Headers

webhook-id: The delivery’s ID, the same on every try.
webhook-timestamp: When this try was sent, in Unix seconds.
webhook-signature: v1, and an HMAC-SHA256 of the request.

How delivery and retries work

Data

What’s in data. Every event wraps it in the same envelope.

contact_id string · uuid

agent_id string · uuid · nullable

The agent the chat is assigned to now, as chat.assigned_agent_id on the contact shows it. null when nobody is.

team_id string · uuid · nullable

The team the chat is with now. null when no team has it.

by object

Who made the change: a team member, an API key, the chatbot or another actor.

Show 3 child attributesHide child attributes

by.type string

Who or what it was: a team member, an API key, the chatbot, the AI, an automation, a broadcast, the WhatsApp Business app or Soosh itself. More values may be added.

One of user api_key bot ai automation broadcast whatsapp_app system.

by.id string · uuid · nullable

The person, key or broadcast. null for actors without one, such as the chatbot.

by.name string

When nothing is sent

A change that leaves both the agent and the team as they were sends nothing.

Handling it

Answer with any 2xx within 10 seconds. Do the work after.
Check the signature first. Verify webhooks has the code.
Subscribe with POST /v1/webhooks, events: ["chat.assigned"].