Hi Brian,
Thanks for sharing this. There’s definitely a little complexity around the conversation states here. Hope I can provide some clarity here;
| Status | Can not be status | Description |
|---|
| assigned | unassigned | Conversations which have an assignee |
|---|
| unassigned | assigned | Conversations which do not have an assignee |
|---|
| archived | open, trashed, snoozed | Conversations which are archived (appear in the Archived inbox tab) |
|---|
| trashed | archived, open, snoozed | Conversations in the Trash inbox tab |
|---|
| open | archived, trashed, snoozed | Open conversations (not archive/trashed/snoozed) |
|---|
| snoozed | archived, trashed, open | Snoozed (will be reopened at a later date) |
|---|
| unreplied | | Conversations where the last message was inbound (To the channel) |
|---|
To address your questions;
If I remove is:open from my own searches, the “assigned” status is ignored; everything is returned. ie this returns convos with status: archived.
It sounds like your filter is simply is:assigned
If this is the case, conversations can have an assignee, and be archived (i.e. not open) - just take a look in the Archived tab of your Assigned to me folder; archived (not open), but assigned.
If I replace “open” with “unreplied”, I also get every status message.
It sounds like your filter is is:unreplied
If this is the case, that behavior is expected. The search is asking for conversations where the last message was inbound (the external sender has not received a reply). We’re not filtering based on any statuses here.
Thanks for the note about the double-encoded example. We’ll take a look into what can be done about that.
Let us know if you have other questions, or you have a query about how to search for conversations in a specific state
Wow thanks for that thorough and fast reply! Very helpful. Did I miss that chart somewhere in the docs?
If the API is returning messages that are both assigned and archived, how does it decide whether the response JSON “status” will be “assigned” or “archived”? Seems like it never sets “status” to “open”, for instance.
This is way out of scope, but “status” should either come back as an array of values, or those values should be spit into mutually compatible categories (status: assigned/unassigned, inbox_state: archived/trashed/open, is_snoozed: true/false, is_replied: true/false)
Thanks again for the help and patience.
Thanks Brian,
You didn’t miss the table; I just put that together as a quick demo.
So the API conversation.status field will return one of 4 statuses;
| conversation.status | Meaning | Search |
|---|
| unassigned | Open and unassigned | is:open is:unassigned |
|---|
| assigned | Open and assigned | is:open is:assigned |
|---|
| archived | Archived (assigned or unassigned)
Snoozed conversations appear as status = archived, and have a reminder object indicating when the snooze ends | is:archived / is:snoozed |
|---|
| deleted | Trashed (assigned or unassigned) | is:trashed |
|---|
These conversation.status values map closely to what you see in the app; if you click into a shared inbox, you’ll notice the Unassigned / Assigned / Archived inbox tabs.
I agree the status value is not always super clear, but it can be determined based on the value of the conversation.assignee (for assignment state) and conversation.reminders (for snoozed state) fields. For the replied/unreplied state, you do need to fetch the last message from the conversation and determine the message direction (inbound vs outbound) to see if it was replied or not.
Again, I hope this helps provide some clarity. Let me know if you have more questions
Perfect, thanks, Jason! I’ve wrestled with a bunch of APIs in this space, and your knowledge, patience, and care in understanding what I’m saying is a huge differentiator.
@brian_herbert Thanks for helping to improve our documentation! I’ve added this information to the search topic. We will also update the OpenAPI spec to fix the double-encoded example.
Cheers
