Skip to main content
API docs by Redocly

ChatKitty Platform API (2.5.5)

Download OpenAPI specification:Download

URL: mailto:support@chatkitty.com License: MIT Terms of Service

OpenAPI specification (OAS) for the ChatKitty Platform API. See the Interactive Docs to try ChatKitty API methods without writing code, and get the complete schema of resources exposed by the API.

Platform API Interactive Docs

Application

Configure and manage your ChatKitty application

Retrieve the authenticated application

Returns the ChatKitty application associated with the authentication credentials used.

You must use an OAuth V2 Bearer token to access this endpoint.

Authorizations:
application_authorization

Responses

Request samples 

curl -X 'GET' \
  'https://api.chatkitty.com/v1/application' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Retrieve the authenticated application settings

Returns the current settings configuring this application

Authorizations:
application_authorization

Responses

Request samples 

curl -X 'GET' \
  'https://api.chatkitty.com/v1/application/settings' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{
  • "features": {
    }
}

Update the authenticated application settings

Update the settings configuring this application

Authorizations:
application_authorization
Request Body schema: application/json
guestUsers
required
string
Enum: "DISABLED" "ENABLED"

Toggle state of this settings option

userCreatedChannels
required
string
Enum: "DISABLED" "ENABLED"

Toggle state of this settings option

Responses

Request samples

Content type
application/json
{
  • "guestUsers": "DISABLED",
  • "userCreatedChannels": "DISABLED"
}

Response samples

Content type
{
  • "features": {
    }
}

Channels

Operations to create, retrieve, update and delete channels

List channels

Returns a page of channels belonging to this application

Authorizations:
application_authorization
query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

type
string
Enum: "DIRECT" "PUBLIC" "PRIVATE"

Filters by channel type

members
Array of strings unique

Filters by channel members using their usernames

startTime
string <date-time>

Filters for channels created within a time range: start time

endTime
string <date-time>

Filters for channels created within a time range: end time

properties
string

Filters by channel custom properties

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels?page=0&size=5' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Create a channel

Creates a new channel or returns an equivalent existing channel

Authorizations:
application_authorization
Request Body schema: application/json
type
required
string
ChatUserIdReference (object) or ChatUserUsernameReference (object)
Array of ChatUserIdReference (object) or ChatUserUsernameReference (object) unique

List of user references of members of this channel

object

Custom data associated with this channel

name
string

The unique name of this channel used to reference the channel. If absent defaults to a random UUID

displayName
string

Human readable name of this channel shown to users. If absent defaults to the channel name

Responses

Request samples

Content type
application/json
Example
{
  • "type": "PUBLIC",
  • "name": "b0a0bd55-921a-4f72-8ee3-f26c6fda0bb7"
}

Response samples

Content type
Example
{}

Retrieve a channel

Returns a channel by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/55913' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
Example
{}

Delete a channel

Deletes a channel by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Responses

Request samples 

curl --location --request 'DELETE' \
  'https://api.chatkitty.com/v1/channels/55913' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Update a channel

Updates a channel properties

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema: application/json+merge-patch
displayName
string

Updates human readable name of this channel

object

Updates custom data associated with this channel

Responses

Request samples

Content type
application/json+merge-patch
{
  • "displayName": "A chatty channel"
}

Response samples

Content type
Example
{}

Send a channel event

Sends a custom channel event

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema: application/json
type
required
string

Custom type of this event

required
object

Custom data associated with this event

Responses

Request samples

Content type
application/json
{
  • "type": "My Custom Event",
  • "properties": {
    }
}

Response samples

Content type
{}

List channel invites

Returns a page of invites sent to join this channel

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/67026/invites?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Send a channel invite

Sends a channel invite to user

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema: application/json
required
ChatUserIdReference (object) or ChatUserUsernameReference (object)
One of
id
required
integer <int64>

User ID associated with this user

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
{}

Send channel keystrokes

Sends keystrokes in this channel on behalf of a user

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>
Request Body schema: application/json
keys
required
string
required
ChatUserIdReference (object) or ChatUserUsernameReference (object)

Responses

Request samples

Content type
application/json
{
  • "keys": "string",
  • "user": {
    }
}

Response samples

Content type
{
  • "keys": "string",
  • "username": "string",
  • "_links": {
    }
}

List a channel's members

Returns a page of channel members

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/67026/members?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Add a channel member

Makes a user a group channel member

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema: application/json
One of
id
required
integer <int64>

User ID associated with this user

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane@chatkitty.com"
}

Response samples

Content type
Example
{}

Remove a channel member

Removes a member from a group channel

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

user_id
required
integer <int64>

User ID of member to be removed

Responses

Request samples 

curl --location --request 'DELETE' \
  'https://api.chatkitty.com/v1/channels/55913/members/14503' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
Example
{}

List channel memberships

