Datahose - Read Events

Creates and reads a real time feed of messages & events. The datahose API provides messages and events from all conversations in the pod, even the ones the service user is not part of. The types of events surfaced can be found in the Real Time Events list.

Add-on: The Datahose API is an add-on to the Symphony Services, and is subject to additional charges. Prior to using Datahose in your Symphony environment(s), you will need to enter into a specific contract. Please reach out to [e-mail] to discuss the offering, its pricing or for any further information.

Creates and Reads a real time feed of messages and events of your pod (Datahose)

post

Available on Agent 22.6 and above.

This API provides a real time feed of all the messages and events in the pod, even from conversations where the calling service user is not a member. The types of events surfaced can be found in the Real Time Events list. In case you retrieving SOCIALMESSAGE events, the credentials of the ceservice account must be properly configured in the Agent.

The types of events returned can be found in the Real Time Events list (see definition on top of the file).

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.

If you have several instances of the same bot, they must share the same feed so that events are spread across all bot instances. To do so, you must: share the same service account provide the same "tag" and same "filters" values.

The Datahose API is an add-on to the Symphony Services, and is subject to additional charges. Prior to using Datahose in your Symphony environment(s), you will need to enter into a specific contract.

Header parameters

sessionTokenstringRequired

Session authentication token.

keyManagerTokenstringRequired

Key Manager authentication token.

Body

typestringRequired

The type of feed. Only allowed value is "datahose".

tagstring · min: 1 · max: 80Required

A unique identifier to ensure uniqueness of the datafeed.

eventTypesstring[]Optional

At least one value is required. Values must be valid Real-Time Events, i.e. one of:

• MESSAGESENT
• MESSAGESUPPRESSED
• SYMPHONYELEMENTSACTION
• SHAREDPOST
• INSTANTMESSAGECREATED
• ROOMCREATED
• ROOMUPDATED
• ROOMDEACTIVATED
• ROOMREACTIVATED
• USERREQUESTEDTOJOINROOM
• USERJOINEDROOM
• USERLEFTROOM
• ROOMMEMBERPROMOTEDTOOWNER
• ROOMMEMBERDEMOTEDFROMOWNER
• CONNECTIONREQUESTED
• CONNECTIONACCEPTED

ackIdstringOptional

Should be empty for the first call, acknowledges that the current batch of messages have been successfully received by the client.

updatePresencebooleanOptional

Whether to update the presence status of the account to AVAILABLE when calling the endpoint. Default value is true.

Default: true

Responses

200

Datafeed successfully read.

application/json

400

Bad request.

application/json

401

Unauthorized.

application/json

403

Forbidden.

application/json

500

Internal server error.

application/json

post

HTTPcURLJavaScriptPython

POST /agent/v5/events/read HTTP/1.1
Host: youragentURL.symphony.com
sessionToken: text
keyManagerToken: text
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "type": "datahose",
  "tag": "mybotusername",
  "eventTypes": [
    "MESSAGE_SENT"
  ],
  "updatePresence": false
}

