Skip to navigation
API ReferenceMessaging

List Conversations

Available by Request

List conversations. A conversation is the running message thread between a property and one recipient; every message belongs to exactly one.

Look conversations up one of three ways, in this order of precedence:

  • By recipient — supply recipientId with a customer id or prospect id.
  • By household — supply householdId together with propertyId. Returns the conversations for every member of the household.
  • By property — supply propertyId alone, optionally narrowed with status.

The recipient and household lookups embed the most recent inbound message under lastReceivedMessage. The property lookup does not.

This endpoint is part of our evolving API ecosystem. To explore availability for your integration, please contact our team.

Filtering, sorting, field selection, and pagination are not available on this endpoint. The fields, sort, filter, page, and limit query parameters are ignored.

Authentication

x-api-keystring
API Key authentication via header

Query parameters

recipientIdstringOptionalformat: "uuid"
A customer id or prospect id. Takes precedence over the other lookups.
householdIdstringOptionalformat: "uuid"

Return conversations for every member of this household. Must be supplied together with propertyId.

propertyIdstringOptionalformat: "uuid"

Return conversations belonging to this property, or scope a householdId lookup.

statusenumOptional

Narrow a propertyId lookup to conversations in this state. Ignored by the other lookups.

Response

Expected response to a valid request. Returns an empty array when nothing matches.
idstringOptional
Unique identifier for the conversation.
conversationStatusenumOptional

Where the conversation stands. NEEDS_HELP prevails over every other value for as long as any message on the conversation has an open needs-help flag — see needsHelpMessageIds — and the conversation returns to whatever status the underlying workflow calls for once the last flag is resolved. NEW is set when an inbound message arrives and no one has responded yet, UNRESOLVED while a staff member is working it, and RESOLVED once it is closed. INVALID_PHONE_NUMBER and INVALID_EMAIL indicate the recipient could not be reached.

messageTypeenumOptional
The channel the conversation takes place on.
Allowed values:
recipientslist of objectsOptional
Everyone linked to the conversation. A conversation may follow a person from prospect through customer, so both ids can appear over its lifetime.
recipientobjectOptional
The party currently being messaged.
emailSubjectstringOptional
Subject line of the email thread. Email conversations only.
lastUsedEmailAddressstringOptional
Most recent email address used for this conversation. Email conversations only.
lastReceivedMessageIdstringOptional
The most recent inbound message on the conversation.
needsHelpMessageIdslist of stringsOptional

Ids of messages on this conversation with an open needs-help flag. Empty when nothing is flagged. The conversation reads NEEDS_HELP for as long as this is non-empty.

propertyIdstringOptionalformat: "uuid"
createdAtdatetimeOptional
updatedAtdatetimeOptional
lastReceivedMessageobjectOptional

The most recent inbound message, embedded in full. Only returned when the conversations are looked up by recipientId or by householdId; the propertyId lookup omits it. Attachment download URLs are not generated for the embedded message — read the message directly to get them.

Errors

400
Bad Request Error