Returns a page of channel membership info for this channel

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/702/memberships?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

List channel messages

Returns a page of messages sent in this channel

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
size
integer <int32>

The size of the page to be returned

start
integer <int64>

Start cursor value. Do not set manually. Provided by the Platform API pagination engine to fetch previous or next pages

next
integer <int64>

Next page cursor value. Do not set manually. Provided by the Platform API pagination engine to fetch subsequent pages

relation
string
Enum: "SELF" "PREVIOUS" "NEXT"

Page cursor relation. Do not set manually. Provided by the Platform API pagination engine to fetch previous or next pages

username
string
query
string

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/702/messages' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Send a channel message

Sends a message in this channel as the system or on behalf of a user

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema:
type
required
string
groupTag
string

Optional string to associate this message with other messages. Can be used to group messages into a gallery

object

Custom data associated with this message

ChatUserIdReference (object) or ChatUserUsernameReference (object)
body
required
string

The text body of this message

Responses

Request samples

Content type
Example
{
  • "type": "TEXT",
  • "body": "Hello, World!"
}

Response samples

Content type
Example
{}

Lists a channel's moderators

Returns a page of channel moderators

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/67026/moderators?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Add a channel moderator

Makes a user a group channel moderator

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

Request Body schema: application/json
One of
id
required
integer <int64>

User ID associated with this user

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane@chatkitty.com"
}

Response samples

Content type
{}

Remove a channel moderator

Removes a moderator from a group channel

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

user_id
required
integer <int64>

User ID of moderator to be removed

Responses

Request samples 

curl --location --request 'DELETE' \
  'https://api.chatkitty.com/v1/channels/55913/moderators/14503' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
Example
{}

List channel participants

Returns a page of channel active participants: members that currently online

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Channel ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/channels/702/participants?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Chat Sessions

Chat session operations

List chat sessions

Returns a page of chat sessions belonging to this application

Authorizations:
application_authorization
query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

state
string
Enum: "ACTIVE" "ENDED"

Filters by state

Responses

Response samples

Content type
{}

Chat Function Versions

Chat function version operations

Retrieve a chat function version

Returns a chat function version by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function version ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/function-versions/13515' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{
  • "id": 13515,
  • "versionNumber": 34,
  • "handlerScript": "const logs = [];\n\nasync function handleEvent(event: UserAttemptedStartSessionEvent, context: Context) {\n let email = event.username;\n let displayName = event.authParams.displayName || email;\n\n let userApi = context.getUserApi();\n\n logs.push('Hello ' + event.username);\n\n await userApi.getUserExists(email)\n .catch(async () => {\n let user = await userApi.createUser(\n {\n 'name': email,\n 'displayName': displayName\n }\n );\n\n let channelApi = context.getChannelApi();\n\n await channelApi.createChannelMember(702, { 'id': user.data.id });\n });\n\n return logs;\n}",
  • "_links": {}
}

Chat Functions

Chat function operations

Retrieve a chat function

Returns a chat function by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/functions/1' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Retrieve chat function current version

Returns the version of this chat function currently deployed

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/functions/13515/current-version' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{
  • "id": 13515,
  • "versionNumber": 34,
  • "handlerScript": "const logs = [];\n\nasync function handleEvent(event: UserAttemptedStartSessionEvent, context: Context) {\n let email = event.username;\n let displayName = event.authParams.displayName || email;\n\n let userApi = context.getUserApi();\n\n logs.push('Hello ' + event.username);\n\n await userApi.getUserExists(email)\n .catch(async () => {\n let user = await userApi.createUser(\n {\n 'name': email,\n 'displayName': displayName\n }\n );\n\n let channelApi = context.getChannelApi();\n\n await channelApi.createChannelMember(702, { 'id': user.data.id });\n });\n\n return logs;\n}",
  • "_links": {}
}

List chat function invocations

Returns a page of invocations of this chat function. A log of previous runs of the function

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/functions/1/invocations?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

List chat function versions

Returns a page of versions of this chat function

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function ID

query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/functions/1/versions?page=0&size=25' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{
  • "_embedded": {
    },
  • "_links": {},
  • "page": {
    }
}

Create a chat function version

Creates a new version of this chat function

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Chat function ID

Request Body schema: application/json
handlerScript
required
string

JavaScript/TypeScript code that runs when this function is executed

Responses

Request samples

Content type
application/json
{
  • "handlerScript": "const logs = [];\n\nasync function handleEvent(event: UserAttemptedStartSessionEvent, context: Context) {\n let email = event.username;\n let displayName = event.authParams.displayName || email;\n\n let userApi = context.getUserApi();\n\n logs.push('Hello ' + event.username);\n\n await userApi.getUserExists(email)\n .catch(async () => {\n let user = await userApi.createUser(\n {\n 'name': email,\n 'displayName': displayName\n }\n );\n\n let channelApi = context.getChannelApi();\n\n await channelApi.createChannelMember(702, { 'id': user.data.id });\n });\n\n return logs;\n}"
}

