Conversation · StartupBuilder

Properties

Property	Type	Description
`answeredAt`	`datetime`	When a Worker last answered.
`firstAnsweredAt`	`datetime`	When a Worker first answered; set once, never overwritten. `answeredAt` keeps the last answer.
`respondBy`	`datetime`	When the first answer is due: Setting `support.firstResponseWithin` per Offer, default 4 business hours.
`status`	`string`	Open, waiting on the Customer, or resolved; computed from its answers, closes and reopens.
`resolvedAt`	`datetime`	When it was resolved; empty again when the resolution reverses.
`resolution`	`string`	How it was resolved: the Customer said so, or 72 hours passed after an answer with no reply.

Inherited from Thread: 1 property

Property	Type	Required	Description
`subject`	`string`		What the Thread is about.

Object

JSON

{
  "$id": "https://api.sb/shiftnote.app/conversations/conversation_1",
  "$type": "Conversation",
  "subject": "Example subject",
  "answeredAt": "2026-10-22T12:00:00Z",
  "firstAnsweredAt": "2026-10-22T12:00:00Z",
  "respondBy": "2026-10-22T12:00:00Z",
  "status": "open",
  "resolvedAt": "2026-10-22T12:00:00Z",
  "resolution": "confirmed"
}

Relationships

A Conversation awaits one Worker: one Worker owes each Conversation its next answer. awaits, inverse conversations.
A Conversation has one Customer: the Customer a Conversation serves, so every answer reads that Customer’s records. customer, inverse opens.
A Conversation raises many Threads: the intake Threads a support Conversation opens, each deadline counted from the Conversation’s first Message. raises, inverse raisedIn.
A Conversation reports one Issue: the Issue or Incident a Conversation reports; resolving it answers every linked Conversation. reports, inverse conversations.

Lifecycle

State	Meaning	Moves to
`open` (first)	A Contact wrote, and a Worker owes the answer by `respondBy`.	`waiting` on `Conversation.answered`; `waiting` on `Action.asked` when the Question goes to this Conversation’s Contact; `resolved` on `Conversation.closed`
`waiting`	A Worker answered, and the Customer owes the reply.	`open` on `Message.created` when a Contact’s Message arrives in this Conversation; `resolved` on `Conversation.closed`
`resolved`	Resolved, confirmed by the Customer or assumed after 72 hours with no reply.	`open` on `Conversation.reopened`

Verbs

createCreates a Conversation.
POST /{namespace}/conversationsdoConversation.created
getReturns one Conversation by id.
GET /{namespace}/conversations/{id}readNo Event
listReturns Conversations, newest first, one page at a time.
GET /{namespace}/conversationsreadNo Event
updateChanges the given properties of a Conversation.
PATCH /{namespace}/conversations/{id}doConversation.updated
deleteDeletes a Conversation; its history is kept.
DELETE /{namespace}/conversations/{id}doConversation.deleted
answerAnswer replies in a Conversation through the Channel it arrived on and closes the reply Task it opened.
POST /{namespace}/conversations/{conversation}/answerdoConversation.answered
assignAssign routes a Conversation to the Worker holding the right Role, by topic, Customer tier and language.
POST /{namespace}/conversations/{conversation}/assigndoConversation.assigned
closeClose marks a Conversation resolved, confirmed by the Customer or assumed after 72 hours with no reply.
POST /{namespace}/conversations/{conversation}/closedoConversation.closed
escalateEscalate hands a Conversation and its summary to the Worker in the Role above, a Human only where one holds it.
POST /{namespace}/conversations/{conversation}/escalatedoConversation.escalated
reopenReopen reverses a Conversation’s resolution when a reversal signal arrives within 7 days, and grades the resolution a failure.
POST /{namespace}/conversations/{conversation}/reopendoConversation.reopened

Permissions

Which Access level may call each Verb. One-way Verbs wait their delay window.

Operation	`owner`	`admin`	`member`	`viewer`
`Conversation.create`	Yes	Yes	Yes	No
`Conversation.get`	Yes	Yes	Yes	Yes
`Conversation.list`	Yes	Yes	Yes	Yes
`Conversation.update`	Yes	Yes	Yes	No
`Conversation.delete`	Yes	Yes	Yes	No
`Conversation.answer`	Yes	Yes	Yes	No
`Conversation.assign`	Yes	Yes	Yes	No
`Conversation.close`	Yes	Yes	Yes	No
`Conversation.escalate`	Yes	Yes	Yes	No
`Conversation.reopen`	Yes	Yes	Yes	No

Call it

Text

Answer the latest conversation.

Example

A Customer emails "my API key stopped working." The Conversation stays open until the support Agent answers and the Customer confirms the fix.

PropertiesCopy Anchor Link

ObjectCopy Anchor Link

RelationshipsCopy Anchor Link

LifecycleCopy Anchor Link

VerbsCopy Anchor Link

PermissionsCopy Anchor Link

Call itCopy Anchor Link

ExampleCopy Anchor Link