API docs by Redocly

Chat Default Adapter API Documentation (1.0)

Download OpenAPI specification:Download

Basal Inc.: gen@basal.dev URL: basal.dev Terms of Service

Chat Adapter documentation.

Chat Adapter documentation.

Message

Get Message

Retrieve the information of the message with the matching ID.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'read' permission
  • an organization subscription to the topic with the 'read' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
readStatusForOrg
string (objectId) ^[0-9a-z]{24}$
Example: readStatusForOrg=0123456789ab0123456789ab

When specified, readStatus/unreadCount flags for this endpoint will be returned for the organization with the specified ID. This is useful when sharing the same organization chat amongst multiple users.

Note that this can only be used by users who have a role in the specified organization.

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "category": "string",
  • "title": "Title",
  • "content": "This is a message",
  • "customFields": {
    },
  • "organizationId": "0123456789ab0123456789ab",
  • "priority": "important",
  • "receiptId": "0123456789ab0123456789ab",
  • "readStatus": "read",
  • "senderType": "superUser",
  • "senderId": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "typeId": "message",
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

Delete Message

Soft delete an existing message.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • the message belongs to the authenticated user
Authorizations:
(Authorizationx-nb-fingerprint)

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Update Message

Update the information of an existing message.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'read' permission
  • an organization subscription to the topic with the 'read' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Patch Message body

title
string (title)

Title of the message

customFields
object (customFields)

CustomFields of the message. What's inside depends on what was configured when initializing the service.

content
string (content)

Content of the message

priority
string (priority)

Indicate how important the message is

category
string (category)

Category of the message (for human management).

Responses

Request samples

Content type
application/json
{
  • "title": "Title",
  • "customFields": {
    },
  • "content": "This is a message",
  • "priority": "important",
  • "category": "string"
}

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "category": "string",
  • "title": "Title",
  • "content": "This is a message",
  • "customFields": {
    },
  • "organizationId": "0123456789ab0123456789ab",
  • "priority": "important",
  • "receiptId": "0123456789ab0123456789ab",
  • "readStatus": "read",
  • "senderType": "superUser",
  • "senderId": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "typeId": "message",
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

Create Message

Create a new Message.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • the message to be a private chat message
  • a user subscription to the topic with 'write' permission
  • an organization subscription to the topic with the 'write' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Create Message body

category
required
string (category)

Category of the message (for human management).

title
string (title)

Title of the message

customFields
object (customFields)

CustomFields of the message. What's inside depends on what was configured when initializing the service.

content
required
string (content)

Content of the message

organizationId
string (objectId) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

priority
required
string (priority)

Indicate how important the message is

receiptId
string (objectId) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

senderType
required
string (senderType)
Enum: "superUser" "system" "normalUser"

The type of the sender who sent this message

senderId
string (objectId) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

topicId
required
string (objectId) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

typeId
required
string (typeId)
Value: "message"

The type of message (e.g., image for image uploads, or file for file uploads)

Responses

Request samples

Content type
application/json
{
  • "category": "string",
  • "title": "Title",
  • "customFields": {
    },
  • "content": "This is a message",
  • "organizationId": "0123456789ab0123456789ab",
  • "priority": "important",
  • "receiptId": "0123456789ab0123456789ab",
  • "senderType": "superUser",
  • "senderId": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "typeId": "message"
}

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "category": "string",
  • "title": "Title",
  • "content": "This is a message",
  • "customFields": {
    },
  • "organizationId": "0123456789ab0123456789ab",
  • "priority": "important",
  • "receiptId": "0123456789ab0123456789ab",
  • "readStatus": "read",
  • "senderType": "superUser",
  • "senderId": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "typeId": "message",
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

List Messages

Get list of all messages.

This operation requires the super user permission (i.e. user typeId =100, or internal service)

Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

List Messages for User

List messages that are visible to a given user. These messages include all topics that the user is subscribed to with the 'read' permission. This endpoint also give user's read status for each message.

This operation requires the login user.

Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
userId
required
any
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Update Message Read Status

