Created
December 7, 2020 12:49
-
-
Save Shmarkus/a40c6b82b73a19aad2c61b572b93b4b9 to your computer and use it in GitHub Desktop.
Genesys OpenAPI 3 spec
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| openapi: 3.0.0 | |
| info: | |
| title: Chat API Version 2 | |
| description: Use this API for Web Chat (replacement for eServices WebAPI Chat) | |
| version: 8.5.2 | |
| tags: | |
| - name: chat | |
| description: Chat services | |
| paths: | |
| /{serviceName}: | |
| post: | |
| tags: | |
| - chat | |
| summary: Request Chat | |
| operationId: requestChat | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| firstName: | |
| description: First name of the customer (either nickname or both firstName and lastName should be supplied) | |
| type: string | |
| lastName: | |
| description: Last name of the customer (either nickname or both firstName and lastName should be supplied) | |
| type: string | |
| nickname: | |
| description: Customer's nickname (either nickname or both firstName and lastName should be supplied) | |
| type: string | |
| subject: | |
| description: Subject as entered by the customer | |
| type: string | |
| emailAddress: | |
| description: email address of the customer | |
| type: string | |
| required: | |
| - firstName | |
| - lastName | |
| - nickname | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ChatRequestResponse" | |
| /{serviceName}/{chatId}/send: | |
| post: | |
| tags: | |
| - chat | |
| summary: Send Message | |
| description: "" | |
| operationId: sendMessage | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| message: | |
| description: Text message to send | |
| type: string | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| messageType: | |
| description: Any arbitrary type that the user wants to set | |
| type: string | |
| transcriptPosition: | |
| description: Including this parameter enables the return of the transcription and it sets the position in the transcript from where it should be retrieved. | |
| type: string | |
| required: | |
| - message | |
| - userId | |
| - secureKey | |
| - alias | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| /{serviceName}/{chatId}/startTyping: | |
| post: | |
| tags: | |
| - chat | |
| summary: Start Typing | |
| description: "" | |
| operationId: startTyping | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| message: | |
| description: Message if any | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| /{serviceName}/{chatId}/stopTyping: | |
| post: | |
| tags: | |
| - chat | |
| summary: Stop Typing | |
| description: "" | |
| operationId: stopTyping | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| message: | |
| description: Message, if any | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| /{serviceName}/{chatId}/refresh: | |
| post: | |
| tags: | |
| - chat | |
| summary: Refresh Chat | |
| description: > | |
| Refresh Chat requests a transcript of events from the specified chat. The value of the transcriptPosition parameter determines which events are returned: | |
| * If transcriptPosition is set to 0, none of the events from the chat are returned. | |
| * If transcriptPosition is set to 1, all of the events from the chat are returned. | |
| * Otherwise, the request returns any new events that have occurred since the event at the position number indicated in the transcriptPosition parameter. | |
| In addition to its usefulness in returning the above information, this request can be used to let Chat Server know that the web client that sent the request is still alive. | |
| operationId: refresh | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| transcriptPosition: | |
| description: > | |
| Index position in the transcript starting from which the messages should be retrieved | |
| * 0 (no messages) | |
| * 1 (all messages) | |
| * 2 (all messages starting from 2nd message) | |
| default: 1 | |
| minimum: 0 | |
| maximum: 2 | |
| type: integer | |
| message: | |
| description: > | |
| For use with Typing Preview at the agent chat window. Text that the user has entered so far in the chat box at the time this request is being made. This text will be submitted to the chat server along with notification TypingStarted. Property "typing_preview" must be enabled as described in Chat Services Options. | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/RefreshResponse" | |
| /{serviceName}/{chatId}/disconnect: | |
| post: | |
| tags: | |
| - chat | |
| summary: Disconnect | |
| operationId: disconnect | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/BaseResponse" | |
| /{serviceName}/{chatId}/pushUrl: | |
| post: | |
| tags: | |
| - chat | |
| summary: Push URL | |
| operationId: pushUrl | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| pushUrl: | |
| description: URL | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| - pushUrl | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| /{serviceName}/{chatId}/updateNickname: | |
| post: | |
| tags: | |
| - chat | |
| summary: Update Nickname | |
| operationId: updateNickname | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| nickname: | |
| description: New nickname | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| - nickname | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| /{serviceName}/{chatId}/readReceipt: | |
| post: | |
| tags: | |
| - chat | |
| summary: Read Receipt | |
| description: > | |
| Introduced in: **8.5.201.04** | |
| Use this operation to acknowledge that the user has read a given message or event. | |
| operationId: readReceipt | |
| parameters: | |
| - in: path | |
| name: serviceName | |
| required: true | |
| schema: | |
| type: string | |
| - in: path | |
| name: chatId | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| content: | |
| application/x-www-form-urlencoded: | |
| schema: | |
| type: object | |
| properties: | |
| userId: | |
| description: User ID | |
| type: string | |
| secureKey: | |
| description: Secure key | |
| type: string | |
| alias: | |
| description: Host alias | |
| type: string | |
| transcriptPosition: | |
| description: > | |
| The index of the event that the client app acknowledges having read. This is not the same index as nextPosition, but rather the index of the event from the "messages" array. | |
| type: string | |
| required: | |
| - userId | |
| - secureKey | |
| - alias | |
| - transcriptPosition | |
| responses: | |
| "200": | |
| description: OK | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/SendMessageResponse" | |
| servers: | |
| - url: http://localhost/genesys/2/chat | |
| components: | |
| schemas: | |
| BaseResponse: | |
| type: object | |
| properties: | |
| statusCode: | |
| type: integer | |
| format: int32 | |
| description: > | |
| * 0 indicates that the operation was successful and all fields in the response have valid values. | |
| * 1 indicates that there was an error and the client can keep trying until it receives a statusCode of 0 or until it decides to give up. | |
| > Note: When you receive this response, you cannot assume that the values of any other fields are valid. | |
| * 2 indicates that there was an error. | |
| minimum: 0 | |
| maximum: 2 | |
| alias: | |
| type: string | |
| description: Identifies the Chat Server instance that served this request. When provided, use it in subsequent API requests. This alias may change several times within the same session. | |
| userId: | |
| type: string | |
| description: Identifies this chat party (self). When provided, use it in subsequent API requests. | |
| secureKey: | |
| type: string | |
| description: Secured key for this session; use this key (valid only for this session) in each request. Make sure to protect this key. | |
| messages: | |
| type: array | |
| description: Contains full or partial chat transcript. See the Chat Transcript section below. | |
| items: | |
| $ref: "#/components/schemas/ChatTranscriptResource" | |
| ChatRequestResponse: | |
| allOf: | |
| - $ref: '#/components/schemas/BaseResponse' | |
| - type: object | |
| properties: | |
| chatId: | |
| description: Identifies current Chat Session id. When provided, use it in subsequent API requests. This value doesn't change during the chat session. | |
| type: string | |
| example: | |
| statusCode: 0 | |
| alias: 117 | |
| userId: 007555677B20000A | |
| secureKey: 4ee15d7e1c343c8e | |
| messages: | |
| - from: | |
| nickname: First Last | |
| participantId: 1 | |
| type: Client | |
| index: 1 | |
| type: ParticipantJoined | |
| utcTime: 1432845088000 | |
| chatId: 00048aAPEQJ8000U | |
| ChatTranscriptResource: | |
| type: object | |
| properties: | |
| from: | |
| $ref: "#/components/schemas/PartyResource" | |
| index: | |
| type: integer | |
| format: int32 | |
| description: Identifies serial number of this event within chat session, starts with 1 for the first event. | |
| type: | |
| $ref: "#/components/schemas/MessageTypeEnum" | |
| utcTime: | |
| type: integer | |
| format: int64 | |
| description: Indicates the event timestamp. | |
| text: | |
| type: string | |
| description: If available, contains the text associated with this event. | |
| messageType: | |
| type: string | |
| MessageTypeEnum: | |
| type: string | |
| description: Identifies the chat event type. | |
| enum: | |
| - ParticipantJoined | |
| - ParticipantLeft | |
| - Message | |
| - TypingStarted | |
| - TypingStopped | |
| - NicknameUpdated | |
| - PushUrl | |
| - FileUploaded | |
| - FileDeleted | |
| - CustomNotice | |
| - Notice | |
| - IdleAlert | |
| - IdleClose | |
| ParticipantType: | |
| type: string | |
| description: Describes the type of participant. "External" means that the event was not generated by a customer or an agent, but rather by an ESP request, received for example from the routing strategy. | |
| enum: | |
| - Agent | |
| - Client | |
| - External | |
| TenantEnum: | |
| type: string | |
| enum: | |
| - Resources | |
| PartyResource: | |
| type: object | |
| description: The from field of the chat event describes the party who generated this event | |
| properties: | |
| nickname: | |
| type: string | |
| description: The preferable calling [nick] name of the chat participant. | |
| participantId: | |
| type: integer | |
| format: int32 | |
| description: Identifier of this chat party. This identifier differs from the userId. The same party can join and leave several times the chat session. Each time that the party joins, it is assigned a new partyId even if it is the same agent. | |
| type: | |
| $ref: "#/components/schemas/ParticipantType" | |
| SendMessageResponse: | |
| allOf: | |
| - $ref: '#/components/schemas/BaseResponse' | |
| - type: object | |
| properties: | |
| chatEnded: | |
| type: boolean | |
| description: If true, indicates that the current chat session has ended. If false, the chat session is still ongoing. | |
| example: | |
| messages: | |
| - from: | |
| nickname: First Last | |
| participantId: 1 | |
| type: Client | |
| index: 7 | |
| text: hello | |
| messageType: null | |
| type: Message | |
| utcTime: 1432845541000 | |
| chatEnded: false | |
| statusCode: 0 | |
| alias: 117 | |
| secureKey: 3e2a69d421ae2672 | |
| userId: 007555677CB4000D | |
| RefreshResponse: | |
| allOf: | |
| - $ref: '#/components/schemas/BaseResponse' | |
| - type: object | |
| properties: | |
| tenantName: | |
| $ref: '#/components/schemas/TenantEnum' | |
| nextPosition: | |
| description: Indicates which event index to use to request a transcript in the next operation (used in Refresh Chat, and other requests) | |
| type: integer | |
| format: int32 | |
| example: | |
| messages: | |
| - from: | |
| nickname: AgentNick | |
| participantId: 3 | |
| type: Agent | |
| index: 7 | |
| text: hello | |
| type: Message | |
| utcTime: 1451961875000 | |
| chatEnded: false | |
| statusCode: 0 | |
| alias: 249 | |
| secureKey: 45327f306556129f | |
| userId: 00F9568B2DA601BA | |
| tenantName: Resources | |
| nextPosition: 8 | |
| ApiError: | |
| type: object | |
| description: Validation errors with an HTTP status code of 400 happen when any of the values necessary to complete an operation is missing. They have two different formats, depending on which release you are using | |
| properties: | |
| errors: | |
| type: array | |
| items: | |
| $ref: '#/components/schemas/ErrorCode' | |
| ErrorCode: | |
| type: object | |
| description: > | |
| | code | description | chat | email | openmedia | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 100-199 | Error messages in this range indicate that a required parameter is | | | | | |
| | | missing from a request. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 100 | RESERVED | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 101 | tenant is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 102 | firstName is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 103 | lastName is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 104 | subject is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 105 | userData is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 151 | alias is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 152 | userId is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 153 | secureKey is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 154 | chatId is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 161 | nickname is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 162 | message is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 163 | pushUrl is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 181 | fromAddress is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 182 | text is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 191 | mediaType is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 192 | interactionType is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 193 | interactionSubtype is missing. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 200-299 | Error messages in this range indicate that one or more of the | | | | | |
| | | parameters specified in a request is outside of the range configured| | | | | |
| | | in the Genesys Mobile Engagement application options. These errors | | | | | |
| | | include an advice field that displays the allowable range or limit. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 200 | RESERVED | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 201 | The total number of uploaded files is too high | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 202 | The total size of the uploaded files is too large | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 203 | The uploaded file has an incorrect filetype | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 240 | An unexpected error occurred. The advice field includes the Reference| | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | | ID that helps to identify the error cause in the GMS log file. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 241 | The specified file is not present in the current session. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 248 | The interaction with the specified ID was not found. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 249 | The Media Server was not able to execute the request. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 250-299 | Error messages in this range are not generated by Genesys Mobile | | | | | |
| | | Engagement but are provided directly by the connected Media Server | | | | | |
| | | (for example, Chat Server). | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 250 | RESERVED | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 261 | File Upload is not possible until an agent joins the session. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 264 | File was already deleted. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 300-399 | Error messages in this range indicate that a request parameter is | | | | | |
| | | malformed or invalid (for example, an invalid email address). | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 300 | RESERVED | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 306 | serviceName URL parameter is invalid (that is, not configured in the | | | | | |
| | | Genesys Mobile Engagement application). The HTTP status will be set | | | | | |
| | | to 404 - Not Found instead of 400 - Bad Request. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 364 | emailAddress contains an invalid email address. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 381 | fromAddress contains an invalid email address. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| | 383 | mailbox contains an invalid email address. | | | | | |
| |-----------|----------------------------------------------------------------------|---------|--------|-----------| | |
| properties: | |
| code: | |
| type: integer | |
| format: int64 | |
| advice: | |
| type: string | |
| example: "jpg,zip,txt,pdf,exe,bmp,gif,dll,png,doc" |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment