List Conversations

[
  {
    "conversationStatus": "NEEDS_HELP",
    "createdAt": "2024-01-15T09:30:00Z",
    "emailSubject": "emailSubject",
    "id": "id",
    "lastReceivedMessage": {
      "id": "id",
      "conversationId": "conversationId",
      "type": "OUTBOUND",
      "content": "content",
      "messageStatus": "messageStatus",
      "messageStatusReason": "messageStatusReason",
      "messageSid": "messageSid",
      "customerStatus": "customerStatus",
      "idempotencyId": "idempotencyId",
      "isAutomated": true,
      "needsHelp": true,
      "subject": "subject",
      "emailAddress": "emailAddress",
      "attachments": [
        {}
      ],
      "metadata": {
        "key": "value"
      },
      "organizationId": "organizationId",
      "customerId": "customerId",
      "prospectId": "prospectId",
      "userId": "userId",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z"
    },
    "lastReceivedMessageId": "lastReceivedMessageId",
    "lastUsedEmailAddress": "lastUsedEmailAddress",
    "messageType": "SMS",
    "needsHelpMessageIds": [
      "needsHelpMessageIds"
    ],
    "propertyId": "propertyId",
    "recipient": {
      "customerId": "customerId",
      "prospectId": "prospectId",
      "lastUsedPhoneNumberId": "lastUsedPhoneNumberId"
    },
    "recipients": [
      {}
    ],
    "updatedAt": "2024-01-15T09:30:00Z"
  }
]

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.

<Badge>Available by Request</Badge> 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. <Note> This endpoint is part of our evolving API ecosystem. To explore availability for your integration, please contact our team. </Note> <Note> Filtering, sorting, field selection, and pagination are not available on this endpoint. The `fields`, `sort`, `filter`, `page`, and `limit` query parameters are ignored. </Note>

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.

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.

createdAtdatetimeOptional

emailSubjectstringOptional

Subject line of the email thread. Email conversations only.

idstringOptional

Unique identifier for the conversation.

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.

lastReceivedMessageIdstringOptional

The most recent inbound message on the conversation.

lastUsedEmailAddressstringOptional

Most recent email address used for this conversation. Email conversations only.

messageTypeenumOptional

The channel the conversation takes place on.

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"

recipientobjectOptional

The party currently being messaged.

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.

updatedAtdatetimeOptional

Errors

400

List Conversations Request Bad Request Error

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.