Updates read status of messages in a topic. Messages can be read by both users and organizations. In the chat service, if a message is marked as read, all messages in the same topic with createdAt before the message will also be marked as read.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • userId for read status belongs to the authenticated user
  • organizationId for read status belongs to organization that the authenticated user belongs to (with any role)

This operation also requires a subscription to the topic with 'read' permission, either via user or by organization.

Authorizations:
(Authorizationx-nb-fingerprint)
Request Body schema: application/json

Mark message read body

One of
userId
required
string
messageId
required
string (objectId) ^[0-9a-z]{24}$

A 24 character hexadecimal string value.

Responses

Request samples

Content type
application/json
{
  • "organizationId": "string",
  • "messageId": "0123456789ab0123456789ab"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

List Messages for Topic

List messages that belong to one topic. Users can only retrieve messages they have permission to read. This endpoint also gives read status for each message.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'read' permission
  • an organization subscription to the topic with the 'read' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
topicId
required
any
query Parameters
readStatusForOrg
string (objectId) ^[0-9a-z]{24}$
Example: readStatusForOrg=0123456789ab0123456789ab

When specified, readStatus/unreadCount flags for this endpoint will be returned for the organization with the specified ID. This is useful when sharing the same organization chat amongst multiple users.

Note that this can only be used by users who have a role in the specified organization.

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Subscription

List Subscriptions for Topic

List subscriptions that belong to one topic.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'read' permission
  • an organization subscription to the topic with the 'read' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
topicId
required
any
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Create Subscription

Creates a subscription. A subscription gives permission over a topic. Subscriptions can be created for users or for organizations. Duplicate subscriptions for the same user or organization to the same topic are not allowed.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'admin' permission
  • an organization subscription to the topic with the 'admin' permission, and the user is in the organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Create Subscription body

One of
userId
required
string

ID of the user to subscribe

topicId
required
string

Topic ID of the message

permissions
Array of strings (permissions)

Permissions granted to user

approved
boolean (approved)

Whether the subscription is approved

customFields
object (customFields)

CustomFields of the message. What's inside depends on what was configured when initializing the service.

Responses

Request samples

Content type
application/json
{
  • "organizationId": "string",
  • "topicId": "string",
  • "permissions": "read",
  • "approved": true,
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "organizationId": "0123456789ab0123456789ab",
  • "userId": "0123456789ab0123456789ab",
  • "approved": true,
  • "permissions": [
    ],
  • "subscribedAt": "2023-01-01T00:00:00.000Z",
  • "customFields": {
    }
}

List Subscriptions

Lists all subscriptions.

This operation requires the super user permission (i.e. user typeId =100, or internal service)

Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Get Subscription

Get a subscription by ID.

This operation requires the login user, and user subscribed to the topic

query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "topicId": "0123456789ab0123456789ab",
  • "organizationId": "0123456789ab0123456789ab",
  • "userId": "0123456789ab0123456789ab",
  • "approved": true,
  • "permissions": [
    ],
  • "subscribedAt": "2023-01-01T00:00:00.000Z",
  • "customFields": {
    }
}

Delete Subscription

Delete subscription by ID.

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • a user subscription to the topic with 'admin' permission
  • an organization subscription to the topic with the 'admin' permission, and the user is in the organization with any role
  • the subscription belongs to the user in question or the organization the user is in (via any role)

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Topic

List Topics

Get list of all topics This operation requires superuser permission (i.e. user typeId =100, or internal service)

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires the super user permission (i.e. user typeId =100, or internal service)

Authorizations:
(Authorizationx-nb-fingerprint)
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Create Topic

Create a new topic.

If a topic is created with ownerType=user, then the current user will be subscribed to the topic. In addition, if ownerIds is provided with ownerType=user, then the provided users will also be subscribed to the topic.

If a topic is created with ownerType=organization, then the organization ownerIds provided will be subscribed to the topic.

For Organization owners, if no ownerIds are provided, the topic will be created with no owners or subscriptions. This means that no users will be able to access or modify the topic. Ensure that at least one owner is specified when using organization owners.

