This repository was archived by the owner on Dec 8, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathparloa-chat-v2.yml
430 lines (398 loc) · 14.1 KB
/
parloa-chat-v2.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
openapi: 3.0.0
info:
description: |
API specification of the parloa TextchatV2 API.
<h2 id="description-summary">Summary</h2>
Parloa's TextchatV2 API enables integrators to interact with a parloa textchat bot in their chat system or application.
The API follows a simple request-response pattern, the API consists of only one endpoint that
expects TextchatV2 events via TextchatV2Request and responds with a TextchatV2Response.
<h2 id="description-lifecyle">Conversation Protocol</h2>
An interaction with a textchat bot has to follow the protocol:
1. The first interaction has to initiate a conversation via `TextchatV2LaunchEvent`,
the bot will then directly respond with a welcome message.
2. Until the bot doesn't respond with `endConversation=true` the conversation will be kept
open, the conversation can also be terminated from the client side by sending a `TextchatV2QuitEvent`.
3. Over the lifetime of the conversation `TextchatV2MessageEvent` is used to notify responses from
a user to a bot.
<h2 id="description-authentication">Authentication</h2>
To authenticate against textchat bot, the dialoghook webhook has to be invoked with a Bearer token
that contains the apiToken that was created during the textchat bot's release creation.
[Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/):
```
Authorization: Bearer <apiToken>
```
version: 0.0.1
title: Parloa TextchatV2 API
contact:
email: [email protected]
tags:
- name: Chat
description: Chat api
servers:
- url: http://localhost
description: The development system (Docker)
- url: http://localhost:8081
description: The development system (No-Docker)
- url: https://app.parloa.com
description: The production system
- url: https://stage.parloa.com
description: The staging system
paths:
/dialoghook:
post:
operationId: send-chat-event
summary: "Send chat events to a textchat release and receive chat responses"
description: |
This endpoint expects to receive chat api events from a chat-adapter and responds with a chat response.
tags:
- "Chat"
parameters:
- name: dialog
description: |
The releaseId of Textchat 2 release which should receive the provided TextchatV2Request.
in: query
required: true
schema:
type: string
- name: platform
description: |
Must be "textchatV2".
in: query
required: true
schema:
type: string
enum:
- textchatV2
requestBody:
description: |
Have to be a textchatV2 event.
required: true
content:
application/json:
examples:
launchRequest:
summary: Starts a new conversation with textchat bot.
value:
apiVersion: "chat/v1"
requesterId: "<user-id>"
sessionId: "<session-id>"
event:
type: "launch"
messageRequest:
summary: Send a message to textchat bot.
value:
apiVersion: "chat/v1"
requesterId: "<user-id>"
sessionId: "<session-id>"
event:
type: "message"
text: "Hello textchat!"
quitRequest:
summary: Notifies to textchat bot that user quit the conversation.
value:
apiVersion: "chat/v1"
requesterId: "<user-id>"
sessionId: "<session-id>"
event:
type: "quit"
send-message-context:
summary: Send a message and context information to textchat bot.
value:
apiVersion: "chat/v1"
requesterId: "<user-id>"
sessionId: "<session-id>"
context:
- key: name
value: Max
- key: age
value: 20
event:
type: "message"
text: "Hello textchat!"
schema:
$ref: "#/components/schemas/TextchatV2RequestBody"
responses:
default:
description: Contains the response from TextchatV2 release
content:
application/json:
examples:
text-response:
summary: Textchat bot respond with a text message and the bot expects a response from the user
value:
apiVersion: "chat/v1"
requesterId: "user-id"
sessionId: "session-id"
releaseId: "release-id"
conversationId: "Unique identifier of the current on-going conversation"
transactionId: "Unique identifier for the current textchat bot interaction"
endConversation: false
responseElements:
- id: 0822093c-f18d-11ec-8ea0-0242ac120002
type: text
content: Greetings from the textchat bot.
- id: 3822093c-f1dd-11ec-8ea0-0242dc120002
type: text
content: How can I help you?.
bot-quits-conversation:
summary: Textchat bot gives a farewell and terminates the conversation.
value:
apiVersion: "chat/v1"
requesterId: "user-id"
sessionId: "session-id"
releaseId: "release-id"
conversationId: "Unique identifier of the current on-going conversation"
transactionId: "Unique identifier for the current textchat bot interaction"
endConversation: true
responseElements:
- id: 0822093c-f18d-11ec-8ea0-0242ac120002
type: text
content: Bye! See you later :)
bot-respond-with-json-payload:
summary: Textchat bot responds with json payload that was provided by bot designer.
value:
apiVersion: "chat/v1"
requesterId: "user-id"
sessionId: "session-id"
releaseId: "release-id"
conversationId: "Unique identifier of the current on-going conversation"
transactionId: "Unique identifier for the current textchat bot interaction"
endConversation: false
responseElements:
- id: 0822093c-f18d-11ec-8ea0-0242ac120002
type: payload
content:
suggestionChips:
- yes
- no
- not sure?
schema:
$ref: "#/components/schemas/TextchatV2ResponseBody"
components:
schemas:
TextchatV2Event:
oneOf:
- $ref: "#/components/schemas/TextchatV2LaunchEvent"
- $ref: "#/components/schemas/TextchatV2MessageEvent"
- $ref: "#/components/schemas/TextchatV2QuitEvent"
TextchatV2LaunchEvent:
additionalProperties: false
description: Notifies that a user requested to start a new chat interaction
properties:
type:
type: string
enum:
- launch
required:
- type
type: object
TextchatV2MessageEvent:
additionalProperties: false
description: Notifies that a user sends us a new message.
properties:
text:
description: The content of the text message
type: string
type:
type: string
enum:
- message
required:
- type
- text
type: object
TextchatV2QuitEvent:
additionalProperties: false
description: Notifies that a user leaved the conversation
properties:
type:
type: string
enum:
- quit
required:
- type
type: object
TextchatV2RequestBody:
additionalProperties: false
properties:
apiVersion:
description: The interface version of text chat api
type: string
enum:
- chat/v1
event:
$ref: "#/components/schemas/TextchatV2Event"
description: The event that was be reported by this request.
requesterId:
description: This identifier is used by parloa to identify an user. You should pass in here an identifier for the current user e.g. user-id.
type: string
sessionId:
description: The sessionId should match to the conversationId of the chat interaction of the chat widget. Parloa will use this session Id to remember the conversation state between a user and a parloa bot.
type: string
context:
description: Context information that can be passed over to a parloa-bot.
maxItems: 100
items:
$ref: "#/components/schemas/TextchatV2ContextItem"
type: array
required:
- apiVersion
- sessionId
- requesterId
- event
type: object
TextchatV2GenericCardResponseElement:
additionalProperties: false
properties:
content:
description: The content of the card is required unless a image is present.
type: string
id:
type: string
image:
additionalProperties: false
description: Images could be jpeg or png.
properties:
accessibilityText:
type: string
large:
additionalProperties: false
properties:
height:
type: string
url:
type: string
width:
type: string
required:
- url
type: object
small:
additionalProperties: false
properties:
height:
type: string
url:
type: string
width:
type: string
required:
- url
type: object
required:
- large
- small
type: object
subtitle:
description: The optional subtitle
type: string
title:
type: string
type:
type: string
enum:
- cross_card
required:
- type
type: object
TextchatV2JSONPayloadResponseElement:
additionalProperties: false
properties:
content:
additionalProperties: {}
type: object
type:
type: string
enum:
- payload
required:
- type
- content
type: object
TextchatV2ResponseBody:
additionalProperties: false
properties:
apiVersion:
type: string
enum:
- chat/v1
conversationId:
description: The id is for the current conversation, can be used to lookup the analytics data via the analytics rest api.
type: string
endConversation:
description: Specifies if the conversation should end after this response
type: boolean
releaseId:
description: Id of the bot release that produces this response
type: string
requesterId:
description: This identifier is the same that was passed via the TextchatV2Request#requesterId it identifies an use that take part in a conversation.
type: string
responseElements:
description: Contains the response elements that were produced by the bot.
items:
$ref: "#/components/schemas/TextchatV2ResponseItem"
type: array
sessionId:
description: |-
This identifier is the same that was passed via the TextchatV2Request#sessionId it helps you identify one conversation.
Parloa will use this session Id to remember the conversation state between a user and a parloa bot.
type: string
transactionId:
description: |
Unique identifier for the interaction with the chat api. Should be reported together with bug reports.
NOTE: The transactionId will be replaced by the X-Request-Id and X-Correlation-Id headers.
type: string
deprecated: true
required:
- apiVersion
- releaseId
- sessionId
- requesterId
- responseElements
- endConversation
type: object
TextchatV2ResponseItem:
anyOf:
- $ref: "#/components/schemas/TextchatV2TextResponseElement"
- $ref: "#/components/schemas/TextchatV2JSONPayloadResponseElement"
- $ref: "#/components/schemas/TextchatV2GenericCardResponseElement"
TextchatV2ContextItem:
type: object
properties:
key:
description: |
The identifier of a context field that should be accessible in the bot via that name.
type: string
value:
description: The value of this context item that should be passed over to parloa bot
anyOf:
- type: string
maxLength: 1000
- type: number
- type: boolean
additionalProperties: false
required:
- key
- value
TextchatV2TextResponseElement:
additionalProperties: false
properties:
content:
type: string
id:
type: string
type:
type: string
enum:
- text
required:
- type
- content
type: object
securitySchemes:
BearerAuth:
type: http
scheme: bearer
security:
- BearerAuth: []