REST API: conversations and notes
Inspect conversations, send messages, and manage durable notes.
Start conversation automation with an agent-scoped list. Then fetch messages or notes for the specific conversation that your workflow selects. Conversation message lists have their own limits and schema. Do not apply assumptions from agent or contact lists to them. A message submission is an externally visible mutation. Use a backend-owned key, and make retries idempotent in your own service.
A message can carry attachments. When a customer emails your agent and attaches a file, every message in the list gets an attachments array. Each entry names the file, its content type and its size. Each entry also carries an id, a hasText flag and an available flag. Use the attachment endpoint with that id to read the text the platform extracted from the file when it arrived. The endpoint does not serve the file's bytes. It serves metadata and text, which is what an automated workflow can act on. Cap the text with maxTextChars when you pass the result to a model. The response reports textTruncated when the cap applied.
Read available: false as a record that the customer sent a file the platform could not store. The row stays in the list on purpose. A missing row would tell your workflow that the customer sent nothing, which is a different and wrong conclusion. hasText: false is not a failure. It means the file has no extractable text, such as an archive. Download that file from the dashboard instead.
Notes are separate durable records attached to a conversation. Create a note when information must be explicit to the team. Update the note when its source changes. Delete a note only under a deliberate retention policy. A note is not a raw chat message. Do not treat a note as an immutable audit record.
Conversation deletion removes a resource, so gate it behind administrative review when your policy requires it. Before you delete a conversation, confirm the organization ID, the agent ID, and the conversation ID. Export any data that your policy requires. Capture the API outcome. Use the Help Desk guides for the user-facing ticket workflow. This guide covers backend integration behavior.