List messages

API reference

List messages

Request

This operation lists all messages sent or received via particular Processing Modes.

Setting the messages_source parameter to CONVERSATION_SOURCE allows for querying messages in CONVERSATION mode, and setting it to DISPATCH_SOURCE will allow for queries of messages in DISPATCH mode. Note that conversation_id and contact_id are only supported as query parameters if messages_source is set to CONVERSATION_SOURCE.

Combining multiple parameters is supported for more detailed filtering of messages, but some of them are not supported depending on the value specified for messages_source. The description for each field will inform if that field may not be supported.

The messages are ordered by their accept_time property in descending order, where accept_time is a timestamp of when the message was enqueued by the Conversation API. This means messages received most recently will be listed first.

Security

Basic or oAuth2

Path

project_idstringrequired

The unique ID of the project. You can find this on the Sinch Dashboard.

Query

conversation_idstring

Resource name (ID) of the conversation.

contact_idstring

Resource name (ID) of the contact.

app_idstring

Id of the app.

channel_identitystring

Channel identity of the contact.

start_timestring, (date-time)

Filter messages with accept_time after this timestamp. Must be before end_time if that is specified.

end_timestring, (date-time)

Filter messages with accept_time before this timestamp.

page_sizeinteger, (int32)

Maximum number of messages to fetch. Defaults to 10 and the maximum is 1000.

page_tokenstring

Next page token previously returned if any. When specifying this token, make sure to use the same values for the other parameters from the request that originated the token, otherwise the paged results may be inconsistent.

viewstring(ConversationMessagesView)

Default:"WITH_METADATA"

Enum Value	Description
WITH_METADATA	View the message with metadata.
WITHOUT_METADATA	View the message without metadata.

messages_sourcestring(MessageSource)

Specifies the message source for which the request will be processed. Used for operations on messages in Dispatch Mode. For more information, see Processing Modes.

Default:"CONVERSATION_SOURCE"

Enum Value	Description
CONVERSATION_SOURCE	The default messages source. Retrieves messages sent in the `CONVERSATION` processing mode, which associates the messages with a specific conversation and contact.
DISPATCH_SOURCE	Retrieves messages sent in the `DISPATCH` processing mode. These types of messages are not associated with any conversation or contact.

only_recipient_originatedboolean

If true, fetch only recipient originated messages.

channelstring(Channel Identifier)

Only fetch messages from the channel.

Enum Value	Description
SMS	The SMS channel.
RCS	The RCS channel.
WHATSAPP	The WhatsApp channel.
MMS	The MMS channel.
KAKAOTALK	The KakaoTalk channel.
KAKAOTALKCHAT	The KakaoTalk chat channel (used primarily in ConsultationTalk).
VIBERBM	The Viber Business Messages channel.
LINE	The LINE channel.
INSTAGRAM	The Instagram channel.
MESSENGER	The Facebook Messenger channel.
WECHAT	The WeChat channel.
TELEGRAM	The Telegram channel.
APPLEBC	The Apple Messages for Business channel.

Example:channel=WHATSAPP

directionstring(ConversationDirection)

Optional. Only fetch messages with the specified direction. If direction is not specified, it will list both TO_APP and TO_CONTACT messages.

Enum Value	Description
TO_APP	Sent to the Conversation API app.
TO_CONTACT	Sent to a recipient/contact from the Conversation API app.

curl -i -X GET \
  -u '<username>:<password>' \
  'https://us.conversation.api.sinch.com/v1/projects/{project_id}/messages?conversation_id=string&contact_id=string&app_id=string&channel_identity=string&start_time=2019-08-24T14%3A15%3A22Z&end_time=2019-08-24T14%3A15%3A22Z&page_size=0&page_token=string&view=WITH_METADATA&messages_source=CONVERSATION_SOURCE&only_recipient_originated=true&channel=WHATSAPP&direction=TO_APP'

Responses

A successful response.

Bodyapplication/json

messagesArray of objects(Conversation Message)read-only

List of messages associated to the referenced conversation.

next_page_tokenstring

Token that should be included in the next request to fetch the next page.

Response

{
  "messages": [
    { … }
  ],
  "next_page_token": "string"
}

We'd love to hear from you!