Other than being logged in to the platform, this request has no other authentication restrictions.

query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Create Topic

name
required
string

Name of the topic

typeId
required
string
Enum: "channel" "private"

The type of topic (used for configuring who can subscribe)

app
string

Which App the topic belongs to.

isPublic
boolean

If the topic public to normal user.

ownerType
required
string
Enum: "user" "organization"

Type of the owner

ownerIds
required
Array of strings (ObjectId)
customFields
object (customFields)

CustomFields of the message. What's inside depends on what was configured when initializing the service.

Responses

Request samples

Content type
application/json
{
  • "name": "topic-name",
  • "typeId": "channel",
  • "app": "user",
  • "isPublic": true,
  • "ownerType": "user",
  • "ownerIds": [
    ],
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "name": "topic-name",
  • "typeId": "channel",
  • "app": "user",
  • "isPublic": true,
  • "lastMessageAt": "2023-01-01T00:00:00.000Z",
  • "lastMessageId": "0123456789ab0123456789ab",
  • "ownerType": "user",
  • "ownerIds": [
    ],
  • "unreadCount": 3,
  • "customFields": {
    },
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

List Topics subscribed by Organization

Gets list of topics that the organization is subscribed to. Topics will only be returned if a subscription exists between the organization and the topic.

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • user belongs to organization with any role
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
userId
required
string
query Parameters
readStatusForOrg
string (objectId) ^[0-9a-z]{24}$
Example: readStatusForOrg=0123456789ab0123456789ab

When specified, readStatus/unreadCount flags for this endpoint will be returned for the organization with the specified ID. This is useful when sharing the same organization chat amongst multiple users.

Note that this can only be used by users who have a role in the specified organization.

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

List Topics owned by Organization

Gets list of topics that the organization is an owner for. The topics must have the organization as one of the 'ownerIds', with ownerType 'organization'.

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • user is admin or owner of the specified organization
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
orgId
required
string
query Parameters
readStatusForOrg
string (objectId) ^[0-9a-z]{24}$
Example: readStatusForOrg=0123456789ab0123456789ab

When specified, readStatus/unreadCount flags for this endpoint will be returned for the organization with the specified ID. This is useful when sharing the same organization chat amongst multiple users.

Note that this can only be used by users who have a role in the specified organization.

$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

List Topics subscribed by User

Gets list of topics that the user is subscribed to. Topics will only be returned if a subscription exists between the user and the topic.

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires that the user is logged in as the user specified in the path parameter.

Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
userId
required
string
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

List Topics owned by User

Gets list of topics that the user is an owner for. The topics must have the user as one of the 'ownerIds', with ownerType 'user'.

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires that the user is logged in as the user specified in the path parameter.

Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
userId
required
string
query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Get Topic

Get topic by ID.

Supported $expands

  • user - expands ownerIds to owners array
  • organization - expands ownerIds to owners array
  • subscribedUsers - appends subscriptions array to each topic, containing expanded users key for each subscription
  • message - appends lastMessage key to each topic, containing expanded message object

This operation requires one of the following:

  • super user permission (i.e. user typeId =100, or internal service)
  • user is an owner of the topic (i.e. user is in the ownerIds array)
  • user is admin or owner of organization that is an owner of the topic
  • a user subscription to the topic with 'read' permission
  • an organization subscription to the topic with the 'read' permission, and the user is in the organization with any role
path Parameters
topicId
required
string
query Parameters
readStatusForOrg
string (objectId) ^[0-9a-z]{24}$
Example: readStatusForOrg=0123456789ab0123456789ab

When specified, readStatus/unreadCount flags for this endpoint will be returned for the organization with the specified ID. This is useful when sharing the same organization chat amongst multiple users.

Note that this can only be used by users who have a role in the specified organization.

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "name": "topic-name",
  • "typeId": "channel",
  • "app": "user",
  • "isPublic": true,
  • "lastMessageAt": "2023-01-01T00:00:00.000Z",
  • "lastMessageId": "0123456789ab0123456789ab",
  • "ownerType": "user",
  • "ownerIds": [
    ],
  • "unreadCount": 3,
  • "customFields": {
    },
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

Update Topic

Update topic information.

This operation requires either

  • the super user permission (i.e. user typeId =100, or internal service)
  • user is an owner of the topic (i.e. user is in the ownerIds array)
  • user is admin or owner of organization that is an owner of the topic
path Parameters
topicId
required
string
query Parameters
$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}
Request Body schema: application/json

