Retrieving messages

Access all messages associated with an Issue. Messages represent the communication thread between reporters and responders, including:

Original messages from reporters
Replies from Issue handlers
Translations, machine and human
Questions and conversation transcripts
Multi-language support

Messages are read only. The API cannot post a reply into the Reporter conversation.

On this page: Query parameter · Message object · Message item object · Version types · Content types · Response scenarios · Data models reference

Query parameter

Messages are only included in the response when the messages=true query parameter is specified.

GET /v1/public/issues/{id}?messages=true

If the messages parameter is not provided or set to false, the messages field will not be included in the response.

curl -X GET '{API_BASE_URL}/v1/public/issues/1001?messages=true' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

The messages key is added to the Issue response. For the rest of that response, see Retrieving Issues.

Message object

Each message in the messages array contains the following structure.

Field	Type	Description
`id`	Number	Unique identifier for the message.
`status`	String	Message status: `"draft"`, `"new"`, or `"seen"`.
`reply`	Boolean	Indicates if this is a reply message (`true`) or original message (`false`).
`createdAt`	String	Timestamp when the message was created.
`updatedAt`	String	Timestamp when the message was last updated.
`sentAt`	String	Timestamp when the message was sent.
`seenAt`	String or null	Timestamp when the message was seen. Null if not seen.
`user`	String	Name of the user who sent the message.
`items`	Array	Array of message items, the content in different languages and versions.

Message item object

Each item in the items array represents a version or translation of the message content.

Field	Type	Description
`id`	Number	Unique identifier for the message item.
`version`	String	Version type: `"original"`, `"machine"`, or `"human"`.
`type`	String	Content type: `"text"`, `"questions"`, or `"conversation"`.
`messageId`	Number	Reference to the parent message ID.
`languageId`	Number	Numeric identifier for the language.
`createdAt`	String	Timestamp when this item was created.
`value`	String or Array	The actual content. String for text, array for questions and conversation.
`language`	String	Human-readable language name, for example English, Hindi, or Kannada.

Version types

original: The original message content as created by the user
machine: Translation done by machine
human: Translation done by a human

Content types

text: Standard text message content
questions: Array of questions, exclusive for AI Agent Sienna Reports
conversation: Conversation transcript with speaker turns, exclusive for AI Agent Sienna Reports

Response scenarios

The following sections document the message response scenarios you may encounter. Each example shows the messages array only. It appears alongside the other Issue fields in the full response.

Simple text message

A basic message with original content in a single language, no translations.

"messages": [
  {
    "id": 1,
    "status": "seen",
    "reply": false,
    "createdAt": "2025-11-12T08:52:01.102Z",
    "updatedAt": "2025-11-12T08:58:05.076Z",
    "sentAt": "2025-11-12T08:56:42.899Z",
    "seenAt": "2025-11-12T08:58:05.083Z",
    "user": "Reporter",
    "items": [
      {
        "id": 1,
        "version": "original",
        "type": "text",
        "messageId": 1,
        "languageId": 18,
        "createdAt": "2025-11-12T08:56:41.794Z",
        "value": "I need to report a security incident that occurred yesterday.",
        "language": "English"
      }
    ]
  }
]

Text message with machine translation

A message with original content and an automatically generated translation.

"messages": [
  {
    "id": 2,
    "status": "seen",
    "reply": false,
    "createdAt": "2025-11-12T09:03:16.127Z",
    "updatedAt": "2025-11-12T09:03:41.330Z",
    "sentAt": "2025-11-12T09:03:26.065Z",
    "seenAt": "2025-11-12T09:03:41.335Z",
    "user": "Jane Smith",
    "items": [
      {
        "id": 8,
        "version": "machine",
        "type": "text",
        "messageId": 2,
        "languageId": 18,
        "createdAt": "2025-11-12T09:03:26.589Z",
        "value": "This is a test message in a non-English language.",
        "language": "English"
      },
      {
        "id": 7,
        "version": "original",
        "type": "text",
        "messageId": 2,
        "languageId": 31,
        "createdAt": "2025-11-12T09:03:25.381Z",
        "value": "यह एक गैर-अंग्रेजी भाषा में परीक्षण संदेश है।",
        "language": "Hindi"
      }
    ]
  }
]

