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)

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.

GEThttps://CONNECT-DOMAIN/api/v2/customer/rooms

Authorization

sfsAuthentication

Query parameters

Response

200400401403404

List of rooms found

Body

application/json

roomsarray of room-response (object)

paginationPagination

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/rooms', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "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
    }
  ],
  "pagination": {
    "previous": "?before=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "next": "?after=ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
    "cursors": {
      "before": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9",
      "after": "ewogICJlbWFpbEFkZHJlc3MiOiB7CiAgICAicyI6ICJtb2NrLnVzZXJAbW9jay5jb20iCiAgfQp9"
    }
  }
}

Create room

Create room (recommended)

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

POSThttps://CONNECT-DOMAIN/api/v2/customer/rooms

Authorization

sfsAuthentication

Body

application/json

roomName*string

federationGroupIdstring

externalNetworkRoomDisplayNamestring

ownerSymphonyId*string (number)

externalNetwork*string

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

Response

200400401403404409500

Room created successfully

Body

application/json

streamIdstring

roomNamestring

advisorSymphonyIdstring

federationGroupIdstring

createdstring (date-time)

updatedstring (date-time)

roomTypeenum

ROOMIM

membersCountinteger

externalNetworkRoomDisplayNamestring

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/rooms', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "ownerSymphonyId": 1234567890,
      "externalNetwork": "WHATSAPP",
      "roomName": "API room"
    }),
});
const data = await response.json();

Response

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

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

POSThttps://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/rename

Authorization

sfsAuthentication

Path parameters

streamId*string

StreamId of the room to rename.

Body

application/json

newRoomName*string

Response

200401403404409500

Room name updated successfully

Body

application/json

streamIdstring

oldRoomNamestring

newRoomNamestring

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/rename', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "newRoomName": "text"
    }),
});
const data = await response.json();

Response

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

Transfer room ownership to another advisor

Transfer room ownership to another advisor

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

POSThttps://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/ownership

Authorization

sfsAuthentication

Path parameters

streamId*string

StreamId of the room to transfer.

Body

application/json

newRoomOwnerSymphonyId*string (number)

Response

204404409

Room owner updated successfully

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/ownership', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "newRoomOwnerSymphonyId": 1234567890
    }),
});
const data = await response.json();

Remove room member

Remove room member (recommended)

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

DELETEhttps://CONNECT-DOMAIN/api/v2/customer/rooms/{streamId}/members

Authorization

sfsAuthentication

Path parameters

streamId*string

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.

Query parameters

Response

200401403404409

Member successfully removed from the room

Body

application/json

isRoomDeletedboolean

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/rooms/{streamId}/members', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "isRoomDeleted": false
}

Add room member

Add room member (recommended)

Add a member to a room:

POSThttps://CONNECT-DOMAIN/api/v2/customer/rooms/{streamId}/members

Authorization

sfsAuthentication

Path parameters

streamId*string

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

application/json

memberSymphonyId*string (number)

advisorSymphonyId*string (number)

externalNetwork*string

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

contact*boolean

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

empChannelConnectorstring

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.

Response

200400401403404409500

Member successfully added to the room

Body

application/json

streamIdstring

symphonyIdstring

federatedUserIdstring

externalNetworkstring

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

firstNamestring

lastNamestring

companyNamestring

avatarstring

displayNamestring

emailAddressstring

isOwnerboolean

empChannelConnectorall of

Network channel connector used for room member. Only for LINE

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/rooms/{streamId}/members', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "advisorSymphonyId": 1234567890,
      "memberSymphonyId": 1234567890,
      "externalNetwork": "WHATSAPP",
      "contact": false
    }),
});
const data = await response.json();

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": "[e-mail]",
  "isOwner": false,
  "empChannelConnector": {
    "displayName": "Official Account Name",
    "id": 123456
  }
}

List room members

List room members

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

GEThttps://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/members

Authorization

sfsAuthentication

Path parameters

streamId*string

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.

Query parameters

Response

200400401403

List of room members

Body

application/json

membersarray of room-member-response (object)

paginationPagination

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/members', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer JWT"
    },
});
const data = await response.json();

Response

{
  "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": "[e-mail]",
      "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

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

POSThttps://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/features

Authorization

sfsAuthentication

Path parameters

streamId*string

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

application/json

attachmentsDisabledboolean

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

Response

204400401403

Features updated successfully

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v1/customer/rooms/{streamId}/features', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Add room members in bulk

Add room members in bulk (recommended)

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.

POSThttps://CONNECT-DOMAIN/api/v2/customer/rooms/members

Authorization

sfsAuthentication

Body

application/json

requestsarray of room-member-multi-room-requestv2 (object)

advisorSymphonyIdstring (number)

externalNetworkstring

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

Response

200400401403

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

Body

application/json

membersarray of bulk-room-member-item-responsev2 (object)

Request

JavaScriptCurl

const response = await fetch('https://CONNECT-DOMAIN/api/v2/customer/rooms/members', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "members": [
    {
      "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": "[e-mail]",
        "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"
        }
      }
    }
  ]
}