conversation.assigned

Fires when a conversation’s owner is set: routing gives a chat to a teammate, somebody takes a conversation nobody owned, or a widget chat is transferred.

Payload

{
  "id": "whd_6Kr3mP8wT",
  "event": "conversation.assigned",
  "createdAt": "2026-09-11T15:10:33.582Z",
  "data": {
    "conversationId": "conv_7Yn2kP",
    "assigneeId": "user_5Nc1rT",
    "previousAssigneeId": "user_8Vd4qM",
    "source": "manual",
    "sourceType": "widget"
  }
}

string

required

The conversation. Always present.

string

The member who owns the conversation now.

string

The member who owned it before. Omitted when nobody did, which is the case for a first assignment and for every conversation somebody takes.

string

How the owner was chosen: routing when routing rules assigned it, manual when a person took it or transferred it. Treat any other value as informational rather than as an error.

string

The channel the conversation came from: phone, email, sms, widget, meeting, slack.

Where assignments come from

What happened	`source`	`previousAssigneeId`
Routing assigns a widget chat or a Slack thread	`routing`	Omitted, unless it already had an owner
Somebody takes a conversation nobody owned	`manual`	Omitted
A widget chat is transferred to a teammate	`manual`	The previous owner

Email, SMS, call and meeting conversations start with no owner, so for those this fires only when somebody takes one.

Worth knowing

Offering a conversation fires nothing. When routing offers a conversation to several people at once, nobody owns it yet. The event arrives when one of them takes it.
Taking a conversation that already has an owner changes nothing, so it sends nothing either.
The owner can arrive unchanged. Routing that runs again for a conversation can assign the person who already had it, and previousAssigneeId then equals assigneeId.
Ids, not names. assigneeId and previousAssigneeId are member ids. Resolve them against your workspace’s member list, and cache the map.

Example

custral.on("conversation.assigned", async (event) => {
  const {conversationId, assigneeId, previousAssigneeId, sourceType} = event.data;
  if (assigneeId === previousAssigneeId) return;

  await helpdesk.assignTicket({
    externalId: conversationId,
    agent: await directory.lookup(String(assigneeId)),
    channel: sourceType,
  });
});

Getting started

Building a receiver

Event reference

Operations

Payload

Where assignments come from

Worth knowing

Example

​Payload

​Where assignments come from

​Worth knowing

​Example

Payload

Where assignments come from

Worth knowing

Example