In this example the machine translation precedes the original. Match on version rather than array position.

Text message with human translation

A message with original content and a human-reviewed translation.

"messages": [
  {
    "id": 3,
    "status": "seen",
    "reply": true,
    "createdAt": "2025-11-12T09:05:43.509Z",
    "updatedAt": "2025-11-12T09:08:51.002Z",
    "sentAt": "2025-11-12T09:05:59.481Z",
    "seenAt": "2025-11-12T09:08:51.008Z",
    "user": "Reporter",
    "items": [
      {
        "id": 16,
        "version": "original",
        "type": "text",
        "messageId": 3,
        "languageId": 31,
        "createdAt": "2025-11-12T09:05:44.010Z",
        "value": "यह हमारे कार्यालय में घटना के बारे में एक रिपोर्ट है।",
        "language": "Hindi"
      },
      {
        "id": 17,
        "version": "human",
        "type": "text",
        "messageId": 3,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:36.001Z",
        "value": "This is a report about an incident in our office.",
        "language": "English"
      }
    ]
  }
]

Message with original, machine, and human translations

A reporter message that contains all three translation versions. This scenario occurs when Channel settings prefer machine translation, but a human-reviewed translation is also available. The original message is in Hindi, with both machine and human translations in English.

"messages": [
  {
    "id": 4,
    "status": "seen",
    "reply": false,
    "createdAt": "2025-11-12T09:05:43.509Z",
    "updatedAt": "2025-11-12T09:08:51.002Z",
    "sentAt": "2025-11-12T09:05:59.481Z",
    "seenAt": "2025-11-12T09:08:51.008Z",
    "user": "Reporter",
    "items": [
      {
        "id": 16,
        "version": "original",
        "type": "text",
        "messageId": 4,
        "languageId": 31,
        "createdAt": "2025-11-12T09:05:44.010Z",
        "value": "मुझे एक घटना की रिपोर्ट करनी है जो कल हुई थी।",
        "language": "Hindi"
      },
      {
        "id": 17,
        "version": "machine",
        "type": "text",
        "messageId": 4,
        "languageId": 18,
        "createdAt": "2025-11-12T09:05:50.001Z",
        "value": "I need to report an incident that happened yesterday.",
        "language": "English"
      },
      {
        "id": 18,
        "version": "human",
        "type": "text",
        "messageId": 4,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:36.001Z",
        "value": "I need to report an incident that occurred yesterday.",
        "language": "English"
      }
    ]
  }
]

New message, unseen

A message that has been sent but not yet seen by the recipient. seenAt is null.

"messages": [
  {
    "id": 5,
    "status": "new",
    "reply": false,
    "createdAt": "2025-11-12T08:58:57.114Z",
    "updatedAt": "2025-11-12T08:59:07.206Z",
    "sentAt": "2025-11-12T08:59:07.213Z",
    "seenAt": null,
    "user": "Reporter",
    "items": [
      {
        "id": 3,
        "version": "original",
        "type": "text",
        "messageId": 5,
        "languageId": 18,
        "createdAt": "2025-11-12T08:59:06.508Z",
        "value": "I have additional information to share.",
        "language": "English"
      }
    ]
  }
]

Message with questions

A message that includes questions for the reporter to answer. The questions arrive as a separate item with type set to "questions", alongside the text item.

