Conversations API reference

Conversations endpoints of the Quackback REST API: paths, parameters, request fields and responses.

JM
James Morton
Written By James MortonLast updated 3 days ago

This is the reference for the Conversations endpoints of the Quackback REST API: every endpoint, its parameters, request fields and response fields. It is generated from the API's OpenAPI description, so it matches what the API accepts.

All paths are relative to /api/v1 on your workspace's address (for example https://feedback.example.com/api/v1). Authenticate with an API key in the Authorization: Bearer qb_... header. For keys, errors, pagination and rate limits, see API overview. Every workspace also serves an interactive reference at /api/v1/docs.

Endpoints

  • GET /conversations: List conversations
  • GET /conversations/{conversationId}: Get a conversation
  • GET /conversations/{conversationId}/messages: List messages in a conversation
  • POST /conversations/{conversationId}/reply: Reply to a conversation
  • POST /conversations/{conversationId}/note: Add an internal note to a conversation
  • POST /conversations/{conversationId}/status: Set a conversation status
  • POST /conversations/{conversationId}/assign: Assign a conversation
  • POST /conversations/{conversationId}/priority: Set a conversation priority
  • POST /conversations/{conversationId}/read: Mark a conversation read
  • POST /conversations/{conversationId}/tags: Attach a tag to a conversation
  • DELETE /conversations/{conversationId}/tags: Detach a tag from a conversation

List conversations

GET /api/v1/conversations

Returns a paginated list of support conversations. Requires a team-role API key.

Parameters

Name

In

Type

Required

Description

status

query

string (open, snoozed, closed)

No

Filter by conversation status

priority

query

string (none, low, medium, high, urgent)

No

Filter by triage priority

assignedAgentPrincipalId

query

string

No

Filter by assigned agent principal ID

cursor

query

string

No

Pagination cursor from previous response

limit

query

integer

No

Items per page (max 100)

Response 200: returns id, status, channel, priority, subject, visitorPrincipalId, visitorEmail, assignedAgentPrincipalId, lastMessageAt, resolvedAt, createdAt.

Get a conversation

GET /api/v1/conversations/{conversationId}

Get a single conversation by ID. Requires a team-role API key.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Response 200: returns id, status, channel, priority, subject, visitorPrincipalId, visitorEmail, assignedAgentPrincipalId, lastMessageAt, resolvedAt, createdAt.

List messages in a conversation

GET /api/v1/conversations/{conversationId}/messages

Returns a paginated list of messages in a conversation. Internal agent notes are excluded by default. Requires a team-role API key.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

includeInternal

query

boolean

No

Include internal agent notes (default: false)

cursor

query

string

No

Pagination cursor from previous response

limit

query

integer

No

Items per page (max 100)

Response 200: returns id, conversationId, senderType, isInternal, authorPrincipalId, authorName, content, createdAt, editedAt.

Reply to a conversation

POST /api/v1/conversations/{conversationId}/reply

Send an agent reply (visible to the visitor).

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

content

string

Yes

Message body as markdown

attachments

array of object

No

Response 201: returns id, conversationId, senderType, isInternal, authorPrincipalId, authorName, content, createdAt, editedAt.

Add an internal note to a conversation

POST /api/v1/conversations/{conversationId}/note

Add an agent-only internal note (never visible to the visitor).

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

content

string

Yes

Message body as markdown

attachments

array of object

No

Response 201: returns id, conversationId, senderType, isInternal, authorPrincipalId, authorName, content, createdAt, editedAt.

Set a conversation status

POST /api/v1/conversations/{conversationId}/status

Set open / snoozed / closed. No required-attributes close-guard for API closes.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

status

string (open, snoozed, closed)

Yes

Response 200: returns id, status, channel, priority, subject, visitorPrincipalId, visitorEmail, assignedAgentPrincipalId, lastMessageAt, resolvedAt, createdAt.

Assign a conversation

POST /api/v1/conversations/{conversationId}/assign

Assign to a teammate, or pass null to unassign.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

assigneePrincipalId

string

No

Agent principal id; null or omitted unassigns

Response 200: returns id, status, channel, priority, subject, visitorPrincipalId, visitorEmail, assignedAgentPrincipalId, lastMessageAt, resolvedAt, createdAt.

Set a conversation priority

POST /api/v1/conversations/{conversationId}/priority

Set the triage priority on a conversation.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

priority

string (none, low, medium, high, urgent)

Yes

Response 200: returns id, status, channel, priority, subject, visitorPrincipalId, visitorEmail, assignedAgentPrincipalId, lastMessageAt, resolvedAt, createdAt.

Mark a conversation read

POST /api/v1/conversations/{conversationId}/read

Mark the conversation read up to now for the agent side. Publishes a realtime read event that clears the unread signal teammates see.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Response 200: returns ok.

Attach a tag to a conversation

POST /api/v1/conversations/{conversationId}/tags

Attach an existing conversation tag (idempotent). Returns the updated tag list.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

tagId

string

Yes

Existing conversation tag id

Response 200: returns id, name, color.

Detach a tag from a conversation

DELETE /api/v1/conversations/{conversationId}/tags

Detach a conversation tag. Returns the updated tag list.

Parameters

Name

In

Type

Required

Description

conversationId

path

string

Yes

Conversation ID

Request body

Field

Type

Required

Description

tagId

string

Yes

Existing conversation tag id

Response 200: returns id, name, color.

Was this helpful?

Your feedback shapes what we write next.

← Previous

Changelog API reference

Next →

Tickets API reference

Related articles

Tickets API referenceTickets endpoints of the Quackback REST API: paths, parameters, request fields and responses.Tags API referenceTags endpoints of the Quackback REST API: paths, parameters, request fields and responses.Posts API referencePosts endpoints of the Quackback REST API: paths, parameters, request fields and responses.Comments API referenceComments endpoints of the Quackback REST API: paths, parameters, request fields and responses.