Patch Topic

name
string

Name of the topic

typeId
string
Enum: "channel" "private"

The type of topic (used for configuring who can subscribe)

app
string

Which App the topic belongs to.

isPublic
boolean

If the topic public to normal user.

ownerIds
Array of strings (ObjectId)
customFields
object (customFields)

CustomFields of the message. What's inside depends on what was configured when initializing the service.

Responses

Request samples

Content type
application/json
{
  • "name": "topic-name",
  • "typeId": "channel",
  • "app": "user",
  • "isPublic": true,
  • "ownerIds": [
    ],
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0123456789ab0123456789ab",
  • "name": "topic-name",
  • "typeId": "channel",
  • "app": "user",
  • "isPublic": true,
  • "lastMessageAt": "2023-01-01T00:00:00.000Z",
  • "lastMessageId": "0123456789ab0123456789ab",
  • "ownerType": "user",
  • "ownerIds": [
    ],
  • "unreadCount": 3,
  • "customFields": {
    },
  • "createdAt": "2023-01-01T00:00:00.000Z",
  • "updatedAt": "2023-01-01T00:00:00.000Z"
}

Delete Topic

Delete a topic by ID

This operation requires either

  • the super user permission (i.e. user typeId =100, or internal service)
  • user is an owner of the topic (i.e. user is in the ownerIds array)
  • user is admin or owner of organization that is an owner of the topic
path Parameters
topicId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Message Template

Create Message Template

Create a new Message Template.

This operation requires the login user, and the user must be one of:

  • super user (i.e. user typeId =100, or internal service)
  • belongs to an organization
Authorizations:
(Authorizationx-nb-fingerprint)
Request Body schema: application/json

Create Message Template body

title
required
string
content
required
string
orgId
string
permissions
Array of any

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "orgId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "title": "string",
  • "content": "string",
  • "orgId": "0123456789ab0123456789ab",
  • "permissions": [ ]
}

List Message Templates

Retrieve the information of all message templates.

This operation requires the super user permission (i.e. user typeId =100, or internal service)

Authorizations:
(Authorizationx-nb-fingerprint)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Update Message Template

Update a Message Template.

This operation requires the login user, and the user must be one of:

  • super user (i.e. user typeId =100, or internal service)
  • belongs to an organization, and same orgId owns the message template
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
messageTemplateId
required
string
Request Body schema: application/json

Patch Message Template body

title
string
content
string
orgId
string
permissions
Array of any

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "content": "string",
  • "orgId": "string",
  • "permissions": [
    ]
}

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "title": "string",
  • "content": "string",
  • "orgId": "0123456789ab0123456789ab",
  • "permissions": [ ]
}

Get Message Template

Retrieve the information of a message template by ID.

This operation requires the login user, and the user must be one of:

  • super user (i.e. user typeId =100, or internal service)
  • belongs to an organization, and same orgId owns the message template
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
messageTemplateId
required
string

Responses

Response samples

Content type
{
  • "id": "0123456789ab0123456789ab",
  • "title": "string",
  • "content": "string",
  • "orgId": "0123456789ab0123456789ab",
  • "permissions": [ ]
}

Delete Message Template

Update Message Template.

This operation requires the login user, and the user must be one of:

  • super user (i.e. user typeId =100, or internal service)
  • belongs to an organization, and same orgId owns the message template
Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
messageTemplateId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

List Message Tempalates for Organization

Retrieve the information of the message templates by the organization ID.

This operation requires the user need to be a member of the organization.

Authorizations:
(Authorizationx-nb-fingerprint)
path Parameters
orgId
required
string

