Assistant Instances

Instances of AI Assistant associated with a project.

Endpoints

The AI Assistant Instance object

  • idinteger

    The unique identifier for the AI assistant instance.

  • projectIdinteger

    The unique identifier for the project the AI Assistant instance belongs to.

  • entityIDstring

    Optional. If present, this identifies the entity instane associated with the AI Assistant instance.

  • chatPlatform| options are slack, msTeams, direct

    Identifies one of the supported chat platforms that this AI Assistant instance is integrated with.

  • slackConfigobject

    This field is required if chatPlatform is 'slack' and contains necessary configuration of a Slack chatbot.

  • msTeamsConfigobject

    This field is required if chatPlatform is 'msTeams' and contains necessary configuration of a MS Teams chatbot.

  • directConfigobject

    This field is required if chatPlatform is 'direct' and contains necessary configuration of a direct chatbot.

  • namestring

    Display name of AI Assistant.

  • descriptionstring

    Additional information about AI Assistant.

  • createdAtstring| format is date-time

    Instance creation timestamp.

  • updatedAtstring| format is date-time

    Timestamp of last update.

Get AI Assistant instances

Endpoint
get /assistants
Description

Get a list of AI Assistant instances.

Query Parameters

  • projectId

    integer

    required

    Return Assistant instances of the specified project.

  • skip

    integer

    Number of items to skip over.

  • limit

    integer

    Maximum number of items to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read assistant instances, or a project API key.

Response
  • 200Successfully retrieved the assistant instances.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Create AI Assistant instance

Endpoint
post /assistants
Description

Create an AI Assistant instance in a project.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to create assistant instances, or a project API key with admin permission.

Request Body

  • slackConfig

    object

    This field is required if chatPlatform is 'slack' and contains necessary configuration of a Slack chatbot.

  • msTeamsConfig

    object

    This field is required if chatPlatform is 'msTeams' and contains necessary configuration of a MS Teams chatbot.

  • directConfig

    object

    This field is required if chatPlatform is 'direct' and contains necessary configuration of a direct chatbot.

  • name

    string

    required

    Display name of AI Assistant.

  • description

    string

    Additional information about AI Assistant.

Response
  • 201New AI Assistant successfully created.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get assistant

Endpoint
get /assistants/{assistantId}
Description

Return the AI Assistant instance with the specified ID.

Path Parameters

  • assistantId

    integer

    required

    The unique ID for a specific Assistant instance.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read assistant instances, or a project API key.

Response
  • 200Successfully retrieved the specified assistant instance.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested assistant does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Update an AI Assistant instance

Endpoint
patch /assistants/{assistantId}
Description

Update attributes and configurations of the AI Assistant instance with the sepcified ID.

Path Parameters

  • assistantId

    integer

    required

    The unique ID for a specific Assistant instance.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to update assistant instances, or a project API key with admin permission.

Request Body

  • slackConfig

    object

    This field is required if chatPlatform is 'slack' and contains necessary configuration of a Slack chatbot.

  • msTeamsConfig

    object

    This field is required if chatPlatform is 'msTeams' and contains necessary configuration of a MS Teams chatbot.

  • directConfig

    object

    This field is required if chatPlatform is 'direct' and contains necessary configuration of a direct chatbot.

  • name

    string

    required

    Display name of AI Assistant.

  • description

    string

    Additional information about AI Assistant.

Response
  • 204Successfully update the specified assistant instance.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested assistant does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Delete an AI Assistant instance

Endpoint
delete /assistants/{assistantId}
Description

Delete the AI Assistant instance with the sepcified ID.

Path Parameters

  • assistantId

    integer

    required

    The unique ID for a specific Assistant instance.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to delete assistant instances, or a project API key with admin permission.

Response
  • 204Successfully deleted the specified assistant instance.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required assistant does not exist or is not accessible.
  • 409The assistant cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Get Slack channels

Endpoint
get /assistants/{assistantId}/slackChannels
Description

Get a list of Slack channels associated with the AI Assistant instance. This endpoint is available only the chatPlatform of the specified Assistant is Slack. This API only returns the unarchived public channels. NOTE: We are getting the channels list from the Slack conversations.list API. Unlike most of other MODE API endpoints, the pagination style of this API is cursor-based. It's because the above Slack API is cursor-based.

Path Parameters

  • assistantId

    integer

    required

    The unique ID for a specific Assistant instance.

Query Parameters

  • cursor

    string

    You can paginate through the list of channels by providing a cursor. You are supposed to set the cursor to the value of the response's next_cursor field.

  • limit

    integer

    Maximum number of items to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read assistant instances, or a project API key.

Response
  • 200Successfully retrieved the Slack channels.
  • 403The client doesn't have the permission to access the specified Assistant or the chatPlatform of the specified Assistant is not Slack.

Get Direct rooms

Endpoint
get /assistants/{assistantId}/directRooms
Description

Get a list of rooms the assistant has joined. The response doesn't include rooms whose type is pair talk. This endpoint is available only when the chatPlatform of the specified Assistant is Direct. NOTE: /slackChannels endpoint returns all public channels, but this API returns only rooms the assistant has already joined. There is no public room in Direct in the first place and bots can send messages to the channels the bot has already joined.

Path Parameters

  • assistantId

    integer

    required

    The unique ID for a specific Assistant instance.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read assistant instances, or a project API key.

Response
  • 200Successfully retrieved the list of rooms.
  • 403The client doesn't have the permission to access the specified Assistant or the chatPlatform of the specified Assistant is not Direct.