8x8 Contact Center Chat API v2 for creating and driving chat conversations, messages and participants inside the contact center.
{
"openapi": "3.0.0",
"info": {
"title": "8x8 Contact Center Chat API V2",
"description": "Integration with the 8x8 Contact Center (CC) Chat API enables you to:\n* Respond in real time to your customer's chat inquiries\n* Initiate chat conversations between your customers and agents\n* Quickly access customer account information in order to better facilitate and enhance your agent's chat session\n* Allocate your company's resources to best address customer chat requirements\n* Review conversation information between your customer and the chat message receiving bot\n* Forward system events (e.g., agent joining conversation, agent ending conversation) to chat seesion stakeholders\n* Manage customer chats in your agent's supported language(s) or use the automatic translation tool\n\nThe 2 way API communication is achieved by using callbacks from 8x8's platform to your subscribed URIs. ",
"contact": {
"email": "cc-cluj-oncall@8x8.com"
},
"version": "2.0"
},
"servers": [
{
"url": "https://api.8x8.com"
}
],
"tags": [
{
"name": "Authentication",
"description": "Creates access tokens for endpoint access."
},
{
"name": "Info",
"description": "General information about the API."
},
{
"name": "WebHooks",
"description": "Enables webhook definitions that can be associated to channels."
},
{
"name": "JwkKeys",
"description": "An API that offers JWK public key access to customers."
},
{
"name": "Channels",
"description": "Enables ChatAPI channel registration and association with a webhook containing channel."
},
{
"name": "Conversations",
"description": "Provides Contact Center interaction capabilities."
}
],
"paths": {
"/oauth/v2/token": {
"post": {
"tags": ["Authentication"],
"summary": "Creates a new access token that can be used for API access.",
"description": "Creates a new access token that can be used for API access.",
"operationId": "createaccesstoken",
"security": [
{
"8x8APIBasic": ["basic"]
}
],
"requestBody": {
"description": "Defines the create transaction request payload.",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"properties": {
"grant_type": {
"enum": ["client_credentials"],
"default": "client_credentials"
}
},
"required": ["grant_type"]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/AuthResponse"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/RequestOAuthProblem"
},
"401": {
"$ref": "#/components/responses/RequestOAuthProblem"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/RequestOAuthProblem"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/web-hooks": {
"get": {
"tags": ["WebHooks"],
"summary": "Retrieves all customer webhooks based on the associated token information.",
"description": "Retrieves all customer webhooks based on the associated token information.",
"operationId": "getwebhooks",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/PageSizeFilterOptional"
},
{
"$ref": "#/components/parameters/PageIndexFilterOptional"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHooksV2ListResult"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"post": {
"tags": ["WebHooks"],
"summary": "Creates a new customer webhook.",
"description": "Creates a new customer webhook.",
"operationId": "createwebhook",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2CreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "WebHook created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2Result"
}
}
}
},
"400": {
"$ref": "#/components/responses/RequestValidationV2Problem"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/web-hooks/{web-hook-id}": {
"get": {
"tags": ["WebHooks"],
"summary": "Get webhook by Id.",
"description": "Retrieves the webhook by the provided Id.",
"operationId": "getwebhookbyid",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/WebHookUrlID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2Result"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"put": {
"tags": ["WebHooks"],
"summary": "Updates the full webhook resource by Id.",
"description": "Updates the full webhook resource by Id.",
"operationId": "updatewebhook",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/WebHookUrlID"
},
{
"$ref": "#/components/parameters/NumbericVersionMatchPreconditionOptional"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2PutRequest"
}
}
}
},
"responses": {
"200": {
"description": "Webhook successfully updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2Result"
}
}
}
},
"400": {
"$ref": "#/components/responses/RequestValidationV2Problem"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"delete": {
"tags": ["WebHooks"],
"summary": "Deletes the webhook by Id.",
"description": "Deletes the webhook by Id.",
"operationId": "deletewebhookbyid",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/WebHookUrlID"
}
],
"responses": {
"204": {
"description": "A deleted resource."
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/web-hooks/verify": {
"post": {
"tags": ["WebHooks"],
"summary": "The endpoint used to validate that the webhook is working and reachable.",
"description": "Validates the webhook URL endpont from the connectivity point-of-view by sending a hello message and a 2xx success status code.",
"operationId": "verifywebhook",
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebHookV2VerifyRequest"
}
}
}
},
"security": [
{
"8x8APIBearerToken": ["vcc-chat.webhooks.read"]
}
],
"responses": {
"204": {
"description": "Webhook validated successfully."
},
"400": {
"$ref": "#/components/responses/RequestValidationV2Problem"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/jwk/{jwk-id}/public": {
"get": {
"tags": ["JwkKeys"],
"summary": "Returns the public JWK.",
"description": "Returns the public JWK that can be used to validate the message signature.",
"operationId": "getjwkpublickey",
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"name": "jwk-id",
"in": "path",
"description": "JWK UUID",
"required": true,
"schema": {
"type": "string",
"format": "string"
},
"example": "EXaiWfZe20eSjklZ70074w"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "string",
"example": {
"kty": "RSA",
"e": "AQAB",
"kid": "EXaiWfZe20eSjklZ70074w",
"n": "obq8u-Yq9VgIqsfOFftSr-TINYrL8xNWhYhJjYtPp5DTQK3g1_ylCl6HMmRnEgb9wlkNfk9iazvkOU_XvyZSdfHNm173FlX3YgAPj_snUnCDO1Y0b0M4trK-iGUJP4A_tT4XauI1YJ96rEQAHzfOvsnnniFVqlK5pAMKWnVD4LhRbaEFLOnvMuNCiB13CPF7ZY4j7Aahf8KKdSiBJDw9um1lw5gfKe2j2DN7UOPm5Msz_is-C343xVaJ81d8W9ihDCX9JgaZEYciol-224n6F_gmUMWIfTTCRK3GC2_fnEXXWQbQvACA28Zf40h9iXiWiVdIXFGQgz2lQ7dg4ksUvw"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"description": "Contains a descriptive information.",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "string",
"description": "A string that identifies the Error code class.",
"example": "ClientError"
},
"title": {
"type": "string",
"description": "A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non technical stakeholders and\nnot localized); \n",
"example": "Resource not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code generated by the origin server for this problem occurrence.\n",
"minimum": 100,
"maximum": 600,
"exclusiveMaximum": true,
"example": 404
},
"detail": {
"type": "string",
"description": "Could not locate the resource. The resource may not exist or is not accessible.\n",
"example": "Resource may not exist or is not accessible."
},
"resourceType": {
"type": "string",
"format": "string",
"example": "JWKPublic"
},
"resourceId": {
"type": "string",
"format": "string",
"example": "EXaiWfZe20eSjklZ70074w"
},
"instance": {
"type": "string",
"format": "string",
"description": "The specific error code that points to the problem. It is a subclass of the Type error code class.\n",
"example": "ResourceNotFound"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/channels": {
"get": {
"tags": ["Channels"],
"summary": "Retrieves all customer Chat API channels.",
"description": "Retrieves all customer Chat API channels based on the provided access token information.",
"operationId": "getchatapichannels",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.channels.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/PageSizeFilterOptional"
},
{
"$ref": "#/components/parameters/PageIndexFilterOptional"
},
{
"$ref": "#/components/parameters/SortByOptional"
},
{
"$ref": "#/components/parameters/FilterOptional"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelsV2ListResult"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"post": {
"tags": ["Channels"],
"summary": "Creates a channel.",
"description": "Create a new channel for a customer.",
"operationId": "createchatapichannel",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.channels.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV2CreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Channel created successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV2Result"
}
}
}
},
"400": {
"$ref": "#/components/responses/ValidationExceptionPayload"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/channels/{channel-id}": {
"get": {
"tags": ["Channels"],
"summary": "Get ChatAPI channel by Id.",
"description": "Retrieves ChatAPI channel by Id.",
"operationId": "getchatapichannel",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.channels.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/ChatAPIChannelUrlID"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV2Result"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"put": {
"tags": ["Channels"],
"summary": "Update ChatAPI channel by Id.",
"description": "Update ChatAPI channel by Id.",
"operationId": "updatechatapichannel",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.channels.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/ChatAPIChannelUrlID"
},
{
"$ref": "#/components/parameters/NumbericVersionMatchPreconditionOptional"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV2PutRequest"
}
}
}
},
"responses": {
"200": {
"description": "Channel updated succesfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChannelV2Result"
}
}
}
},
"400": {
"$ref": "#/components/responses/RequestValidationV2Problem"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"delete": {
"tags": ["Channels"],
"summary": "Delete ChatAPI channel by Id.",
"description": "Deletes ChatAPI channel by the provided Id.",
"operationId": "deletechatapichannelbyid",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.channels.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/ChatAPIChannelUrlID"
}
],
"responses": {
"204": {
"description": "Deleted resource."
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/conversations": {
"get": {
"tags": ["Conversations"],
"summary": "Returns all conversations belonging to the customer.",
"description": "Returns a list of all conversations belonging to the customer that comply with the provided filters.",
"operationId": "getcctransactions",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.conversations.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/PageSizeFilterOptional"
},
{
"$ref": "#/components/parameters/PageIndexFilterOptional"
},
{
"$ref": "#/components/parameters/ChannelIdFilterOptional"
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Transaction status",
"schema": {
"anyOf": [
{
"type": "string",
"x-extensible-enum": ["all"],
"default": "all"
},
{
"$ref": "#/components/schemas/TransactionStatus"
}
]
}
},
{
"name": "order",
"in": "query",
"required": false,
"description": "The order results that are based on create time.",
"schema": {
"type": "string",
"enum": ["asc", "desc"],
"default": "asc"
}
},
{
"name": "userId",
"in": "query",
"required": false,
"description": "Filters orders by userId.",
"schema": {
"type": "string",
"format": "string"
}
},
{
"name": "customer.email",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "string",
"default": "email"
}
},
{
"name": "customer.<anyCustomerKeyName>",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "string",
"default": "customerKeyValue"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationListResult"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
},
"post": {
"tags": ["Conversations"],
"summary": "Creates a new conversation.",
"description": "Creates a new transaction in the Contact Center and returns a conversation Id as an identifier that can be used later on to send messages to agent and also close the ongoing transaction.",
"operationId": "createcctransaction",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.conversations.write"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
}
],
"requestBody": {
"$ref": "#/components/requestBodies/CreateTransactionRequestBody"
},
"responses": {
"202": {
"description": "Transaction accepted.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/ConversationIdentifierField"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/RequestValidationV2Problem"
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/conversations/{conversation-id}": {
"get": {
"tags": ["Conversations"],
"summary": "Retrieves conversation details.",
"description": "Retrieves conversation details.",
"operationId": "getcctransaction",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.conversations.read"]
}
],
"parameters": [
{
"$ref": "#/components/parameters/RegionParam"
},
{
"$ref": "#/components/parameters/TenantIdPathParam"
},
{
"$ref": "#/components/parameters/ChatAPIConversationUrlID"
}
],
"responses": {
"200": {
"description": "Returns the conversation details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationResult"
}
}
}
},
"401": {
"$ref": "#/components/responses/UnauthorizedResponse"
},
"403": {
"$ref": "#/components/responses/ForbiddenRequestResponse"
},
"404": {
"$ref": "#/components/responses/ResourceNotFoundResponse"
},
"500": {
"$ref": "#/components/responses/InternalServerErrorResponse"
},
"default": {
"$ref": "#/components/responses/InternalServerErrorResponse"
}
}
}
},
"/vcc/{region}/chat/v2/tenant/{tenant-id}/conversations/{conversation-id}/participants": {
"get": {
"tags": ["Conversations"],
"summary": "Retrieve the conversation participants.",
"description": "Retrieves all the participants that joined during the lifespan of the conversation.",
"operationId": "getparticipantsforcctransaction",
"security": [
{
"8x8APIBearerToken": ["vcc-chat.conversations.read"]
}
],
"parameters": [
{
"$ref": "#/components/param
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-actions-events-8x8-contact-center-chat-api-v2.json