openapi: 3.1.0 info: title: Salesforce Service Cloud Salesforce Chat REST API description: >- REST API for managing live chat sessions between agents and visitors in Salesforce Service Cloud. Enables initiating chat sessions, sending and receiving messages, and monitoring chat activity. version: '59.0' contact: name: Salesforce Developer Support url: https://developer.salesforce.com/support termsOfService: https://www.salesforce.com/company/legal/agreements/ externalDocs: description: Chat REST API Developer Guide url: https://developer.salesforce.com/docs/atlas.en-us.live_agent_rest.meta/live_agent_rest/ servers: - url: https://{hostname}/chat/rest description: Chat REST API Endpoint variables: hostname: default: d.la1-c1-ia4.salesforceliveagent.com description: Your Live Agent endpoint hostname tags: - name: Availability description: Agent availability and routing - name: Messages description: Chat message operations - name: Sessions description: Chat session lifecycle management - name: Settings description: Chat deployment settings security: - apiKey: [] paths: /System/SessionId: get: operationId: getSessionId summary: Salesforce Service Cloud Get a new session ID description: >- Generates a unique session ID and key to establish a new chat session. This must be the first request made for every new chat. tags: - Sessions parameters: - $ref: '#/components/parameters/AffinityToken' responses: '200': description: Session ID and key content: application/json: schema: $ref: '#/components/schemas/SessionIdResponse' '403': description: Invalid API version or configuration /Chasitor/ChasitorInit: post: operationId: initiateChatSession summary: Salesforce Service Cloud Initiate a chat session description: >- Initiates a new chat request from a visitor, placing them in the queue for an available agent. tags: - Sessions requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChasitorInit' responses: '200': description: Chat session initiated '400': description: Invalid request parameters '503': description: No agents available /System/Messages: get: operationId: getMessages summary: Salesforce Service Cloud Get chat messages description: >- Returns all messages sent between agents and chat visitors during a chat session, including system messages and events. tags: - Messages parameters: - $ref: '#/components/parameters/SessionKey' - $ref: '#/components/parameters/AffinityToken' responses: '200': description: Chat messages content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' '403': description: Invalid session /Chasitor/ChatMessage: post: operationId: sendChatMessage summary: Salesforce Service Cloud Send a chat message description: >- Sends a chat message from the visitor to the agent during an active chat session. tags: - Messages requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatMessageRequest' responses: '200': description: Message sent successfully '403': description: Invalid session or chat ended /Visitor/Availability: get: operationId: checkAvailability summary: Salesforce Service Cloud Check agent availability description: >- Indicates whether a chat button is available to receive new chat requests based on agent availability and routing rules. tags: - Availability parameters: - name: org_id in: query required: true description: Salesforce organization ID schema: type: string - name: deployment_id in: query required: true description: Chat deployment ID schema: type: string - name: Availability.ids in: query required: true description: Comma-separated chat button IDs schema: type: string responses: '200': description: Availability status content: application/json: schema: $ref: '#/components/schemas/AvailabilityResponse' /Visitor/Settings: get: operationId: getSettings summary: Salesforce Service Cloud Get deployment settings description: >- Retrieves settings and configuration for a chat deployment, used to initialize the chat client. tags: - Settings parameters: - name: org_id in: query required: true description: Salesforce organization ID schema: type: string - name: deployment_id in: query required: true description: Chat deployment ID schema: type: string responses: '200': description: Deployment settings content: application/json: schema: $ref: '#/components/schemas/SettingsResponse' /Chasitor/ChatEnd: post: operationId: endChat summary: Salesforce Service Cloud End a chat session description: >- Ends the current chat session from the visitor side. tags: - Sessions responses: '200': description: Chat ended successfully '403': description: Invalid session components: securitySchemes: apiKey: type: apiKey in: header name: X-LIVEAGENT-API-VERSION description: Live Agent API version header parameters: SessionKey: name: X-LIVEAGENT-SESSION-KEY in: header required: true description: The session key from the SessionId response schema: type: string AffinityToken: name: X-LIVEAGENT-AFFINITY in: header required: true description: Affinity token for session routing schema: type: string schemas: SessionIdResponse: type: object properties: id: type: string description: The unique session ID key: type: string description: The session key for subsequent requests affinityToken: type: string description: Token for maintaining session affinity clientPollTimeout: type: integer description: Recommended polling interval in seconds ChasitorInit: type: object required: - organizationId - deploymentId - buttonId - sessionId - visitorName properties: organizationId: type: string description: Salesforce organization ID deploymentId: type: string description: Chat deployment ID buttonId: type: string description: Chat button ID sessionId: type: string description: Session ID from SessionId request visitorName: type: string description: Display name of the visitor prechatDetails: type: array items: type: object description: Pre-chat form field values MessagesResponse: type: object properties: messages: type: array items: $ref: '#/components/schemas/ChatMessage' description: Array of chat messages and events ChatMessage: type: object properties: type: type: string description: Type of message enum: - ChatMessage - AgentTyping - ChatEnded - ChatTransferred - AgentNotTyping - ChatEstablished message: type: object properties: text: type: string description: Message text content name: type: string description: Sender name ChatMessageRequest: type: object required: - text properties: text: type: string description: Message text to send AvailabilityResponse: type: object properties: messages: type: array items: type: object properties: type: type: string message: type: object properties: results: type: array items: type: object properties: id: type: string description: Chat button ID isAvailable: type: boolean description: Whether agents are available SettingsResponse: type: object properties: messages: type: array items: type: object description: Settings configuration messages