Response samples

Content type
{
  • "id": 13515,
  • "versionNumber": 34,
  • "handlerScript": "const logs = [];\n\nasync function handleEvent(event: UserAttemptedStartSessionEvent, context: Context) {\n let email = event.username;\n let displayName = event.authParams.displayName || email;\n\n let userApi = context.getUserApi();\n\n logs.push('Hello ' + event.username);\n\n await userApi.getUserExists(email)\n .catch(async () => {\n let user = await userApi.createUser(\n {\n 'name': email,\n 'displayName': displayName\n }\n );\n\n let channelApi = context.getChannelApi();\n\n await channelApi.createChannelMember(702, { 'id': user.data.id });\n });\n\n return logs;\n}",
  • "_links": {}
}

Imports

Import user, channel, message data into your ChatKitty application

Import channels

Batch imports channels from a JSON array file

Learn more about importing channels and the channel import JSON array file format
Authorizations:
application_authorization
Request Body schema: multipart/form-data
file
required
string <binary>

JSON array file with channels

Responses

Request samples 

curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/imports/channels' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@channels_import_file.json;type=application/json

Response samples

Content type
{}

Import channel members

Batch imports channel members from a JSON array file

Learn more about importing channel members and the channel member import JSON array file format
Authorizations:
application_authorization
path Parameters
id
required
integer <int64>
Request Body schema: multipart/form-data
file
required
string <binary>

JSON array file with user references to be added as members

Responses

Request samples 

curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/imports/channels/1/members' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@members_import_file.json;type=application/json

Response samples

Content type
{}

Import messages

Batch imports messages from a JSON array file

Learn more about importing messages and the message import JSON array file format
Authorizations:
application_authorization
Request Body schema: multipart/form-data
file
required
string <binary>

JSON array file with messages

Responses

Request samples 

curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/imports/messages' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@messages_import_file.json;type=application/json

Response samples

Content type
{}

Import users

Batch imports users from a JSON array file

Learn more about importing users and the user import JSON array file format
Authorizations:
application_authorization
Request Body schema: multipart/form-data
file
required
string <binary>

JSON array file with users

Responses

Request samples 

curl --location --request 'POST' \
  'https://api.chatkitty.com/v1/imports/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@users_import_file.json;type=application/json

Response samples

Content type
{}

Jobs

Retrieve information about long running scheduled jobs like imports and exports

List jobs

Returns a page of jobs created for this application

Authorizations:
application_authorization
query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 25

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

running
boolean

Filters for jobs currently running

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/jobs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Retrieve a job

Returns a job by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Job ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/jobs/1' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Messages

Operations to retrieve, update and delete messages

List messages

Returns a page of messages belonging to this application

Authorizations:
application_authorization
query Parameters
size
integer <int32>

The size of the page to be returned

start
integer <int64>

Start cursor value. Do not set manually. Provided by the Platform API pagination engine to fetch previous or next pages

next
integer <int64>

Next page cursor value. Do not set manually. Provided by the Platform API pagination engine to fetch subsequent pages

relation
string
Enum: "SELF" "PREVIOUS" "NEXT"

Page cursor relation. Do not set manually. Provided by the Platform API pagination engine to fetch previous or next pages

username
string

Filters messages by a sender's username

query
string

Filters text messages by text contained in the message body

Responses

Request samples 

curl --location --request  'GET' \
  'https://api.chatkitty.com/v1/messages' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Delete messages

Deletes all messages belonging to this application

Authorizations:
application_authorization

Responses

Request samples 

curl --location --request 'DELETE' \
  'https://api.chatkitty.com/v1/messages' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Retrieve a message

Returns a message by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Message ID

Responses

Request samples 

curl --location --request 'GET' \
  'https://api.chatkitty.com/v1/messages/44902' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
Example
{}

Delete a message

Deletes a message by ID

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Message ID

Responses

Request samples 

curl --location --request 'DELETE' \
  'https://api.chatkitty.com/v1/messages/67528' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN'

Response samples

Content type
{}

Update a message

Updates a message properties

Authorizations:
application_authorization
path Parameters
id
required
integer <int64>

Message ID

Request Body schema: application/json+merge-patch
body
string

Updates the text body of this message

object

Updates custom data associated with this message

Responses

Request samples

Content type
application/json+merge-patch
{
  • "body": "string",
  • "properties": { }
}

Response samples

Content type
Example
{
  • "id": 44902,
  • "type": "TEXT",
  • "channelId": 702,
  • "user": {
    },
  • "body": "🌞",
  • "properties": { },
  • "createdTime": "2021-09-16T20:45:33.696Z",
  • "_links": {