Room API | 26.04 - UAT

List an advisor's rooms (recommended)

get

List all rooms where an advisor is either a member or an owner for a given network.
Search is performed with the advisor's Symphony user ID.
This end point returns at most 25 records per page.

Authorizations

AuthorizationstringRequired

HTTP header

Query parameters

advisorSymphonyIdstring · numberRequired

Advisor's Symphony user ID

Example: 1234567890

externalNetworkstringRequired

The external network: WECHAT or WHATSAPP or WHATSAPP-DIRECT or SMS or SMS-DIRECT or LINE

Example: WHATSAPP

ownerbooleanOptional

If set to "true", lists the rooms where the advisor is an owner. If set to "false", lists the rooms where the advisor is an owner and the rooms where the advisor is only a member.

Default: true

beforestringOptional

The before cursor for pagination

afterstringOptional

The after cursor for pagination

Responses

200

List of rooms found

application/json

400

Missing or malformed parameter

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

404

Not found

application/json

get

/api/v2/customer/rooms

GET /api/v2/customer/rooms?advisorSymphonyId=1234567890&externalNetwork=WHATSAPP HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "rooms": [
    {
      "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
      "roomName": "API room",
      "advisorSymphonyId": 12345678912365,
      "federationGroupId": "federationGroupId",
      "created": 1547661232368,
      "updated": 1547661232370,
      "roomType": "ROOM",
      "membersCount": 1,
      "company": "Company",
      "roomStatus": "ACTIVE",
      "limitedMembersCount": 1,
      "pendingMembersCount": 2,
      "unknownStatusMembersCount": 0
    }
  ],
  "pagination": {
    "previous": "?before=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "next": "?after=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "cursors": {
      "before": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
      "after": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9"
    }
  }
}

Create room (recommended)

post

Create a room with the advisor whose Symphony user ID is provided.
The advisor is set as a member.
"externalNetworkRoomDisplayName" applies for WeChat only.

Authorizations

AuthorizationstringRequired

HTTP header

Body

roomNamestring · max: 50RequiredExample: API room

federationGroupIdstringOptionalExample: federationGroupId

externalNetworkRoomDisplayNamestring · max: 50OptionalExample: API room

ownerSymphonyIdstring · numberRequiredExample: 1234567890

externalNetworkstring · max: 50Required

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

Example: WHATSAPP

Responses

200

Room created successfully

application/json

streamIdstringOptionalExample: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA

roomNamestringOptionalExample: API room

advisorSymphonyIdstringOptionalExample: 12345678912365

federationGroupIdstringOptionalExample: federationGroupId

createdstring · date-timeOptionalExample: 1547661232368

updatedstring · date-timeOptionalExample: 1547661232370

roomTypestring · enumOptionalPossible values:

membersCountintegerOptionalExample: 1

externalNetworkRoomDisplayNamestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Advisor not found

application/json

409

Conflict (room name already exists)

application/json

500

Room creation failed

application/json

post

/api/v2/customer/rooms

POST /api/v2/customer/rooms HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "roomName": "API room",
  "federationGroupId": "federationGroupId",
  "externalNetworkRoomDisplayName": "API room",
  "ownerSymphonyId": 1234567890,
  "externalNetwork": "WHATSAPP"
}

{
  "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
  "roomName": "API room",
  "advisorSymphonyId": 12345678912365,
  "federationGroupId": "federationGroupId",
  "created": 1547661232368,
  "updated": 1547661232370,
  "roomType": "ROOM",
  "membersCount": 1,
  "externalNetworkRoomDisplayName": "text"
}

Rename a room

post

Rename a room with the new room name which is provided.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

StreamId of the room to rename.

Body

newRoomNamestring · min: 1 · max: 50Required

Responses

200

Room name updated successfully

application/json

streamIdstringOptional

oldRoomNamestringOptional

newRoomNamestringOptional

401

Unauthorized

application/json

403

Forbidden

application/json

404

Room not found

application/json

409

Conflict

application/json

500

Rename room failed

application/json

post

/api/v1/customer/rooms/{streamId}/rename

POST /api/v1/customer/rooms/{streamId}/rename HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "newRoomName": "text"
}

{
  "streamId": "text",
  "oldRoomName": "text",
  "newRoomName": "text"
}

Transfer room ownership to another advisor

post

Transfer the room ownership to the advisor matching the provided Symphony user ID.
This advisor should already be a member of the room.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

StreamId of the room to transfer.

Body

newRoomOwnerSymphonyIdstring · numberRequiredExample: 1234567890

Responses

204

Room owner updated successfully

404

Not found

application/json

409

Conflict

application/json

post

/api/v1/customer/rooms/{streamId}/ownership

POST /api/v1/customer/rooms/{streamId}/ownership HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "newRoomOwnerSymphonyId": 1234567890
}

No content

Remove room member (recommended)

delete

Remove any member, advisor or contact from a room.
The room is identified by its streamID.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

Room's streamId. The streamId needs to be URLsafe Base64. To obtain the URLSafe Base64 Conversation ID:

replace forward slashes / with underscores
replace pluses + with minuses -
ignore any trailing equal signs = For example, the URLSafe Base64 encoding of: lX1hwfmQ+AK/k/a/BB0y2n///q2+0KfbdA== converts to lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Example: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA

Query parameters

memberSymphonyIdstring · numberRequired

The Symphony user ID of the member to remove

Example: 1234567890

advisorSymphonyIdnumberRequired

The Symphony user ID of the advisor who is removing the member

Example: 1234567890

Responses

200

Member successfully removed from the room

application/json

isRoomDeletedbooleanOptional

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

delete

/api/v2/customer/rooms/{streamId}/members

DELETE /api/v2/customer/rooms/{streamId}/members?memberSymphonyId=1234567890&advisorSymphonyId=1234567890 HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "isRoomDeleted": true
}

Add room member (recommended)

post

Add a member to a room:

An advisor must be entitled for the relevant external network.
A contact must have already been onboarded.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

Room's streamId. The streamID needs to be URLsafe Base64. To obtain the URLSafe Base64 conversation ID:

Replace forward slashes / with underscores _
Replace pluses + with minuses -
Ignore any trailing equal signs = For example, the URLSafe Base64 encoding of: lX1hwfmQ+AK/k/a/BB0y2n///q2+0KfbdA== converts to lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Example: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA

Body

memberSymphonyIdstring · numberRequiredExample: 1234567890

advisorSymphonyIdstring · numberRequiredExample: 1234567890

externalNetworkstringRequired

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

Example: WHATSAPP

contactbooleanRequired

Boolean indicating whether added member is an advisor (false) or a federated user (true)

Default: false

empChannelConnectorstringOptional

ID of the Emp channel Connector to use to reach the federated user. Required for LINE in case automatic LINE channel selection feature is not enabled for your tenant, not applicable for the other external networks.

Responses

200

Member successfully added to the room

application/json

streamIdstringOptionalExample: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA

symphonyIdstringOptionalExample: 12345678912365

federatedUserIdstringOptionalExample: 14362370637825

externalNetworkstringOptional

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

Example: WHATSAPP

firstNamestringOptionalExample: John

lastNamestringOptionalExample: Doe

companyNamestringOptionalExample: Company

avatarstringOptionalExample: https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png

displayNamestringOptionalExample: John Doe

emailAddressstringOptionalExample: [email protected]

isOwnerbooleanOptionalExample: false

400

Forbidden

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

500

Failed to add member to the room

application/json

post

/api/v2/customer/rooms/{streamId}/members

POST /api/v2/customer/rooms/{streamId}/members HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "memberSymphonyId": 1234567890,
  "advisorSymphonyId": 1234567890,
  "externalNetwork": "WHATSAPP",
  "contact": false,
  "empChannelConnector": "text"
}

{
  "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
  "symphonyId": 12345678912365,
  "federatedUserId": 14362370637825,
  "externalNetwork": "WHATSAPP",
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Company",
  "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
  "displayName": "John Doe",
  "emailAddress": "[email protected]",
  "isOwner": false,
  "empChannelConnector": {
    "displayName": "Official Account Name",
    "id": 123456
  }
}

List room members

get

List a room’s members. The room is identified by its streamID.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

Room's streamId. The streamId needs to be URL safe Base64. To obtain the URLSafe Base64 conversation ID:

Replace forward slashes / with underscores _
Replace pluses + with minuses -
Ignore any trailing equal signs = For example, the URLSafe Base64 encoding of: lX1hwfmQ+AK/k/a/BB0y2n///q2+0KfbdA== converts to lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Example: lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA

Query parameters

beforestringOptional

The before cursor for pagination

afterstringOptional

The after cursor for pagination

Responses

200

List of room members

application/json

400

Missing or malformed parameter

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

get

/api/v1/customer/rooms/{streamId}/members

GET /api/v1/customer/rooms/{streamId}/members HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "members": [
    {
      "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
      "symphonyId": 12345678912365,
      "federatedUserId": 14362370637825,
      "externalNetwork": "WHATSAPP",
      "firstName": "John",
      "lastName": "Doe",
      "companyName": "Company",
      "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
      "displayName": "John Doe",
      "emailAddress": "[email protected]",
      "isOwner": false,
      "empChannelConnector": {
        "displayName": "Official Account Name",
        "id": 123456
      }
    }
  ],
  "pagination": {
    "previous": "?before=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "next": "?after=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "cursors": {
      "before": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
      "after": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9"
    }
  }
}

Update room member's attributes

put

Update room member's attributes, such as their role in the room.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

The ID of the Symphony room.

memberSymphonyIdstringRequired

The ID of the member to update.

Pattern: ^\d+$

Body

rolestring · enumOptional

The role to assign to the member.

Possible values:

Responses

200

Member's role updated successfully.

No content

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

409

Conflict.

application/json

put

/api/v1/customer/rooms/{streamId}/members/{memberSymphonyId}

PUT /api/v1/customer/rooms/{streamId}/members/{memberSymphonyId} HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "role": "OWNER"
}

No content