"messages": [
  {
    "id": 7,
    "status": "seen",
    "reply": true,
    "createdAt": "2025-11-12T09:08:55.957Z",
    "updatedAt": "2025-11-12T09:11:31.724Z",
    "sentAt": "2025-11-12T09:09:10.241Z",
    "seenAt": "2025-11-12T09:11:31.729Z",
    "user": "James Davis",
    "items": [
      {
        "id": 37,
        "version": "original",
        "type": "text",
        "messageId": 7,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:56.743Z",
        "value": "We need some additional information to proceed with your case.",
        "language": "English"
      },
      {
        "id": 35,
        "version": "original",
        "type": "questions",
        "messageId": 7,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:56.566Z",
        "value": [
          "Who do you suspect was involved in this incident?"
        ],
        "language": "English"
      },
      {
        "id": 44,
        "version": "machine",
        "type": "questions",
        "messageId": 7,
        "languageId": 37,
        "createdAt": "2025-11-12T09:09:10.575Z",
        "value": [
          "ಈ ಘಟನೆಯಲ್ಲಿ ಯಾರು ಭಾಗವಹಿಸಿದ್ದಾರೆ ಎಂದು ನೀವು ಅನುಮಾನಿಸುತ್ತೀರಿ?"
        ],
        "language": "Kannada"
      }
    ]
  }
]

Message with multiple questions

A message containing multiple questions in the questions array. Note that the accompanying text item can have an empty value.

"messages": [
  {
    "id": 8,
    "status": "seen",
    "reply": true,
    "createdAt": "2025-11-12T09:08:55.991Z",
    "updatedAt": "2025-11-12T09:15:21.307Z",
    "sentAt": "2025-11-12T09:11:31.362Z",
    "seenAt": "2025-11-12T09:15:21.310Z",
    "user": "Michael Miller",
    "items": [
      {
        "id": 42,
        "version": "original",
        "type": "questions",
        "messageId": 8,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:59.763Z",
        "value": [
          "Tell us which place",
          "Tell us which color",
          "Tell us which shape",
          "Tell us which number",
          "Tell us new names"
        ],
        "language": "English"
      },
      {
        "id": 36,
        "version": "original",
        "type": "text",
        "messageId": 8,
        "languageId": 18,
        "createdAt": "2025-11-12T09:08:56.695Z",
        "value": "",
        "language": "English"
      }
    ]
  }
]

Message with a conversation transcript

A message containing a conversation transcript with speaker turns and translations. Each turn is an object rather than a string.

"messages": [
  {
    "id": 9,
    "status": "seen",
    "reply": false,
    "createdAt": "2025-11-12T09:17:50.089Z",
    "updatedAt": "2025-11-12T05:06:14.543Z",
    "sentAt": "2025-11-12T09:17:57.322Z",
    "seenAt": "2025-11-12T05:06:14.550Z",
    "user": "Reporter",
    "items": [
      {
        "id": 26,
        "version": "original",
        "type": "conversation",
        "messageId": 9,
        "languageId": 37,
        "createdAt": "2025-11-12T09:17:56.372Z",
        "value": [
          {
            "speaker": "Sienna Agent",
            "text": "ಸ್ಪೀಕ್ ಅಪ್‌ಗೆ ಸ್ವಾಗತ. ನಾನು ಹೇಗೆ ಸಹಾಯ ಮಾಡಬಹುದು?",
            "translation": "Welcome to Speak Up. How can I help you?"
          },
          {
            "speaker": "Reporter",
            "text": "ನನಗೆ ಒಂದು ಘಟನೆಯನ್ನು ವರದಿ ಮಾಡಬೇಕಾಗಿದೆ.",
            "translation": "I need to report an incident."
          },
          {
            "speaker": "Sienna Agent",
            "text": "ಈ ಘಟನೆ ಯಾವಾಗ ನಡೆದಿದೆ? ದಯವಿಟ್ಟು ದಿನಾಂಕ ಮತ್ತು ಸಮಯವನ್ನು ನೀಡಿ.",
            "translation": "When did this incident occur? Please provide the date and time."
          }
        ],
        "language": "Kannada"
      }
    ]
  }
]

