Room API

Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.

List an advisor's rooms

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

sfsAuthentication

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

HTTPcURLJavaScriptPython

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

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

sfsAuthentication

AuthorizationstringRequired

HTTP header

Body

application/json

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

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

HTTPcURLJavaScriptPython

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 room

Rename a room

post

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

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

StreamId of the room to rename.

Body

application/json

newRoomNamestring · min: 1 · max: 50Required

Responses

200

Room name updated successfully

application/json

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

HTTPcURLJavaScriptPython

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

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

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

StreamId of the room to transfer.

Body

application/json

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

HTTPcURLJavaScriptPython

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

Remove room member (recommended)

delete

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

Authorizations

sfsAuthentication

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

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

409

Conflict

application/json

delete

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

HTTPcURLJavaScriptPython

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

Add room member (recommended)

post

Add a member to a room:

Authorizations

sfsAuthentication

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

application/json

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

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

HTTPcURLJavaScriptPython

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

List room members

get

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

Authorizations

sfsAuthentication

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

HTTPcURLJavaScriptPython

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 features

Update a room's features

post

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

Authorizations

sfsAuthentication

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

application/json

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

HTTPcURLJavaScriptPython

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

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

sfsAuthentication

AuthorizationstringRequired

HTTP header

Body

application/json

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

HTTPcURLJavaScriptPython

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

Update room activity

put

Update room activity room by stream ID

Authorizations

sfsAuthentication

AuthorizationstringRequired

HTTP header

Path parameters

streamIdstringRequired

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

Body

application/json

setActivebooleanRequired

Responses

200

Room Activity successfully updated

application/json

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

HTTPcURLJavaScriptPython

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"
}