Update a room's features

post

Update a room's features. Only supported for WhatsApp. The room is identified by its streamID.

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

Room's streamId. The streamId needs to be URLsafe Base64. To obtain the URLSafe Base64 conversation ID:

Replace forward slashes / with underscores _
Replace pluses + with minuses -
Ignore any trailing equal signs = For example, the URLSafe Base64 encoding of: lX1hwfmQ+AK/k/a/BB0y2n///q2+0KfbdA== converts to lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Example: lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA

Body

attachmentsDisabledbooleanOptional

Allows to enable or disable attachments in a room. Only supported for WhatsApp.

Responses

204

Features updated successfully

400

Missing or malformed parameter

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

post

/api/v1/customer/rooms/{streamId}/features

POST /api/v1/customer/rooms/{streamId}/features HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "attachmentsDisabled": true
}

No content

Add room members in bulk (recommended)

post

Add multiple advisors and/or contacts to a room.
An advisor must be entitled for the relevant external network. A contact must have already been onboarded.

Authorizations

AuthorizationstringRequired

HTTP header

Body

advisorSymphonyIdstring · numberOptionalExample: 1234567890

externalNetworkstringOptional

External network: WECHAT or WHATSAPP or SMS or SMS-DIRECT or LINE

Example: WHATSAPP

Responses

200

Operation to add members to the room completed. Returns an object with the detail of each member's addition success or failure.

application/json

400

Missing or malformed parameter

application/json

401

Unauthorized

application/json

403

Operation forbidden

application/json

post

/api/v2/customer/rooms/members

POST /api/v2/customer/rooms/members HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 186

{
  "requests": [
    {
      "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
      "memberSymphonyId": 1234567890,
      "empChannelConnector": "SYM0001"
    }
  ],
  "advisorSymphonyId": 1234567890,
  "externalNetwork": "WHATSAPP"
}

{
  "members": [
    {
      "status": 1,
      "response": {
        "streamId": "bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA",
        "symphonyId": 12345678912365,
        "federatedUserId": 14362370637825,
        "externalNetwork": "WHATSAPP",
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Company",
        "avatar": "https://YOURDOMAIN.symphony.com/avatars/3gXMhglCCTwLPL9JAprnyHzYn5-PR49-wYDG814n1g8.png",
        "displayName": "John Doe",
        "emailAddress": "[email protected]",
        "isOwner": false,
        "empChannelConnector": {
          "displayName": "Official Account Name",
          "id": 123456
        }
      },
      "error": {
        "itemId": "text",
        "type": "https://zalando.github.io/problem/constraint-violation",
        "title": "text",
        "statusCode": 503,
        "detail": "Connection to database timed out",
        "instance": "https://example.com",
        "parameters": {
          "additionalProp1": "text",
          "additionalProp2": "text",
          "additionalProp3": "text"
        }
      }
    }
  ]
}

Update room activity

put

Update room activity room by stream ID

Authorizations

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

Room's streamId.
The streamID needs to be URLsafe Base64.
To obtain the URLSafe Base64 Conversation ID:

Replace forward slashes / with underscores _
Replace pluses + with minuses -
Ignore any trailing equal signs =

For example, the URLSafe Base64 encoding of: lX1hwfmQ+AK/k/a/BB0y2n///q2+0KfbdA== converts to lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Body

setActivebooleanRequired

Responses

200

Room Activity successfully updated

application/json

isRoomActivityUpdatedbooleanOptional

newRoomStatusstring · enumOptionalPossible values:

404

Room not found

application/json

500

Update room Status failed

application/json

501

Reactivation Not Implemented

application/json

put

/api/v1/customer/rooms/{streamId}/activity

PUT /api/v1/customer/rooms/{streamId}/activity HTTP/1.1
Host: CONNECT-DOMAIN
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "setActive": true
}

{
  "isRoomActivityUpdated": true,
  "newRoomStatus": "ACTIVE"
}

hashtagList an advisor's rooms

hashtagList an advisor's rooms (recommended)

hashtagCreate room

hashtagCreate room (recommended)

hashtagRename room

hashtagRename a room

hashtagTransfer room ownership to another advisor

hashtagTransfer room ownership to another advisor

hashtagRemove room member

hashtagRemove room member (recommended)

hashtagAdd room member

hashtagAdd room member (recommended)

hashtagList room members

hashtagList room members

hashtagUpdate room member

hashtagUpdate room member's attributes

hashtagUpdate room features

hashtagUpdate a room's features

hashtagAdd room members in bulk

hashtagAdd room members in bulk (recommended)

hashtagUpdate room activity

hashtagUpdate room activity

List an advisor's rooms

List an advisor's rooms (recommended)

Create room

Create room (recommended)

Rename room

Rename a room

Transfer room ownership to another advisor

Transfer room ownership to another advisor

Remove room member

Remove room member (recommended)

Add room member

Add room member (recommended)

List room members

List room members

Update room member

Update room member's attributes

Update room features

Update a room's features

Add room members in bulk

Add room members in bulk (recommended)

Update room activity

Update room activity