Fin Agent Status Updated Event

Home/

REST API Reference

Event fired when Fin's status changes during a conversation. Fin will report its status to the client via this event.

event_namestringrequired

The name of the event.

Value:"fin_status_updated"

Example:"fin_status_updated"

conversation_idstringrequired

The ID of the conversation.

Example:"123456"

user_idstringrequired

The ID of the user.

Example:"7891"

statusstringrequired

Fin's current status.

awaiting_user_reply: Fin has finished replying and is waiting for the user to respond
escalated: The conversation has been escalated to a human
resolved: The user's query has been resolved
complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires

Enum:"awaiting_user_reply""escalated""resolved""complete"

Example:"escalated"

reasonstring

Optional. A human-readable explanation of why the conversation was escalated. Only present when status is 'escalated'.

When you escalate deterministically with /fin/escalate, the reason is always "Escalation requested via API".

The following reasons apply to Fin-decided escalations when Fin owns the conversation (/fin/start, and /fin/reply on a conversation that was started that way):

"Escalation requested by user"
"Escalation rule: {rule_name}"
"Escalation rule matched"
"Routed to team"
"Conversation finished without resolution"

Example:"Escalation requested via API"

created_at_msstring, (date-time)required

The timestamp the event was created at, with millisecond precision.

Example:"2025-01-24T10:00:00.123Z"

{
  "event_name": "fin_status_updated",
  "conversation_id": "123456",
  "user_id": "7891",
  "status": "escalated",
  "reason": "Escalation requested via API",
  "created_at_ms": "2025-01-24T10:00:00.123Z"
}