Message: response / conversations (app -> client)

Back to overview

Return the list of conversations.

This message MUST be sent by the app in case the list of conversations has been requested by the client.

Acknowledgement

This message acknowledges:

Message Condition Error Codes
request/conversations (client -> app)

(None)
Name Description
internalError

An internal error occurred

Args

None

Data

The data value is an Array<Conversation>.

Models

Conversation

Field Description Type Optional Nullable Default
type

The receiver type

Allowed values: "me", "contact", "group", "distributionList"

String False False
id

The identity of the responder

 String False False
position

The index of the message (for sorting purposes)

 Integer False False
messageCount

Number of messages

 Integer False False
unreadCount

Number of unread messages

 Integer False False
latestMessage

The latest message's content

 Map<Message> True False
receiver

The receiver

 Map<Receiver> True False
avatar

The avatar of the receiver. Only set for the top 20-30 conversations.

 Binary True False
notifications

Notification settings

 Map<NotificationSettings> True False
isStarred

Whether the conversation is starred

 Boolean True False False
isUnread

Whether the conversation was explicitly marked as unread.

Note that a non-zero unreadCount always takes precedence over this flag.

 Boolean True False False

Message

Field Description Type Optional Nullable Default
type

The message type

Allowed values: "text", "image", "video", "audio", "file", "location", "contact", "status", "voipStatus", "ballot"

String False False
id

The message id

 String False False
body

The message body

 String True False
thumbnail

The message thumbnail

 Map<Thumbnail> True False
date

The message's date (last modification) as a unix timestamp in seconds

 Integer True False
events

A list of message events

 Array<MessageEvent> True False
sortKey

A number used for sorting messages, higher means newer, may not be negative

 Integer False False
partnerId

The identity of the sender of this message

 String True False
isOutbox

Whether this message was sent by the user

 Boolean False False
isStatus

Whether this is a status message

 Boolean False False
statusType

The status message type

Allowed values: "text", "firstUnreadMessage"

String True False
caption

The message caption

 String True False
unread

Whether this message is unread

 Boolean True False False
state

The message state

  • "pending": Message created and stored in the app's database. No attempt to deliver the message to the chat server has been made, yet.
  • "sending": Message created and stored in the app's database. The app now attempts to deliver the message to the chat server.
  • "send-failed": The message could not be delivered to the server. User action is required for retrying.
  • "sent": Associated blobs have been uploaded and the message has been delivered to the chat server.
  • "delivered": The messsage has been received by the recipient.
  • "read": Message has been read by the recipient.
  • "user-ack": Message has been acknowledged by the recipient.
  • "user-dec": Message has been declined by the recipient.

Allowed values: "pending", "sending", "send-failed", "sent", "delivered", "read", "user-ack", "user-dec"

String True False
lastEditedAt

Unix timestamp in milliseconds of the last edit, or undefined if this message was not edited

 Integer True False
quote

The message quote

 Map<Quote> True False
file

The file info

 Map<File> True False
video

The video info

 Map<Video> True False
audio

The audio info

 Map<Audio> True False
location

The location info

 Map<Location> True False
voip

The voip status info

 Map<VoIP> True False

Thumbnail

Field Description Type Optional Nullable Default
height

The height of the thumbnail (max 350px)

 Integer False False
width

The width of the thumbnail (max 350px)

 Integer False False
preview

The thumbnail preview. This should be resized so that no side is larger than 50px.

 Binary False False

MessageEvent

Field Description Type Optional Nullable Default
date

The event date (last modification) as a unix time stamp in seconds

 Integer False False
type

The event type

  • "created": Message created and stored in the app's database.
  • "sent": Associated blobs have been uploaded and the message has been delivered to the chat server.
  • "delivered": Messsage has been received by the recipient.
  • "read": Message has been read by the recipient.
  • "acked": Message has been acknowledged or declined by the recipient.
  • "modified": Most recent date the message has been modified.

Allowed values: "created", "sent", "delivered", "read", "acked", "modified"

String False False

Quote

Field Description Type Optional Nullable Default
identity

The quote author's identity

 String False False
text

The quote text

 String False False
messageId

The message id of the quoted message

 String True False

File

Field Description Type Optional Nullable Default
name

The file name

 String False False
size

The file size in bytes

 Integer False False
type

The file MIME type

 String False False
inApp

TODO

 Boolean False False

Video

Field Description Type Optional Nullable Default
duration

The video duration in seconds

 Integer False False
size

The video file size in bytes

 Integer True False

Audio

Field Description Type Optional Nullable Default
duration

The duration of the audio message in seconds

 Integer False False

Location

Field Description Type Optional Nullable Default
lat

WSG84 latitude

 Float False False
lon

WSG84 longitude

 Float False False
accuracy

The horizontal accuracy in meters (the radius of 68% confidence)

 Float False False
address

The address belonging to this location

 String True False
description

Description text for this location

 String False False

VoIP

Field Description Type Optional Nullable Default
status

The type of VoIP status message

  • 1: Missed
  • 2: Finished
  • 3: Rejected
  • 4: Aborted

Allowed values: 1, 2, 3, 4

Integer False False
duration

The duration of the call in seconds

 Integer True False
reason

The reject reason

  • 0: Unknown
  • 1: Busy
  • 2: Timeout
  • 3: Rejected

Allowed values: 0, 1, 2, 3

Integer True False

NotificationSettings

Field Description Type Optional Nullable Default
sound

Notification sound settings

 Map<NotificationSound> False False
dnd

Do not disturb settings

 Map<NotificationDnd> False False

NotificationSound

Field Description Type Optional Nullable Default
mode

The notification mode

Allowed values: "default", "muted"

String False False

NotificationDnd

Field Description Type Optional Nullable Default
mode

The do not disturb mode

Allowed values: "off", "on", "until"

String False False
mentionsOnly

Only notify on mentions. May be used with modes "on" or "until"

Allowed values: "off", "on", "until"

String True False False
until

Unix timestamp in milliseconds. Must be set if mode is "until"

 Integer True False