Organization ID

query Parameters
$filter
string

Return only items which matches to a condition (The operators below are listed in order of precedence from highest to lowest).

Operator Description Example
( ) Precedence grouping (items.quantity eq 1 or items.productName eq 'T-Shirt') and totalPrice gt 100
not Logical negation not totalPrice le 3.5
gt Greater than totalPrice gt 20
ge Greater than or equal totalPrice ge 10
lt Less than totalPrice lt 20
le Less than or equal totalPrice le 100
eq Equal customer.userId eq '01234567890123456789ab'
ne Not equal status ne 'CANCELED'
and Logical and totalPrice le 200 and totalPrice gt 3.5
or Logical or totalPrice le 3.5 or totalPrice gt 200
$top
integer

number of object want to fetch

$skip
integer

number of object want to skip

$nextToken
string

Token for get next batch of list data

$previousToken
string

Token for get previous batch of list data

$expand
string
Value: "user"

Include extra information that are not included in responses by default in the response. By default, the fields that supports this query contain only uri for referring to the full information of it. To include the full information of the field, specify the field by $expand.

You can expand recursively by specifying nested fields after a dot (.). until For example, requesting product.category on a product image will expand the product property into a full product object, and will then expand the category property on that product into a full category object. Expansions have a maximum depth of 3 levels.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

You can expand multiple objects at once by identifying multiple items in comma-separated style.

Examples:

Include full category and organization information in the response.

Before expanding,

{
  ...
  "category": {
    "uri": "https://{{catalogServiceEndpoint}}/categories/01234567890123456789ab"
  },
  "organization": {
    "uri": "https://{{organizationServiceEndpoint}}/organization/01234567890123456789ab"
  },
  ...
}

By using $expand parameter,

$expand=category,organization

It will returns full information:

{
  ...
  "category": {
    "id": "01234567890123456789ab",
    "name": "Category A",
    "description": "Description of Category A.",
    ...
  },
  "organization": {
    "id": "01234567890123456789ab",
    "name": "Org A",
    "description": "Description of Org A.",
    ...
  },
  ...
}

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "count": 0,
  • "@nextLink": "string",
  • "@previousLink": "string",
  • "value": [
    ]
}

Attachment

Create Topic Attachment

Create a topic attachment

This operation requires

  • valid Authorization specified in request header
  • Authorization have super user permission or
    • user subscribed to the topic and have write permission on the topic
Authorizations:
Authorization
Request Body schema: application/json

attachment data

Array
objectId
string non-empty

objectId in storage

type
string non-empty

type of the attachment

ownerId
string non-empty

owner of the attachment

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "ownerId": "string",
  • "ownerType": "string",
  • "type": "string",
  • "url": "http://example.com"
}

List Topic Attachments

Get list of topic attachments

This operation requires

  • valid Authorization specified in request header
  • Authorization have super user permission or
    • user subscribed to the topic and have read permission on the topic
Authorizations:
Authorization

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Topic Attachment

Get a specific topic attachment

This operation requires

  • valid Authorization specified in request header
  • Authorization have super user permission or
    • user subscribed to the topic and have read permission on the topic
Authorizations:
Authorization
path Parameters
topicId
required
string

The ID of the topic

attachmentId
required
string

The ID of the attachment

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "ownerId": "string",
  • "ownerType": "string",
  • "type": "string",
  • "url": "http://example.com"
}

Delete Topic Attachment

Delete an topic attachment

This operation requires

  • valid Authorization specified in request header
  • Authorization have super user permission or
    • user subscribed to the topic and have write permission on the topic
Authorizations:
Authorization
path Parameters
topicId
required
string

The ID of the topic

attachmentId
required
string

The ID of the attachment

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get Topic Attachment upload URL

Create signed url for user to upload an attachment

This operation requires

  • valid Authorization specified in request header
  • Authorization have super user permission or
  • user subscribed to the topic and have write permission on the topic
Authorizations:
Authorization

Responses

Response samples

Content type
application/json
null