Conversation with transcription not available

A conversation message where transcription is not available for some turns. Both text and translation carry the literal string Transcription not available.

"messages": [
  {
    "id": 10,
    "status": "seen",
    "reply": false,
    "createdAt": "2025-11-12T09:43:34.485Z",
    "updatedAt": "2025-11-12T09:43:59.358Z",
    "sentAt": "2025-11-12T09:43:38.538Z",
    "seenAt": "2025-11-12T09:43:59.364Z",
    "user": "Reporter",
    "items": [
      {
        "id": 20,
        "version": "original",
        "type": "conversation",
        "messageId": 10,
        "languageId": 37,
        "createdAt": "2025-11-12T09:43:37.661Z",
        "value": [
          {
            "speaker": "Sienna Agent",
            "text": "Welcome to Speak Up. How can I help?",
            "translation": "Welcome to Speak Up. How can I help?"
          },
          {
            "speaker": "Sienna Agent",
            "text": "Transcription not available",
            "translation": "Transcription not available"
          }
        ],
        "language": "Kannada"
      }
    ]
  }
]

Multiple messages in a thread

A complete message thread showing multiple messages in chronological order. reply distinguishes handler replies from reporter messages.

"messages": [
  {
    "id": 13,
    "status": "seen",
    "reply": false,
    "sentAt": "2025-11-12T08:56:42.899Z",
    "seenAt": "2025-11-12T08:58:05.083Z",
    "user": "John Doe",
    "items": [
      {
        "id": 1,
        "version": "original",
        "type": "text",
        "messageId": 13,
        "languageId": 18,
        "value": "I need to report an incident.",
        "language": "English"
      }
    ]
  },
  {
    "id": 14,
    "status": "seen",
    "reply": true,
    "sentAt": "2025-11-12T08:58:16.844Z",
    "seenAt": "2025-11-12T08:58:50.684Z",
    "user": "David Johnson",
    "items": [
      {
        "id": 2,
        "version": "original",
        "type": "text",
        "messageId": 14,
        "languageId": 18,
        "value": "Thank you for your report. We will investigate.",
        "language": "English"
      }
    ]
  },
  {
    "id": 15,
    "status": "new",
    "reply": false,
    "sentAt": "2025-11-12T08:59:07.213Z",
    "seenAt": null,
    "user": "John Doe",
    "items": [
      {
        "id": 3,
        "version": "original",
        "type": "text",
        "messageId": 15,
        "languageId": 18,
        "value": "I have additional information.",
        "language": "English"
      }
    ]
  }
]

Data models reference

Message status values

Value	Description
`"seen"`	Message has been viewed by the recipient.
`"new"`	Message has been sent but not yet viewed.
`"draft"`	Message has been composed but not sent.

Version types

Value	Description
`"original"`	The original message content as created by the user.
`"machine"`	Translation done by machine.
`"human"`	Translation done by a human.

Content types

Value	Description	Value format
`"text"`	Standard text content.	String
`"questions"`	Array of questions.	Array of strings, can be empty
`"conversation"`	Conversation transcript.	Array of conversation turn objects

Conversation turn object

When type is "conversation", the value field contains an array of conversation turn objects.

Field	Type	Description
`speaker`	String	Speaker identifier, for example Sienna Agent or Reporter.
`text`	String	The spoken text in the original language.
`translation`	String	English translation of the text, if applicable.

Errors

This parameter is part of the get Issue endpoint, so the same errors apply. See Retrieving Issues and the API error reference.

Retrieving messages

Query parameter

Message object

Message item object

Version types

Content types

Response scenarios

Simple text message

Text message with machine translation

Text message with human translation

Message with original, machine, and human translations

New message, unseen

Message with questions

Message with multiple questions

Message with a conversation transcript

Conversation with transcription not available

Multiple messages in a thread

Data models reference

Message status values

Version types

Content types

Conversation turn object

Errors

Related