File a thread in a folder
file_conversationFiles a thread where you say: "archive" puts it away, out of the Inbox and kept for good; "trash" throws it away, where it stays readable and can be brought back; "inbox" brings it back from wherever it was; or "folder_id" files it in a folder a person made (list_folders gives them), which becomes its home. One thread sits in one place, so filing it somewhere takes it out of where it was; a reply brings a thread back to the Inbox without taking it out of its folder. This is the gesture for tidying a mailbox, and "trash" is what "delete this thread" almost always means: nothing is lost for 30 days, after which the Trash deletes it for good, and delete_conversation is the other, immediate and final thing. It does not file spam: report_spam is that gesture, because filing as spam also blocks the sender. A thread of a helpdesk queue has the Trash as its one folder: "trash" throws it away (a spam, a phishing attempt, a prospecting mail nobody answers) and "inbox" brings it back to the view its status belongs to; "archive" is refused there, closing a case being how a queue puts it away. Filing never changes where a thread STANDS: a notice thrown in the Trash is still "open", among what is left to do. Give "status" (and "deal_stage") to settle that in the same gesture, as set_conversation_status would: "trash" with "closed" tidies away what nobody answers, "archive" with "answered" or "closed" puts away an exchange that is over. The status is recorded first, so a status refused leaves the thread where it was, and a thread that then cannot be filed answers that its status was recorded and why it stayed put. To file several threads in the same place, give conversation_id the list of their ids, in ONE call rather than one call per thread: the answer then lists in "results" the outcome of each thread in the order given ("ok", with its "result" or its "error") and counts "succeeded" and "failed". Each thread passes exactly the checks it would alone, so one refused or out of reach ("not found") leaves the others done, and the call is an error only when none succeeded.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Where the thread goes: "archive" to put it away, "trash" to throw it away restorably, "inbox" to bring it back. "spam" is not one of them: call report_spam, which blocks the sender too. Leave it out when you give "folder_id". | |
| status | No | Where the thread stands: "open" for one nobody has taken, "customer_reply" when the contact has written back, "answered" once we replied, "delivery_failed" when our reply bounced, "in_progress" while someone works on it, "closed" when it is over. | |
| folder_id | No | A folder a person made in the thread's box, by its id from list_folders, instead of "folder". | |
| deal_stage | No | Where the thread stands in the pipeline, in your own vocabulary, up to 128 characters. An empty string clears it. | |
| conversation_id | Yes | The id of the conversation, as list_conversations gives it, or a list of up to 50 ids to do the same to every one of them in a single call. |