Skip to content

Instantly share code, notes, and snippets.

@Shmarkus

Shmarkus/genesys.yaml

Created December 7, 2020 12:49
Show Gist options
  • Save Shmarkus/a40c6b82b73a19aad2c61b572b93b4b9 to your computer and use it in GitHub Desktop.
Save Shmarkus/a40c6b82b73a19aad2c61b572b93b4b9 to your computer and use it in GitHub Desktop.
Download ZIP
Genesys OpenAPI 3 spec
Raw
genesys.yaml
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