The Symphony Agent API handles encryption and decryption of messages and content sent to and from bots. Provides message sending, datafeed (real-time event stream), signal management, DLP (Data Loss Prevention), and content sharing operations. Requires the on-premise Agent server to be deployed.
openapi: 3.0.1
info:
title: Symphony Agent API
description: |
This document refers to Symphony API calls to send and receive messages
and content. They need the on-premise Agent installed to perform
decryption/encryption of content.
- sessionToken and keyManagerToken can be obtained by calling the
authenticationAPI on the symphony back end and the key manager
respectively. Refer to the methods described in authenticatorAPI.yaml.
- Actions are defined to be atomic, ie will succeed in their entirety
or fail and have changed nothing.
- If it returns a 40X status then it will have sent no message to any
stream even if a request to some subset of the requested streams
would have succeeded.
- If this contract cannot be met for any reason then this is an error
and the response code will be 50X.
- MessageML is a markup language for messages. See reference here:
https://rest-api.symphony.com/docs/messagemlv2
- **Real Time Events**: The following events are returned when reading
from a real time messages and events stream ("datafeed"). These
events will be returned for datafeeds created with the v5 endpoints.
To know more about the endpoints, refer to Create Messages/Events
Stream and Read Messages/Events Stream. Unless otherwise specified,
all events were added in 1.46.
version: 22.9.1
servers:
- url: /
paths:
/v3/health:
get:
tags:
- Health
summary: Symphony Checks Health Status
description: >
_Available on Agent 2.57.0 and above._
Returns the connectivity status of your Agent server. If your Agent
server is started and running, the status value will be `UP`
operationId: v3Health
responses:
'200':
description: Agent application is alive.
content:
application/json:
schema:
$ref: '#/components/schemas/V3Health'
/v3/health/extended:
get:
tags:
- Health
summary: Symphony Checks Health Status of Services and Users
description: >
_Available on Agent 2.57.0 and above._
Returns the connectivity status of the Agent services (**pod**, **key
manager** and **datafeed**) as well as users
connectivity (**agentservice** and **ceservice**).
The global status will be set to `DOWN` if at least one of the
sub-status is also `DOWN`.
operationId: v3ExtendedHealth
responses:
'200':
description: Agent is healthy, all components are `UP`.
content:
application/json:
schema:
$ref: '#/components/schemas/V3Health'
'503':
description: Agent is unhealthy, some components are `DOWN`.
content:
application/json:
schema:
$ref: '#/components/schemas/V3Health'
/v4/message/import:
post:
tags:
- Message
summary: Import Messages From Other Systems Into Symphony
description: >
Sends a message to be imported into the system.
Allows you to override the timestamp and author of the message with your
desired values.
The requesting user must have the Content Management role.
The user that the message is intended to have come from must also be
present in the conversation.
The intended message timestamp must be a valid time from the past. It
cannot be a future timestamp.
Optionally the original message ID can be specified to identify the
imported message for the purpose of repeat imports.
parameters:
- name: sessionToken
in: header
description: Session authentication token.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/V4MessageImportList'
required: true
responses:
'200':
description: Message sent.
content:
application/json:
schema:
$ref: '#/components/schemas/V4ImportResponseList'
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
x-codegen-request-body-name: messageList
/v4/message/blast:
post:
tags:
- Message
summary: Symphony Post a Message to Multiple Existing Streams
description: >
Post a new message to the given list of streams. The stream can be a
chatroom,
an IM or a multiparty IM.
You may include an attachment on the message.
The message can be provided as MessageMLV2 or PresentationML. Both
formats support Freemarker templates.
The optional parameter "data" can be used to provide a JSON payload
containing entity data.
If the message contains explicit references to entity data (in
"data-entity-id" element attributes),
this parameter is required.
If the message is in MessageML and fails schema validation a client
error results
This endpoint is idempotent, it means that a 200 response will be
returned even if the message has not been
delivered to some streams. Check the `errors` map from the response in
order to see on which stream(s) the
message has not been delivered.
The maximum number of streams where the message can be sent is limitted
to 100.
Regarding authentication, you must either use the sessionToken which was
created for delegated app access
or both the sessionToken and keyManagerToken together.
parameters:
- name: sessionToken
in: header
description: Authorization token used to make delegated calls.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
required:
- sids
properties:
sids:
type: array
description: A comma-separated list of Stream IDs
items:
type: string
message:
type: string
description: The message payload in MessageML.
data:
type: string
description: Optional message data in EntityJSON.
version:
type: string
description: >
Optional message version in the format "major.minor". If
empty, defaults to the latest supported version.
attachment:
type: string
description: Optional file attachment.
format: binary
preview:
type: string
description: Optional attachment preview.
format: binary
responses:
'200':
description: Blast message sent.
content:
application/json:
schema:
$ref: '#/components/schemas/V4MessageBlastResponse'
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'451':
description: Compliance Issues found in message or file
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/v1/message/{id}:
get:
tags:
- Message
summary: Symphony Get a Message by ID
parameters:
- name: sessionToken
in: header
description: Session authentication token.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
required: true
schema:
type: string
- name: id
in: path
description: Message ID as a URL-safe string
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/V4Message'
'204':
description: No Messages.
content: {}
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/v1/message/search:
get:
tags:
- Message
summary: Symphony Search Messages
description: >
Search messages according to the specified criteria. The "query"
parameter takes a search query defined as
"field:value" pairs combined by the operator "AND" (e.g. "text:foo AND
autor:bar"). Supported fields are
(case-insensitive): "text", "author", "hashtag", "cashtag", "mention", "signal", "fromDate", "toDate",
"streamId", "streamType".
"text" search requires a "streamId" to be specified.
"streamType" accepts one of the following values: "chat" (IMs and MIMs), "im", "mim", "chatroom", "post".
"signal" queries can only be combined with "fromDate", "toDate", "skip" and "limit" parameters.
parameters:
- name: query
in: query
description: The search query. See above for the query syntax.
required: true
schema:
type: string
- name: skip
in: query
description: No. of results to skip.
schema:
type: integer
- name: limit
in: query
description: >-
Max no. of results to return. If no value is provided, 50 is the
default.
schema:
type: integer
- name: scope
in: query
description: |
Describes where content should be searched for that query.
It can exclusively apply to Symphony content or to one Connector.
schema:
type: string
- name: sortDir
in: query
description: |
Messages sort direction : ASC or DESC (default to DESC)
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.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/V4MessageList'
'204':
description: No Messages.
content: {}
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
post:
tags:
- Message
summary: Symphony Search Messages
description: Search messages according to the specified criteria.
parameters:
- name: skip
in: query
description: No. of results to skip.
schema:
type: integer
- name: limit
in: query
description: >-
Max no. of results to return. If no value is provided, 50 is the
default.
schema:
type: integer
- name: scope
in: query
description: |
Describes where content should be searched for that query.
It can exclusively apply to Symphony content or to one Connector.
schema:
type: string
- name: sortDir
in: query
description: |
Messages sort direction : ASC or DESC (default to DESC)
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.
required: true
schema:
type: string
requestBody:
description: The search query. See above for the query syntax.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageSearchQuery'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/V4MessageList'
'204':
description: No Messages.
content: {}
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
x-codegen-request-body-name: query
/v1/stream/{sid}/attachment:
get:
tags:
- Stream
summary: Symphony Download an Attachment
description: >-
Downloads the attachment body by the attachment ID, stream ID, and
message ID.
parameters:
- name: sid
in: path
description: Stream ID
required: true
schema:
type: string
- name: fileId
in: query
description: The attachment ID (Base64-encoded)
required: true
schema:
type: string
- name: messageId
in: query
description: The ID of the message containing the attachment
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.
required: true
schema:
type: string
responses:
'200':
description: Attachment body as Base64 encoded string.
content:
application/octet-stream:
schema:
type: string
format: byte
'400':
description: Client error, see response body for further details.
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Server error, see response body for further details.
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/Error'
/v4/stream/{sid}/message:
get:
tags:
- Stream
summary: Symphony Get Messages From an Existing Stream
description: |
A caller can fetch all unseen messages by passing the timestamp of
the last message seen as the since parameter and the number of messages
with the same timestamp value already seen as the skip parameter. This
means that every message will be seen exactly once even in the case that
an additional message is processed with the same timestamp as the last
message returned by the previous call, and the case where there are
more than maxMessages with the same timestamp value.
This method is intended for historic queries and is generally reliable
but if guaranteed delivery of every message in real time is required
then the equivilent firehose method should be called.
parameters:
- name: sid
in: path
description: Stream ID
required: true
schema:
type: string
- name: since
in: query
description: |
Timestamp of first required message.
This is a long integer value representing milliseconds since
Jan 1 1970
required: true
schema:
type: integer
format: int64
- name: skip
in: query
description: No. of messages to skip.
schema:
type: integer
- name: limit
in: query
description: >
Max No. of messages to return. If no value is provided, 50 is the
default. The maximum supported value is 500.
schema:
type: integer
- name: sessionToken
in: header
description: Session authentication token.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/V4MessageList'
'204':
description: No Messages.
content: {}
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/v4/stream/{sid}/message/create:
post:
tags:
- Stream
summary: Symphony Post a Message to One Existing Stream
description: >
Post a new message to the given stream. The stream can be a chatroom,,an
IM or a multiparty IM.
You may include an attachment on the message.
The message can be provided as MessageMLV2 or PresentationML. Both
formats support Freemarker templates.
The optional parameter "data" can be used to provide a JSON payload
containing entity data.
If the message contains explicit references to entity data (in
"data-entity-id" element attributes),
this parameter is required.
If the message is in MessageML and fails schema validation a client
error will be returned.
If the message is sent then 200 is returned.
Regarding authentication, you must either use the sessionToken which was
created for delegated app access
or both the sessionToken and keyManagerToken together.
parameters:
- name: sid
in: path
description: Stream ID
required: true
schema:
type: string
- name: sessionToken
in: header
description: Authorization token used to make delegated calls.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
message:
type: string
description: The message payload in MessageML.
data:
type: string
description: Optional message data in EntityJSON.
version:
type: string
description: >
Optional message version in the format "major.minor". If
empty, defaults to the latest supported version.
attachment:
type: string
description: Optional file attachment.
format: binary
preview:
type: string
description: Optional attachment preview.
format: binary
responses:
'200':
description: Message sent.
content:
application/json:
schema:
$ref: '#/components/schemas/V4Message'
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'451':
description: Compliance Issues found in message or file
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/v4/stream/{sid}/message/{mid}/update:
post:
tags:
- Stream
summary: Symphony Update an Existing Message
description: >
Update an existing message. The existing message must be a valid social
message, that has not been deleted.
The message can be provided as MessageMLV2 or PresentationML. Both
formats support Freemarker templates.
The optional parameter "data" can be used to provide a JSON payload
containing entity data.
If the message contains explicit references to entity data (in
"data-entity-id" element attributes),
this parameter is required.
Regarding authentication, you must either use the sessionToken which was
created for delegated app access
or both the sessionToken and keyManagerToken together.
Starting with SBE v24.1, attachments are supported.
parameters:
- name: sid
in: path
description: Stream ID
required: true
schema:
type: string
- name: mid
in: path
description: ID of the message to be updated
required: true
schema:
type: string
- name: sessionToken
in: header
description: Authorization token used to make delegated calls.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
message:
type: string
description: The message payload in MessageML.
data:
type: string
description: Optional message data in EntityJSON.
version:
type: string
description: >
Optional message version in the format "major.minor". If
empty, defaults to the latest supported version.
attachment:
type: string
description: Optional file attachment.
format: binary
preview:
type: string
description: Optional attachment preview.
format: binary
silent:
type: string
description: >
Optional boolean field that will determine if the user/s
should receive the message as read or not (true by default)
responses:
'200':
description: Message sent.
content:
application/json:
schema:
$ref: '#/components/schemas/V4Message'
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'451':
description: Compliance Issues found in message or file
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
/v3/stream/{sid}/share:
post:
tags:
- Stream
summary: PROVISIONAL - Share a Piece of Content Into Symphony
description: >
Given a 3rd party content (eg. news article), it can share to the given
stream.
The stream can be a chatroom, an IM or a multiparty IM.
parameters:
- name: sid
in: path
description: Stream ID
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/ShareContent'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/V2Message'
'400':
description: Client error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: 'Unauthorized: Session tokens invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'Forbidden: Caller lacks necessary entitlement.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Server error, see response body for further details.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
x-codegen-request-body-name: shareContent
/v1/util/echo:
post:
tags:
- Util
summary: Symphony Test Endpoint, Returns Input
parameters:
- name: sessionToken
in: header
description: Session authentication token.
required: true
schema:
type: string
- name: keyManagerToken
in: header
description: Key Manager authentication token.
required: true
schema:
type: string
requestBody:
description: Message in plain text
content:
application/json:
sche
# --- truncated at 32 KB (197 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/symphony/refs/heads/main/openapi/agent-openapi-original.yml