# Read Datafeed

Reads the specified datafeed. The datafeed provides messages and events from all conversations that the user is in. The types of events surfaced in the datafeed can be found in the [Real Time Events](https://docs.developers.symphony.com/building-bots-on-symphony/datafeed/real-time-events) list.

{% hint style="warning" %}
**Backward compatibility breaking notice**: Starting in May 2025, the `ackId` parameter must be either set to an empty string or omitted for the first Datafeed Read call.
{% endhint %}

## Read the specified real time message / event stream ("datafeed").

> \_Available on Agent 2.57.0 and above.\_\
> \
> The datafeed provides messages and events from all conversations that the user\
> is in. The types of events surfaced in the datafeed can be found in the Real Time Events list.\
> (see definition on top of the file)\
> \
> Read the specified datafeed.\
> \
> The ackId sent as parameter can be empty for the first call. In the response an ackId will be sent back and it can be used for\
> the next call: in this way you acknowledge that you have received the events that came with that ackId; datafeed will remove the events\
> associated with that ackId from your queue<br>

```json
{"openapi":"3.0.1","info":{"title":"Agent API","version":"25.8.1"},"servers":[{"url":"youragentURL.symphony.com/agent"}],"paths":{"/v5/datafeeds/{datafeedId}/read":{"post":{"tags":["Datafeed"],"summary":"Read the specified real time message / event stream (\"datafeed\").","description":"_Available on Agent 2.57.0 and above._\n\nThe datafeed provides messages and events from all conversations that the user\nis in. The types of events surfaced in the datafeed can be found in the Real Time Events list.\n(see definition on top of the file)\n\nRead the specified datafeed.\n\nThe ackId sent as parameter can be empty for the first call. In the response an ackId will be sent back and it can be used for\nthe next call: in this way you acknowledge that you have received the events that came with that ackId; datafeed will remove the events\nassociated with that ackId from your queue\n","operationId":"readDatafeed","parameters":[{"name":"datafeedId","in":"path","description":"ID of the datafeed","required":true,"schema":{"type":"string"}},{"name":"sessionToken","in":"header","description":"Session authentication token.","required":true,"schema":{"type":"string"}},{"name":"keyManagerToken","in":"header","description":"Key Manager authentication token.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AckId"}}},"required":false},"responses":{"200":{"description":"Datafeed successfully read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V5EventList"}}}},"400":{"description":"Do not retry: the feed no longer exists, please create a new feed. The datafeed has a 30 minutes ttl. Alternatively, the format of the provided ackId may be incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"403":{"description":"Too many feeds created. This happens when you reached 20 active feeds. Usually, only one active feed is required per service account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}},"500":{"description":"Internal server error. Please retry reading the datafeed with an exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2Error"}}}}}}}},"components":{"schemas":{"AckId":{"type":"object","properties":{"ackId":{"type":"string","description":"A unique id for events that can be deleted from a client's.\nParameter must be omitted or set to empty string for the first read. For successive reads, must be set to the ackId received in the last Datafeed Read.\n"},"updatePresence":{"type":"boolean","description":"Set to false to avoid updating the user's presence when reading events. Default is true.","default":true}},"description":"An object containing the ackId (and parameters) associated with \nevents that the client has received through an individual feed.\n"},"V5EventList":{"type":"object","properties":{"events":{"type":"array","default":[],"items":{"$ref":"#/components/schemas/V4Event"}},"ackId":{"type":"string","description":"The ackId which acknowledges that the current batch of messages \nhave been successfully received by the client\n"}}},"V4Event":{"type":"object","properties":{"id":{"type":"string","description":"Event ID"},"messageId":{"type":"string","description":"Message ID"},"timestamp":{"type":"integer","description":"Timestamp of event","format":"int64"},"type":{"type":"string","description":"Event type, possible events are:\n  - MESSAGESENT\n  - SHAREDPOST\n  - INSTANTMESSAGECREATED\n  - ROOMCREATED\n  - ROOMUPDATED\n  - ROOMDEACTIVATED\n  - ROOMREACTIVATED\n  - USERJOINEDROOM\n  - USERLEFTROOM\n  - ROOMMEMBERPROMOTEDTOOWNER\n  - ROOMMEMBERDEMOTEDFROMOWNER\n  - CONNECTIONREQUESTED\n  - CONNECTIONACCEPTED\n  - MESSAGESUPPRESSED\n  - SYMPHONYELEMENTSACTION\n  - USERREQUESTEDTOJOINROOM\n  - GENERICSYSTEMEVENT\n"},"diagnostic":{"type":"string","description":"Details if event failed to parse for any reason.  The contents of this field may not be useful,\ndepending on the nature of the error. Only present when error occurs.\n"},"initiator":{"$ref":"#/components/schemas/V4Initiator"},"payload":{"$ref":"#/components/schemas/V4Payload"}}},"V4Initiator":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/V4User"}}},"V4User":{"type":"object","properties":{"userId":{"type":"integer","description":"Id of user","format":"int64"},"firstName":{"type":"string","description":"First name of user"},"lastName":{"type":"string","description":"Last name of user"},"displayName":{"type":"string","description":"User display name"},"email":{"type":"string","description":"Email of user"},"username":{"type":"string","description":"Applicable only to internal users"}}},"V4Payload":{"type":"object","properties":{"messageSent":{"$ref":"#/components/schemas/V4MessageSent"},"sharedPost":{"$ref":"#/components/schemas/V4SharedPost"},"instantMessageCreated":{"$ref":"#/components/schemas/V4InstantMessageCreated"},"roomCreated":{"$ref":"#/components/schemas/V4RoomCreated"},"roomUpdated":{"$ref":"#/components/schemas/V4RoomUpdated"},"roomDeactivated":{"$ref":"#/components/schemas/V4RoomDeactivated"},"roomReactivated":{"$ref":"#/components/schemas/V4RoomReactivated"},"userJoinedRoom":{"$ref":"#/components/schemas/V4UserJoinedRoom"},"userLeftRoom":{"$ref":"#/components/schemas/V4UserLeftRoom"},"roomMemberPromotedToOwner":{"$ref":"#/components/schemas/V4RoomMemberPromotedToOwner"},"roomMemberDemotedFromOwner":{"$ref":"#/components/schemas/V4RoomMemberDemotedFromOwner"},"connectionRequested":{"$ref":"#/components/schemas/V4ConnectionRequested"},"connectionAccepted":{"$ref":"#/components/schemas/V4ConnectionAccepted"},"messageSuppressed":{"$ref":"#/components/schemas/V4MessageSuppressed"},"symphonyElementsAction":{"$ref":"#/components/schemas/V4SymphonyElementsAction"},"userRequestedToJoinRoom":{"$ref":"#/components/schemas/V4UserRequestedToJoinRoom"},"genericSystemEvent":{"$ref":"#/components/schemas/V4GenericSystemEvent"}}},"V4MessageSent":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/V4Message"}}},"V4Message":{"type":"object","properties":{"messageId":{"type":"string","description":"Id of the message"},"parentMessageId":{"type":"string","description":"Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14."},"timestamp":{"type":"integer","description":"Timestamp of the message in milliseconds since Jan 1 1970","format":"int64"},"message":{"type":"string","description":"Message content in MessageMLV2","format":"MessageMLV2"},"sharedMessage":{"$ref":"#/components/schemas/V4Message"},"data":{"type":"string","description":"Message data in EntityJSON","format":"JSON"},"attachments":{"type":"array","default":[],"description":"Message attachments","items":{"$ref":"#/components/schemas/V4AttachmentInfo"}},"user":{"$ref":"#/components/schemas/V4User"},"stream":{"$ref":"#/components/schemas/V4Stream"},"externalRecipients":{"type":"boolean","description":"Indicates if the message have external recipients. Only present on real time messaging."},"diagnostic":{"type":"string","description":"Details if event failed to parse for any reason.  The contents of this field may not be useful,\ndepending on the nature of the error. Only present when error occurs.\n"},"userAgent":{"type":"string","description":"User agent string for client that sent the message.  Allows callers to identify which client sent the\norigin message (e.g. API Agent, SFE Client, mobile, etc)\n"},"originalFormat":{"type":"string","description":"Indicates the format in which the message was originally sent.  This could have been either:\n- com.symphony.markdown - Markdown OR Message ML V1\n- com.symphony.messageml.v2 - Message ML V2\n"},"disclaimer":{"type":"string","description":"Message that may be sent along with a regular message if configured for the POD,\nusually the first message sent in a room that day.\n"},"sid":{"type":"string","description":"Unique session identifier from where the message was created.\n"},"replacing":{"type":"string","description":"Id of the message that the current message is replacing (present only if set)"},"replacedBy":{"type":"string","description":"Id of the message that the current message is being replaced with (present only if set)"},"initialTimestamp":{"type":"integer","description":"Timestamp of when the initial message has been created in milliseconds since \nJan 1 1970 (present only if set)\n","format":"int64"},"initialMessageId":{"type":"string","description":"Id the the initial message that has been updated (present only if set)"},"silent":{"type":"boolean","description":"When false the user/s will receive the message update as unread (true by default)"}},"description":"A representation of a message sent by a user of Symphony"},"V4AttachmentInfo":{"required":["id","name","size","images"],"type":"object","properties":{"id":{"type":"string","description":"The attachment ID."},"name":{"type":"string","description":"The file name."},"size":{"type":"integer","description":"Size in bytes.","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/V4ThumbnailInfo"}}}},"V4ThumbnailInfo":{"type":"object","properties":{"id":{"type":"string","description":"The thumbnail ID."},"dimension":{"type":"string","description":"The thumbnail pixel size."}}},"V4Stream":{"type":"object","properties":{"streamId":{"type":"string","description":"Id of stream"},"streamType":{"type":"string","description":"Stream type, possible values are:\n  - IM\n  - MIM\n  - ROOM\n  - POST\n"},"roomName":{"type":"string","description":"Applicable only to rooms"},"members":{"type":"array","description":"Applicable only to IM Created","items":{"$ref":"#/components/schemas/V4User"}},"external":{"type":"boolean"},"crossPod":{"type":"boolean"},"recipientTenantIds":{"type":"array","description":"List of tenant identifiers (aka pod identifiers) involved in the conversation. It contains more than one\nitem if the conversation is external. Field is only present for real time messaging.\n","items":{"type":"integer","format":"int32"}}}},"V4SharedPost":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/V4Message"},"sharedMessage":{"$ref":"#/components/schemas/V4Message"}}},"V4InstantMessageCreated":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"}}},"V4RoomCreated":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"roomProperties":{"$ref":"#/components/schemas/V4RoomProperties"}}},"V4RoomProperties":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"creatorUser":{"$ref":"#/components/schemas/V4User"},"createdDate":{"type":"integer","description":"Timestamp","format":"int64"},"external":{"type":"boolean"},"crossPod":{"type":"boolean"},"public":{"type":"boolean"},"copyProtected":{"type":"boolean"},"readOnly":{"type":"boolean"},"discoverable":{"type":"boolean"},"membersCanInvite":{"type":"boolean"},"keywords":{"type":"array","default":[],"items":{"$ref":"#/components/schemas/V4KeyValuePair"}},"canViewHistory":{"type":"boolean"}}},"V4KeyValuePair":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}},"V4RoomUpdated":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"newRoomProperties":{"$ref":"#/components/schemas/V4RoomProperties"}}},"V4RoomDeactivated":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"}}},"V4RoomReactivated":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"}}},"V4UserJoinedRoom":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"affectedUser":{"$ref":"#/components/schemas/V4User"}}},"V4UserLeftRoom":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"affectedUser":{"$ref":"#/components/schemas/V4User"}}},"V4RoomMemberPromotedToOwner":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"affectedUser":{"$ref":"#/components/schemas/V4User"}}},"V4RoomMemberDemotedFromOwner":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"affectedUser":{"$ref":"#/components/schemas/V4User"}}},"V4ConnectionRequested":{"type":"object","properties":{"toUser":{"$ref":"#/components/schemas/V4User"}}},"V4ConnectionAccepted":{"type":"object","properties":{"fromUser":{"$ref":"#/components/schemas/V4User"}}},"V4MessageSuppressed":{"type":"object","properties":{"messageId":{"type":"string"},"stream":{"$ref":"#/components/schemas/V4Stream"}}},"V4SymphonyElementsAction":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"formMessageId":{"type":"string","description":"The id of the message that contains the Form"},"formId":{"type":"string","description":"The id of the Form element"},"formValues":{"type":"object","description":"The values (in JSON format) answered on the Form"}}},"V4UserRequestedToJoinRoom":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"affectedUsers":{"type":"array","description":"List of affected users by the action (i.e. owners of the room)","items":{"$ref":"#/components/schemas/V4User"}}}},"V4GenericSystemEvent":{"type":"object","properties":{"stream":{"$ref":"#/components/schemas/V4Stream"},"eventTimestamp":{"type":"integer","description":"The timestamp when the event was emitted","format":"int64"},"sourceSystem":{"type":"string","description":"The name of the system that emitted the event"},"eventSubtype":{"type":"string","description":"The identifier of the type of generic event"},"parameters":{"type":"object","description":"Free-form properties that provide context about the event","additionalProperties":true}}},"V2Error":{"required":["code","message"],"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"object"}}}}}}
```

{% hint style="info" %}
**ackId**: The `ackId` sent as a parameter **must** be either set to an empty string or omitted in the first call. In the response, an `ackId` will be sent back and it must be used for the next call. This way, you acknowledge that you have received the events that came with that `ackId` and that the datafeed will remove the events associated with that `ackId` from your queue. Events that have not been acknowledged will be re-queued and distributed again in a successive call.
{% endhint %}

{% hint style="warning" %}
**Datafeed ttl**: A datafeed time-to-live (ttl) is 30 minutes which means that, if your code doesn't poll the feed for 30 minutes, the feed will be deleted and your program will not receive queued messages. If your code attempts to read an expired or deleted feed, you will receive a 400 error code. Upon receiving a 400 error code, you need to create a new feed to continue to receive messages. Messages sent between the time the feed is deleted and you re-create a new one, will be lost.
{% endhint %}