{ "openapi": "3.0.0", "info": { "title": "Chat API", "description": "API endpoints for chat functionality.", "version": "1.0.0" }, "servers": [ { "url": "https://api.us-1.platform.polyai.app", "description": "Hostname for US-1 region" }, { "url": "https://api.uk-1.platform.polyai.app", "description": "Hostname for UK-1 region" }, { "url": "https://api.euw-1.platform.polyai.app", "description": "Hostname for EUW-1 region" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "You must request an API Key to use PolyAI APIs." }, "TokenAuth": { "type": "apiKey", "in": "header", "name": "X-TOKEN", "description": "Authentication token provisioned in Agent Studio." } }, "parameters": { "ApiKeyHeader": { "name": "X-API-KEY", "in": "header", "description": "Your PolyAI API key.", "required": true, "schema": { "type": "string" } }, "TokenHeader": { "name": "X-TOKEN", "in": "header", "description": "Agent authentication token (connector).", "required": true, "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "description": "Standard PolyAI API error envelope.", "required": [ "success", "error", "error_id", "error_code", "error_message", "data" ], "properties": { "success": { "type": "boolean", "description": "Always false for error responses.", "example": false }, "error": { "type": "string", "description": "Human-readable error message." }, "error_id": { "type": "string", "description": "Unique request identifier from the X-PolyAI-Correlation-Id header. Include this when contacting support." }, "error_code": { "type": "string", "description": "Machine-readable error code in UPPER_SNAKE_CASE." }, "error_message": { "type": "string", "description": "Human-readable error message." }, "data": { "nullable": true, "description": "Always null for error responses." } } }, "CreateChatRequest": { "type": "object", "properties": { "integration_attributes": { "type": "object", "description": "Custom metadata passed from external integrations. Accessible in functions via conv.integration_attributes.", "example": { "customer_id": "12345", "source": "mobile_app" } }, "variant_id": { "type": "string", "description": "Specify which variant to use for this conversation. Useful for multi-site deployments.", "example": "VARIANT-xxxxxxxx" }, "channel": { "type": "string", "description": "Channel identifier for the conversation.", "example": "webchat", "enum": [ "webchat", "whatsapp", "sms", "api" ] }, "asr_lang_code": { "type": "string", "description": "Language code for speech recognition (ISO 639-1 with region).", "example": "en-US" }, "tts_lang_code": { "type": "string", "description": "Language code for text-to-speech (ISO 639-1 with region).", "example": "en-US" } } }, "CreateChatResponse": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "Unique ID for the created conversation", "example": "CONV-1234567890" }, "response": { "type": "string", "description": "Initial response message from the agent", "example": "Hi, how can I help?" } }, "required": [ "conversation_id", "response" ] }, "RespondChatRequest": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "ID of the conversation to respond to", "example": "CONV-1234567890" }, "message": { "type": "string", "description": "Message to send to the agent", "example": "Hello again" } }, "required": [ "conversation_id" ] }, "RespondChatResponse": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "ID of the conversation", "example": "CONV-1234567890" }, "response": { "type": "string", "description": "Response message from the agent", "example": "Transferring you to an agent." }, "end_conversation": { "type": "boolean", "description": "Whether the conversation should be ended", "example": true }, "handoff": { "type": "object", "description": "Information about handoff if applicable", "properties": { "destination": { "type": "string", "description": "Destination for the handoff", "example": "live_agent_queue" }, "reason": { "type": "string", "description": "Reason for the handoff", "example": "billing_question" } } } }, "required": [ "conversation_id", "response", "end_conversation" ] }, "CloseChatRequest": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "ID of the conversation to close", "example": "CONV-1234567890" } }, "required": [ "conversation_id" ] }, "CloseChatResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the conversation was successfully closed", "example": true } }, "required": [ "success" ] } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/{version}/{account_id}/{project_id}/chat/create": { "post": { "operationId": "chatCreate", "summary": "Create a new chat conversation", "description": "Creates a new chat conversation and returns the conversation ID along with the agent's initial response.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyHeader" }, { "$ref": "#/components/parameters/TokenHeader" }, { "name": "version", "in": "path", "description": "API version", "required": true, "schema": { "type": "string" }, "example": "v1" }, { "name": "account_id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "string" }, "example": "ACCOUNT-xxxxxxxx" }, { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string" }, "example": "PROJECT-xxxxxxxx" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatRequest" } } } }, "security": [ { "ApiKeyAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChatResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "The draft you are attempting to chat with does not exist.", "error_id": "550e8400-e29b-41d4-a716-446655440000", "error_code": "CHAT_DRAFT_NOT_EXIST", "error_message": "The draft you are attempting to chat with does not exist.", "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{version}/{account_id}/{project_id}/chat/respond": { "post": { "operationId": "chatRespond", "summary": "Send a message to an existing chat conversation", "description": "Sends a user message to an existing conversation and returns the agent's response.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyHeader" }, { "$ref": "#/components/parameters/TokenHeader" }, { "name": "version", "in": "path", "description": "API version", "required": true, "schema": { "type": "string" }, "example": "v1" }, { "name": "account_id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "string" }, "example": "ACCOUNT-xxxxxxxx" }, { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string" }, "example": "PROJECT-xxxxxxxx" } ], "security": [ { "ApiKeyAuth": [] }, { "TokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespondChatRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespondChatResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Chat session exceeded the timeout limit.", "error_id": "550e8400-e29b-41d4-a716-446655440000", "error_code": "CHAT_TIMEOUT", "error_message": "Chat session exceeded the timeout limit.", "data": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{version}/{account_id}/{project_id}/chat/close": { "put": { "operationId": "chatClose", "summary": "Close an existing chat conversation", "description": "Closes an active chat conversation and marks it as complete.", "parameters": [ { "$ref": "#/components/parameters/ApiKeyHeader" }, { "$ref": "#/components/parameters/TokenHeader" }, { "name": "version", "in": "path", "description": "API version", "required": true, "schema": { "type": "string" }, "example": "v1" }, { "name": "account_id", "in": "path", "description": "Account ID", "required": true, "schema": { "type": "string" }, "example": "ACCOUNT-xxxxxxxx" }, { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string" }, "example": "PROJECT-xxxxxxxx" } ], "security": [ { "ApiKeyAuth": [] }, { "TokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseChatRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseChatResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/InternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "TokenAuth": [] } ] }