{
  "events": [
    {
      "id": "text",
      "messageId": "text",
      "timestamp": 1,
      "type": "text",
      "diagnostic": "text",
      "initiator": {
        "user": {
          "userId": 1,
          "firstName": "text",
          "lastName": "text",
          "displayName": "text",
          "email": "text",
          "username": "text"
        }
      },
      "payload": {
        "messageSent": {
          "message": {
            "messageId": "text",
            "parentMessageId": "text",
            "timestamp": 1,
            "message": "text",
            "sharedMessage": "[Circular Reference]",
            "data": "text",
            "attachments": [
              {
                "id": "text",
                "name": "text",
                "size": 1,
                "images": [
                  {
                    "id": "text",
                    "dimension": "text"
                  }
                ]
              }
            ],
            "user": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "stream": {
              "streamId": "text",
              "streamType": "text",
              "roomName": "text",
              "members": [
                {
                  "userId": 1,
                  "firstName": "text",
                  "lastName": "text",
                  "displayName": "text",
                  "email": "text",
                  "username": "text"
                }
              ],
              "external": true,
              "crossPod": true,
              "recipientTenantIds": [
                1
              ]
            },
            "externalRecipients": true,
            "diagnostic": "text",
            "userAgent": "text",
            "originalFormat": "text",
            "disclaimer": "text",
            "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
            "replacing": "text",
            "replacedBy": "text",
            "initialTimestamp": 1,
            "initialMessageId": "text",
            "silent": true
          }
        },
        "sharedPost": {
          "message": {
            "messageId": "text",
            "parentMessageId": "text",
            "timestamp": 1,
            "message": "text",
            "sharedMessage": "[Circular Reference]",
            "data": "text",
            "attachments": [
              {
                "id": "text",
                "name": "text",
                "size": 1,
                "images": [
                  {
                    "id": "text",
                    "dimension": "text"
                  }
                ]
              }
            ],
            "user": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "stream": {
              "streamId": "text",
              "streamType": "text",
              "roomName": "text",
              "members": [
                {
                  "userId": 1,
                  "firstName": "text",
                  "lastName": "text",
                  "displayName": "text",
                  "email": "text",
                  "username": "text"
                }
              ],
              "external": true,
              "crossPod": true,
              "recipientTenantIds": [
                1
              ]
            },
            "externalRecipients": true,
            "diagnostic": "text",
            "userAgent": "text",
            "originalFormat": "text",
            "disclaimer": "text",
            "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
            "replacing": "text",
            "replacedBy": "text",
            "initialTimestamp": 1,
            "initialMessageId": "text",
            "silent": true
          },
          "sharedMessage": {
            "messageId": "text",
            "parentMessageId": "text",
            "timestamp": 1,
            "message": "text",
            "sharedMessage": "[Circular Reference]",
            "data": "text",
            "attachments": [
              {
                "id": "text",
                "name": "text",
                "size": 1,
                "images": [
                  {
                    "id": "text",
                    "dimension": "text"
                  }
                ]
              }
            ],
            "user": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "stream": {
              "streamId": "text",
              "streamType": "text",
              "roomName": "text",
              "members": [
                {
                  "userId": 1,
                  "firstName": "text",
                  "lastName": "text",
                  "displayName": "text",
                  "email": "text",
                  "username": "text"
                }
              ],
              "external": true,
              "crossPod": true,
              "recipientTenantIds": [
                1
              ]
            },
            "externalRecipients": true,
            "diagnostic": "text",
            "userAgent": "text",
            "originalFormat": "text",
            "disclaimer": "text",
            "sid": "fa691cd3-484a-4109-aeb2-57c05b78c95b",
            "replacing": "text",
            "replacedBy": "text",
            "initialTimestamp": 1,
            "initialMessageId": "text",
            "silent": true
          }
        },
        "instantMessageCreated": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          }
        },
        "roomCreated": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "roomProperties": {
            "name": "text",
            "description": "text",
            "creatorUser": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "createdDate": 1,
            "external": true,
            "crossPod": true,
            "public": true,
            "copyProtected": true,
            "readOnly": true,
            "discoverable": true,
            "membersCanInvite": true,
            "keywords": [
              {
                "key": "text",
                "value": "text"
              }
            ],
            "canViewHistory": true
          }
        },
        "roomUpdated": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "newRoomProperties": {
            "name": "text",
            "description": "text",
            "creatorUser": {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            },
            "createdDate": 1,
            "external": true,
            "crossPod": true,
            "public": true,
            "copyProtected": true,
            "readOnly": true,
            "discoverable": true,
            "membersCanInvite": true,
            "keywords": [
              {
                "key": "text",
                "value": "text"
              }
            ],
            "canViewHistory": true
          }
        },
        "roomDeactivated": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          }
        },
        "roomReactivated": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          }
        },
        "userJoinedRoom": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "affectedUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "userLeftRoom": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "affectedUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "roomMemberPromotedToOwner": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "affectedUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "roomMemberDemotedFromOwner": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "affectedUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "connectionRequested": {
          "toUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "connectionAccepted": {
          "fromUser": {
            "userId": 1,
            "firstName": "text",
            "lastName": "text",
            "displayName": "text",
            "email": "text",
            "username": "text"
          }
        },
        "messageSuppressed": {
          "messageId": "text",
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          }
        },
        "symphonyElementsAction": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "formMessageId": "text",
          "formId": "text",
          "formValues": {}
        },
        "userRequestedToJoinRoom": {
          "stream": {
            "streamId": "text",
            "streamType": "text",
            "roomName": "text",
            "members": [
              {
                "userId": 1,
                "firstName": "text",
                "lastName": "text",
                "displayName": "text",
                "email": "text",
                "username": "text"
              }
            ],
            "external": true,
            "crossPod": true,
            "recipientTenantIds": [
              1
            ]
          },
          "affectedUsers": [
            {
              "userId": 1,
              "firstName": "text",
              "lastName": "text",
              "displayName": "text",
              "email": "text",
              "username": "text"
            }
          ]
        }
      }
    }
  ],
  "ackId": "text"
}

Requirements

The Agent v22.6 (release date: June 2022) is required.

Entitlements

The service account needs to have both the Can read from datahose feeds and Can create datahose feeds entitlements enabled to call this endpoint.

Please contact your Technical Account Manager or Symphony representative to get your chat Bot entitled.

Configuration

The credentials of the Content Export service need to be setup in the Agent configuration for datahose to work.

The description of the configuration fields for the Content Export service is available in the Agent configuration guide (look for agent.privatekey.ceservice and agent.certificate.ceservice).

To check that the Content Export is correctly setup, you can test the Agent health check extended endpoint (/agent /v3/health/extended).

The value of users.ceservice.status should be "UP", see example below.

{
    "services": {
        "datafeed": {
            "status": "UP",
            "version": "2.11.2"
        },
        "key_manager": {
            "status": "UP",
            "version": "20.16.3"
        },
        "pod": {
            "status": "UP",
            "version": "20.16.74-216-100b3be"
        }
    },
    "status": "UP",
    "users": {
        "agentservice": {
            "authType": "RSA",
            "status": "UP"
        },
        "ceservice": {
            "authType": "RSA",
           
        }
    },
    "version": "23.11.1-716"
}

Using ackId

The endpoint returns the Real Time Events happening in the pod, either since the time the datahose feed was created or since the previous feed was read by the bot. The ackId has an essential role in retrieving the right events for the bot.

The ackId must be null or empty for the first call. Then, for subsequent requests, the ackId from the previous payload should be reused to confirm the reading of previous events already retrieved by the bot. Please note that you can very easily access this API via our BDKs in Java and Python.

If a batch of messages is not confirmed by sending the ackId, the messages that are there will be returned in the subsequent readings and may blend into the newer messages.

Fair use policy

Datahose API is subject to a fair use policy of 5 active feeds.

If your integration or workflow requires more than 5 feeds active at the same time, please contact Symphony.