From 552e8b14c41aa01c538e9eda1bb6666adb098b38 Mon Sep 17 00:00:00 2001 From: Alan Perdomo Date: Fri, 13 Jan 2023 13:30:18 -0300 Subject: [PATCH] fix(gbminservice.ts): swagger-client migration from 2.0 to 3.0 --- directline-3.0.json | 731 ++++-------------- .../services/AzureDeployerService.ts | 46 +- .../basic.gblib/services/DialogKeywords.ts | 4 +- packages/basic.gblib/services/GBVMService.ts | 11 +- .../basic.gblib/services/vm2-process/index.ts | 2 +- packages/core.gbapp/services/GBMinService.ts | 24 +- 6 files changed, 208 insertions(+), 610 deletions(-) diff --git a/directline-3.0.json b/directline-3.0.json index f0ebc404..39755e98 100644 --- a/directline-3.0.json +++ b/directline-3.0.json @@ -3,7 +3,7 @@ "info": { "version": "v3", "title": "Bot Connector - Direct Line API - v3.0", - "description": "Direct Line 3.0\r\n===============\r\n\r\n\r\nThe Direct Line API is a simple REST API for connecting directly to a single bot. This API is intended for developers\r\nwriting their own client applications, web chat controls, mobile apps, or service-to-service applications that will\r\ntalk to their bot.\r\n\r\nWithin the Direct Line API, you will find:\r\n\r\n* An **authentication mechanism** using standard secret/token patterns\r\n* The ability to **send** messages from your client to your bot via an HTTP POST message\r\n* The ability to **receive** messages by **WebSocket** stream, if you choose\r\n* The ability to **receive** messages by **polling HTTP GET**, if you choose\r\n* A stable **schema**, even if your bot changes its protocol version\r\n\r\nDirect Line 1.1 and 3.0 are both available and supported. This document describes Direct Line 3.0. For information\r\non Direct Line 1.1, visit the [Direct Line 1.1 reference documentation](/en-us/restapi/directline/).\r\n\r\n# Authentication: Secrets and Tokens\r\n\r\nDirect Line allows you to authenticate all calls with either a secret (retrieved from the Direct Line channel\r\nconfiguration page) or a token (which you may get at runtime by converting your secret).\r\n\r\nA Direct Line **secret** is a master key that can access any conversation, and create tokens. Secrets do not expire.\r\n\r\nA Direct Line **token** is a key for a single conversation. It expires but can be refreshed.\r\n\r\nIf you're writing a service-to-service application, using the secret may be simplest. If you're writing an application\r\nwhere the client runs in a web browser or mobile app, you may want to exchange your secret for a token, which only\r\nworks for a single conversation and will expire unless refreshed. You choose which security model works best for you.\r\n\r\nYour secret or token is communicated in the ```Authorization``` header of every call, with the Bearer scheme.\r\nExample below.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other HTTP headers, omitted]\r\n```\r\n\r\nYou may notice that your Direct Line client credentials are different from your bot's credentials. This is\r\nintentional, and it allows you to revise your keys independently and lets you share client tokens without\r\ndisclosing your bot's password. \r\n\r\n## Exchanging a secret for a token\r\n\r\nThis operation is optional. Use this step if you want to prevent clients from accessing conversations they aren't\r\nparticipating in.\r\n\r\nTo exchange a secret for a token, POST to /v3/directline/tokens/generate with your secret in the auth header\r\nand no HTTP body.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/tokens/generate HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"expires_in\": 1800\r\n}\r\n```\r\n\r\nIf successful, the response is a token suitable for one conversation. The token expires in the seconds\r\nindicated in the ```expires_in``` field (30 minutes in the example above) and must be refreshed before then to\r\nremain useful.\r\n\r\nThis call is similar to ```/v3/directline/conversations```. The difference is that the call to\r\n```/v3/directline/tokens/generate``` does not start the conversation, does not contact the bot, and does not\r\ncreate a streaming WebSocket URL.\r\n* Call ```/v3/directline/conversations``` if you will distribute the token to client(s) and want them to \r\n initiate the conversation.\r\n* Call ```/v3/directline/conversations``` if you intend to start the conversation immediately.\r\n\r\n\r\n## Refreshing a token\r\n\r\nA token may be refreshed an unlimited number of times unless it is expired.\r\n\r\nTo refresh a token, POST to /v3/directline/tokens/refresh. This method is valid only for unexpired tokens.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/tokens/refresh HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\",\r\n \"expires_in\": 1800\r\n}\r\n```\r\n\t\r\n\r\n# REST calls for a Direct Line conversation\r\n\r\nDirect Line conversations are explicitly opened by clients and may run as long as the bot and client participate\r\n(and have valid credentials). While the conversation is open, the bot and client may both send messages. More than\r\none client may connect to a given conversation and each client may participate on behalf of multiple users.\r\n\r\n## Starting a conversation\r\n\r\nClients begin by explicitly starting a conversation. If successful, the Direct Line service replies with a\r\nJSON object containing a conversation ID, a token, and a WebSocket URL that may be used later.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 201 Created\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"expires_in\": 1800,\r\n \"streamUrl\": \"https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA...\"\r\n}\r\n```\r\n\r\nIf the conversation was started, an HTTP 201 status code is returned. HTTP 201 is the code that clients\r\nwill receive under most circumstances, as the typical use case is for a client to start a new conversation.\r\nUnder certain conditions -- specifically, when the client has a token scoped to a single conversation AND\r\nwhen that conversation was started with a prior call to this URL -- this method will return HTTP 200 to signify\r\nthe request was acceptable but that no conversation was created (as it already existed).\r\n\r\nYou have 60 seconds to connect to the WebSocket URL. If the connection cannot be established during this time,\r\nuse the reconnect method below to generate a new stream URL.\r\n\r\nThis call is similar to ```/v3/directline/tokens/generate```. The difference is that the call to\r\n```/v3/directline/conversations``` starts the conversation, contacts the bot, and creates a streaming WebSocket\r\nURL, none of which occur when generating a token.\r\n* Call ```/v3/directline/conversations``` if you will distribute the token to client(s) and want them to\r\n initiate the conversation.\r\n* Call ```/v3/directline/conversations``` if you intend to start the conversation immediately.\r\n\r\n## Reconnecting to a conversation\r\n\r\nIf a client is using the WebSocket interface to receive messages but loses its connection, it may need to reconnect.\r\nReconnecting requires generating a new WebSocket stream URL, and this can be accomplished by sending a GET request\r\nto the ```/v3/directline/conversations/{id}``` endpoint.\r\n\r\nThe ```watermark``` parameter is optional. If supplied, the conversation replays from the watermark,\r\nguaranteeing no messages are lost. If ```watermark``` is omitted, only messages received after the reconnection\r\ncall (```GET /v3/directline/conversations/abc123```) are replayed.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nGET /v3/directline/conversations/abc123?watermark=0000a-42 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"streamUrl\": \"https://directline.botframework.com/v3/directline/conversations/abc123/stream?watermark=000a-4&t=RCurR_XV9ZA.cwA...\"\r\n}\r\n```\r\n\r\nYou have 60 seconds to connect to the WebSocket stream URL. If the connection cannot be established during this\r\ntime, issue another reconnect request to get an updated stream URL.\r\n\r\n## Sending an Activity to the bot\r\n\r\nUsing the Direct Line 3.0 protocol, clients and bots may exchange many different Bot Framework v3 Activities,\r\nincluding Message Activities, Typing Activities, and custom activities that the bot supports.\r\n\r\nTo send any one of these activities to the bot,\r\n\r\n1. the client formulates the Activity according to the Activity schema (see below)\r\n2. the client issues a POST message to ```/v3/directline/conversations/{id}/activities```\r\n3. the service returns when the activity was delivered to the bot, with an HTTP status code reflecting the\r\n bot's status code. If the POST was successful, the service returns a JSON payload containing the ID of the\r\n Activity that was sent.\r\n\r\nExample follows.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n{\r\n \"type\": \"message\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n}\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0001\"\r\n}\r\n```\r\n\r\nThe client's Activity is available in the message retrieval path (either polling GET or WebSocket) and is not\r\nreturned inline.\r\n\r\nThe total time to POST a message to a Direct Line conversation is:\r\n\r\n* Transit time to the Direct Line service,\r\n* Internal processing time within Direct Line (typically less than 120ms)\r\n* Transit time to the bot\r\n* Processing time within the bot\r\n* Transit time for HTTP responses to travel back to the client.\r\n\r\nIf the bot generates an error, that error will trigger an HTTP 502 error (\"Bad Gateway\") in\r\nthe ```POST /v3/directline/conversations/{id}/activities``` call.\r\n\r\n### Sending one or more attachments by URL\r\n\r\nClients may optionally send attachments, such as images or documents. If the client already has a URL for the\r\nattachment, the simplest way to send it is to include the URL in the ```contentUrl``` field of an Activity\r\nattachment object. This applies to HTTP, HTTPS, and ```data:``` URIs.\r\n\r\n### Sending a single attachment by upload\r\n\r\nOften, clients have an image or document on a device but no URL that can be included in the activity.\r\n\r\nTo upload an attachment, POST a single attachment to\r\nthe ```/v3/directline/conversations/{conversationId}/upload``` endpoint. The ```Content-Type```\r\nand ```Content-Disposition``` headers control the attachment's type and filename, respectively.\r\n\r\nA user ID is required. Supply the ID of the user sending the attachment as a ```userId``` parameter in the URL.\r\n\r\nIf uploading a single attachment, a message activity is sent to the bot when the upload completes.\r\n\r\nOn completion, the service returns the ID of the activity that was sent.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/upload?userId=user1 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\nContent-Type: image/jpeg\r\nContent-Disposition: name=\"file\"; filename=\"badjokeeel.jpg\"\r\n[other headers]\r\n\r\n[JPEG content]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0003\"\r\n}\r\n```\r\n\r\n### Sending multiple attachments by upload\r\n\r\nIf uploading multiple attachments, use ```multipart/form-data``` as the content type and include each\r\nattachment as a separate part. Each attachment's type and filename may be included in the ```Content-Type```\r\nand ```Content-Disposition``` headers in each part.\r\n\r\nAn activity may be included by adding a part with content type of ```application/vnd.microsoft.activity```.\r\nOther parts in the payload are attached to this activity before it is sent. If an Activity is not included,\r\nan empty Activity is created as a wrapper for the attachments.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/upload?userId=user1 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\nContent-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89\r\n[other headers]\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\nContent-Type: image/jpeg\r\nContent-Disposition: form-data; name=\"file\"; filename=\"badjokeeel.jpg\"\r\n[other headers]\r\n\r\n[JPEG content]\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\nContent-Type: application/vnd.microsoft.activity\r\n[other headers]\r\n\r\n{\r\n \"type\": \"message\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"Hey I just IM'd you\\n\\nand this is crazy\\n\\nbut here's my webhook\\n\\nso POST me maybe\"\r\n}\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\n\r\n\r\n \r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0004\"\r\n}\r\n```\r\n\r\n## Receiving Activities from the bot\r\n\r\nDirect Line 3.0 clients may choose from two different mechanisms for retrieving messages:\r\n\r\n1. A **streaming WebSocket**, which pushes messages efficiently to clients.\r\n2. A **polling GET** interface, which is available for clients unable to use WebSockets or for clients\r\n retrieving the conversation history.\r\n\r\n**Not all activities are available via the polling GET interface.** A table of activity availability follows.\r\n\r\n|Activity type|Availability|\r\n|-------------|--------|\r\n|Message|Polling GET and WebSocket|\r\n|Typing|WebSocket only|\r\n|ConversationUpdate|Not sent/received via client|\r\n|ContactRelationUpdate|Not supported in Direct Line|\r\n|EndOfConversation|Polling GET and WebSocket|\r\n|All other activity types|Polling GET and WebSocket|\r\n\r\n### Receiving Activities by WebSocket\r\n\r\nTo connect via WebSocket, a client uses the StreamUrl when starting a conversation. The stream URL is\r\npreauthorized and does NOT require an Authorization header containing the client's secret or token.\r\n\r\n```\r\n-- connect to wss://directline.botframework.com --\r\nGET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA...\" HTTP/1.1\r\nUpgrade: websocket\r\nConnection: upgrade\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 101 Switching Protocols\r\n[other headers]\r\n```\r\n\r\nThe Direct Line service sends the following messages:\r\n\r\n* An **ActivitySet**, which contains one or more activities and a watermark (described below)\r\n* An empty message, which the Direct Line service uses to ensure the connection is still valid\r\n* Additional types, to be defined later. These types are identified by the properties in the JSON root.\r\n\r\nActivitySets contain messages sent by the bot and by all users. Example ActivitySet:\r\n\r\n```\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }],\r\n \"watermark\": \"0000a-42\"\r\n}\r\n```\r\n\r\nClients should keep track of the \"watermark\" value from each ActivitySet so they can use it on reconnect.\r\n**Note** that a ```null``` or missing watermark should be ignored and should not overwrite a prior watermark\r\nin the client.\r\n\r\nClients should ignore empty messages.\r\n\r\nClients may send their own empty messages to verify connectivity. The Direct Line service will ignore these.\r\n\r\nThe service may forcibly close the connection under certain conditions. If the client has not received an\r\nEndOfConversation activity, it may reconnect by issuing a GET request to the conversation endpoint to get a\r\nnew stream URL (see above).\r\n\r\nThe WebSocket stream contains live updates and very recent messages (since the call to get the WebSocket call\r\nwas issued) but it does not include messages sent prior to the most recent POST\r\nto ```/v3/directline/conversations/{id}```. To retrieve messages sent earlier in the conversation, use the\r\nGET mechanism below.\r\n\r\n### Receiving Activities by GET\r\n\r\nThe GET mechanism is useful for clients who are unable to use the WebSocket, or for clients wishing to retrieve\r\nthe conversation history.\r\n\r\nTo retrieve messages, issue a GET call to the conversation endpoint. Optionally supply a watermark, indicating\r\nthe most recent message seen. The watermark field accompanies all GET/WebSocket messages as a property in the\r\nActivitySet.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nGET /v3/directline/conversations/abc123/activities?watermark=0001a-94 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }, {\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0001\",\r\n \"from\": {\r\n \"id\": \"bot1\"\r\n },\r\n \"text\": \"Nice to see you, user1!\"\r\n }],\r\n \"watermark\": \"0001a-95\"\r\n}\r\n```\r\n\r\nClients should page through the available activities by advancing the ```watermark``` value until no activities\r\nare returned.\r\n\r\n\r\n### Timing considerations \r\n\r\nMost clients wish to retain a complete message history. Even though Direct Line is a multi-part protocol with\r\npotential timing gaps, the protocol and service is designed to make it easy to build a reliable client.\r\n\r\n1. The ```watermark``` field sent in the WebSocket stream and GET response is reliable. You will not miss\r\n messages as long as you replay the watermark verbatim.\r\n2. When starting a conversation and connecting to the WebSocket stream, any Activities sent after the POST but\r\n before the socket is opened are replayed before new messages.\r\n3. When refreshing history by GET call while connected to the WebSocket, Activities may be duplicated across both\r\n channels. Keeping a list of all known Activity IDs will allow you to reject duplicate messages should they occur.\r\n\r\nClients using the polling GET interface should choose a polling interval that matches their intended use.\r\n\r\n* Service-to-service applications often use a polling interval of 5s or 10s.\r\n* Client-facing applications often use a polling interval of 1s, and fire an additional request ~300ms after\r\n every message the client sends to rapidly pick up a bot's response. This 300ms delay should be adjusted\r\n based on the bot's speed and transit time.\r\n\r\n## Ending a conversation\r\n\r\nEither a client or a bot may signal the end of a DirectLine conversation. This operation halts communication\r\nand prevents the bot and the client from sending messages. Messages may still be retrieved via the GET mechanism.\r\nSending this messages is as simple as POSTing an EndOfConversation activity.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n{\r\n \"type\": \"endOfConversation\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n }\r\n}\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0004\"\r\n}\r\n```\r\n\r\n## REST API errors\r\n\r\nHTTP calls to the Direct Line service follow standard HTTP error conventions:\r\n\r\n* 2xx status codes indicate success. (Direct Line 3.0 uses 200 and 201.)\r\n* 4xx status codes indicate an error in your request.\r\n * 401 indicates a missing or malformed Authorization header (or URL token, in calls where a token parameter\r\n is allowed).\r\n * 403 indicates an unauthorized client.\r\n * If calling with a valid but expired token, the ```code``` field is set to ```TokenExpired```.\r\n * 404 indicates a missing path, site, conversation, etc.\r\n* 5xx status codes indicate a service-side error.\r\n * 500 indicates an error inside the Direct Line service.\r\n * 502 indicates an error was returned by the bot. **This is a common error code.**\r\n* 101 is used in the WebSocket connection path, although this is likely handled by your WebSocket client.\r\n\r\nWhen an error message is returned, error detail may be present in a JSON response. Look for an ```error```\r\nproperty with ```code``` and ```message``` fields.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\n[detail omitted]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 502 Bad Gateway\r\n[other headers]\r\n\r\n{\r\n \"error\": {\r\n \"code\": \"BotRejectedActivity\",\r\n \"message\": \"Failed to send activity: bot returned an error\"\r\n }\r\n}\r\n```\r\n\r\nThe contents of the ```message``` field may change. The HTTP status code and values in the ```code```\r\nproperty are stable.\r\n\r\n# Schema\r\n\r\nThe Direct Line 3.0 schema is identical to the Bot Framework v3 schema.\r\n\r\nWhen a bot sends an Activity to a client through Direct Line:\r\n\r\n* attachment cards are preserved,\r\n* URLs for uploaded attachments are hidden with a private link, and\r\n* the ```channelData``` property is preserved without modification.\r\n\r\nWhen a client sends an Activity to a bot through Direct Line:\r\n\r\n* the ```type``` property contains the kind of activity you are sending (typically ```message```),\r\n* the ```from``` property must be populated with a user ID, chosen by your client,\r\n* attachments may contain URLs to existing resources or URLs uploaded through the Direct Line attachment\r\n endpoint, and\r\n* the ```channelData``` property is preserved without modification.\r\n\r\nClients and bots may send Activities of any type, including Message Activities, Typing Activities, and\r\ncustom Activity types.\r\n\r\nClients may send a single Activity at a time.\r\n\r\n```\r\n{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n}\r\n```\r\n\r\nClients receive multiple Activities as part of an ActivitySet. The ActivitySet has an array of activities\r\nand a watermark field.\r\n\r\n```\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }],\r\n \"watermark\": \"0000a-42\"\r\n}\r\n```\r\n\r\n# Libraries for the Direct Line API\r\n\r\nThe Direct Line API is designed to be coded directly, but the Bot Framework includes libraries and controls that\r\nhelp you to embed Direct-Line-powered bots into your application.\r\n\r\n* The [Bot Framework Web Chat control](https://github.com/Microsoft/BotFramework-WebChat) is an easy way to embed\r\n the Direct Line protocol into a webpage.\r\n* [Direct Line Nuget package](https://www.nuget.org/packages/Microsoft.Bot.Connector.DirectLine) with libraries for\r\n .Net 4.5, UWP, and .Net Standard.\r\n* [DirectLineJs](https://github.com/Microsoft/BotFramework-DirectLineJs), also available on\r\n [NPM](https://www.npmjs.com/package/botframework-directlinejs)\r\n* You may generate your own from the [Direct Line Swagger file](swagger.json)\r\n\r\nOur [BotBuilder-Samples GitHub repo](https://github.com/Microsoft/BotBuilder-Samples) also contains samples for\r\n [C#](https://github.com/Microsoft/BotBuilder-Samples/tree/master/CSharp/core-DirectLine) and\r\n [JavaScript](https://github.com/Microsoft/BotBuilder-Samples/tree/master/Node/core-DirectLine).", + "description": "Direct Line 3.0\r\n===============\r\n\r\n\r\nThe Direct Line API is a simple REST API for connecting directly to a single bot. This API is intended for developers\r\nwriting their own client applications, web chat controls, mobile apps, or service-to-service applications that will\r\ntalk to their bot.\r\n\r\nWithin the Direct Line API, you will find:\r\n\r\n* An **authentication mechanism** using standard secret/token patterns\r\n* The ability to **send** messages from your client to your bot via an HTTP POST message\r\n* The ability to **receive** messages by **WebSocket** stream, if you choose\r\n* The ability to **receive** messages by **polling HTTP GET**, if you choose\r\n* A stable **schema**, even if your bot changes its protocol version\r\n\r\nDirect Line 1.1 and 3.0 are both available and supported. This document describes Direct Line 3.0. For information\r\non Direct Line 1.1, visit the [Direct Line 1.1 reference documentation](/en-us/restapi/directline/).\r\n\r\n# Authentication: Secrets and Tokens\r\n\r\nDirect Line allows you to authenticate all calls with either a secret (retrieved from the Direct Line channel\r\nconfiguration page) or a token (which you may get at runtime by converting your secret).\r\n\r\nA Direct Line **secret** is a master key that can access any conversation, and create tokens. Secrets do not expire.\r\n\r\nA Direct Line **token** is a key for a single conversation. It expires but can be refreshed.\r\n\r\nIf you're writing a service-to-service application, using the secret may be simplest. If you're writing an application\r\nwhere the client runs in a web browser or mobile app, you may want to exchange your secret for a token, which only\r\nworks for a single conversation and will expire unless refreshed. You choose which security model works best for you.\r\n\r\nYour secret or token is communicated in the ```Authorization``` header of every call, with the Bearer scheme.\r\nExample below.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other HTTP headers, omitted]\r\n```\r\n\r\nYou may notice that your Direct Line client credentials are different from your bot's credentials. This is\r\nintentional, and it allows you to revise your keys independently and lets you share client tokens without\r\ndisclosing your bot's password. \r\n\r\n## Exchanging a secret for a token\r\n\r\nThis operation is optional. Use this step if you want to prevent clients from accessing conversations they aren't\r\nparticipating in.\r\n\r\nTo exchange a secret for a token, POST to /v3/directline/tokens/generate with your secret in the auth header\r\nand no HTTP body.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/tokens/generate HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"expires_in\": 1800\r\n}\r\n```\r\n\r\nIf successful, the response is a token suitable for one conversation. The token expires in the seconds\r\nindicated in the ```expires_in``` field (30 minutes in the example above) and must be refreshed before then to\r\nremain useful.\r\n\r\nThis call is similar to ```/v3/directline/conversations```. The difference is that the call to\r\n```/v3/directline/tokens/generate``` does not start the conversation, does not contact the bot, and does not\r\ncreate a streaming WebSocket URL.\r\n* Call ```/v3/directline/conversations``` if you will distribute the token to client(s) and want them to \r\n initiate the conversation.\r\n* Call ```/v3/directline/conversations``` if you intend to start the conversation immediately.\r\n\r\n\r\n## Refreshing a token\r\n\r\nA token may be refreshed an unlimited number of times unless it is expired.\r\n\r\nTo refresh a token, POST to /v3/directline/tokens/refresh. This method is valid only for unexpired tokens.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/tokens/refresh HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\",\r\n \"expires_in\": 1800\r\n}\r\n```\r\n\t\r\n\r\n# REST calls for a Direct Line conversation\r\n\r\nDirect Line conversations are explicitly opened by clients and may run as long as the bot and client participate\r\n(and have valid credentials). While the conversation is open, the bot and client may both send messages. More than\r\none client may connect to a given conversation and each client may participate on behalf of multiple users.\r\n\r\n## Starting a conversation\r\n\r\nClients begin by explicitly starting a conversation. If successful, the Direct Line service replies with a\r\nJSON object containing a conversation ID, a token, and a WebSocket URL that may be used later.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 201 Created\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"expires_in\": 1800,\r\n \"streamUrl\": \"https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA...\"\r\n}\r\n```\r\n\r\nIf the conversation was started, an HTTP 201 status code is returned. HTTP 201 is the code that clients\r\nwill receive under most circumstances, as the typical use case is for a client to start a new conversation.\r\nUnder certain conditions -- specifically, when the client has a token scoped to a single conversation AND\r\nwhen that conversation was started with a prior call to this URL -- this method will return HTTP 200 to signify\r\nthe request was acceptable but that no conversation was created (as it already existed).\r\n\r\nYou have 60 seconds to connect to the WebSocket URL. If the connection cannot be established during this time,\r\nuse the reconnect method below to generate a new stream URL.\r\n\r\nThis call is similar to ```/v3/directline/tokens/generate```. The difference is that the call to\r\n```/v3/directline/conversations``` starts the conversation, contacts the bot, and creates a streaming WebSocket\r\nURL, none of which occur when generating a token.\r\n* Call ```/v3/directline/conversations``` if you will distribute the token to client(s) and want them to\r\n initiate the conversation.\r\n* Call ```/v3/directline/conversations``` if you intend to start the conversation immediately.\r\n\r\n## Reconnecting to a conversation\r\n\r\nIf a client is using the WebSocket interface to receive messages but loses its connection, it may need to reconnect.\r\nReconnecting requires generating a new WebSocket stream URL, and this can be accomplished by sending a GET request\r\nto the ```/v3/directline/conversations/{id}``` endpoint.\r\n\r\nThe ```watermark``` parameter is optional. If supplied, the conversation replays from the watermark,\r\nguaranteeing no messages are lost. If ```watermark``` is omitted, only messages received after the reconnection\r\ncall (```GET /v3/directline/conversations/abc123```) are replayed.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nGET /v3/directline/conversations/abc123?watermark=0000a-42 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"conversationId\": \"abc123\",\r\n \"token\": \"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn\",\r\n \"streamUrl\": \"https://directline.botframework.com/v3/directline/conversations/abc123/stream?watermark=000a-4&t=RCurR_XV9ZA.cwA...\"\r\n}\r\n```\r\n\r\nYou have 60 seconds to connect to the WebSocket stream URL. If the connection cannot be established during this\r\ntime, issue another reconnect request to get an updated stream URL.\r\n\r\n## Sending an Activity to the bot\r\n\r\nUsing the Direct Line 3.0 protocol, clients and bots may exchange many different Bot Framework v3 Activites,\r\nincluding Message Activities, Typing Activities, and custom activities that the bot supports.\r\n\r\nTo send any one of these activities to the bot,\r\n\r\n1. the client formulates the Activity according to the Activity schema (see below)\r\n2. the client issues a POST message to ```/v3/directline/conversations/{id}/activities```\r\n3. the service returns when the activity was delivered to the bot, with an HTTP status code reflecting the\r\n bot's status code. If the POST was successful, the service returns a JSON payload containing the ID of the\r\n Activity that was sent.\r\n\r\nExample follows.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n{\r\n \"type\": \"message\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n}\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0001\"\r\n}\r\n```\r\n\r\nThe client's Activity is available in the message retrieval path (either polling GET or WebSocket) and is not\r\nreturned inline.\r\n\r\nThe total time to POST a message to a Direct Line conversation is:\r\n\r\n* Transit time to the Direct Line service,\r\n* Internal processing time within Direct Line (typically less than 120ms)\r\n* Transit time to the bot\r\n* Processing time within the bot\r\n* Transit time for HTTP responses to travel back to the client.\r\n\r\nIf the bot generates an error, that error will trigger an HTTP 502 error (\"Bad Gateway\") in\r\nthe ```POST /v3/directline/conversations/{id}/activities``` call.\r\n\r\n### Sending one or more attachments by URL\r\n\r\nClients may optionally send attachments, such as images or documents. If the client already has a URL for the\r\nattachment, the simplest way to send it is to include the URL in the ```contentUrl``` field of an Activity\r\nattachment object. This applies to HTTP, HTTPS, and ```data:``` URIs.\r\n\r\n### Sending a single attachment by upload\r\n\r\nOften, clients have an image or document on a device but no URL that can be included in the activity.\r\n\r\nTo upload an attachment, POST a single attachment to\r\nthe ```/v3/directline/conversations/{conversationId}/upload``` endpoint. The ```Content-Type```\r\nand ```Content-Disposition``` headers control the attachment's type and filename, respectively.\r\n\r\nA user ID is required. Supply the ID of the user sending the attachment as a ```userId``` parameter in the URL.\r\n\r\nIf uploading a single attachment, a message activity is sent to the bot when the upload completes.\r\n\r\nOn completion, the service returns the ID of the activity that was sent.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/upload?userId=user1 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\nContent-Type: image/jpeg\r\nContent-Disposition: name=\"file\"; filename=\"badjokeeel.jpg\"\r\n[other headers]\r\n\r\n[JPEG content]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0003\"\r\n}\r\n```\r\n\r\n### Sending multiple attachments by upload\r\n\r\nIf uploading multiple attachments, use ```multipart/form-data``` as the content type and include each\r\nattachment as a separate part. Each attachment's type and filename may be included in the ```Content-Type```\r\nand ```Content-Disposition``` headers in each part.\r\n\r\nAn activity may be included by adding a part with content type of ```application/vnd.microsoft.activity```.\r\nOther parts in the payload are attached to this activity before it is sent. If an Activity is not included,\r\nan empty Activity is created as a wrapper for the attachments.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/upload?userId=user1 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\nContent-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89\r\n[other headers]\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\nContent-Type: image/jpeg\r\nContent-Disposition: form-data; name=\"file\"; filename=\"badjokeeel.jpg\"\r\n[other headers]\r\n\r\n[JPEG content]\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\nContent-Type: application/vnd.microsoft.activity\r\n[other headers]\r\n\r\n{\r\n \"type\": \"message\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"Hey I just IM'd you\\n\\nand this is crazy\\n\\nbut here's my webhook\\n\\nso POST me maybe\"\r\n}\r\n\r\n----DD4E5147-E865-4652-B662-F223701A8A89\r\n\r\n\r\n \r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0004\"\r\n}\r\n```\r\n\r\n## Receiving Activities from the bot\r\n\r\nDirect Line 3.0 clients may choose from two different mechanisms for retrieving messages:\r\n\r\n1. A **streaming WebSocket**, which pushes messages efficiently to clients.\r\n2. A **polling GET** interface, which is available for clients unable to use WebSockets or for clients\r\n retrieving the conversation history.\r\n\r\n**Not all activities are available via the polling GET interface.** A table of activity availability follows.\r\n\r\n|Activity type|Availability|\r\n|-------------|--------|\r\n|Message|Polling GET and WebSocket|\r\n|Typing|WebSocket only|\r\n|ConversationUpdate|Not sent/received via client|\r\n|ContactRelationUpdate|Not supported in Direct Line|\r\n|EndOfConversation|Polling GET and WebSocket|\r\n|All other activity types|Polling GET and WebSocket|\r\n\r\n### Receiving Activities by WebSocket\r\n\r\nTo connect via WebSocket, a client uses the StreamUrl when starting a conversation. The stream URL is\r\npreauthorized and does NOT require an Authorization header containing the client's secret or token.\r\n\r\n```\r\n-- connect to wss://directline.botframework.com --\r\nGET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA...\" HTTP/1.1\r\nUpgrade: websocket\r\nConnection: upgrade\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 101 Switching Protocols\r\n[other headers]\r\n```\r\n\r\nThe Direct Line service sends the following messages:\r\n\r\n* An **ActivitySet**, which contains one or more activities and a watermark (described below)\r\n* An empty message, which the Direct Line service uses to ensure the connection is still valid\r\n* Additional types, to be defined later. These types are identified by the properties in the JSON root.\r\n\r\nActivitySets contain messages sent by the bot and by all users. Example ActivitySet:\r\n\r\n```\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }],\r\n \"watermark\": \"0000a-42\"\r\n}\r\n```\r\n\r\nClients should keep track of the \"watermark\" value from each ActivitySet so they can use it on reconnect.\r\n**Note** that a ```null``` or missing watermark should be ignored and should not overwrite a prior watermark\r\nin the client.\r\n\r\nClients should ignore empty messages.\r\n\r\nClients may send their own empty messages to verify connectivity. The Direct Line service will ignore these.\r\n\r\nThe service may forcibly close the connection under certain conditions. If the client has not received an\r\nEndOfConversation activity, it may reconnect by issuing a GET request to the conversation endpoint to get a\r\nnew stream URL (see above).\r\n\r\nThe WebSocket stream contains live updates and very recent messages (since the call to get the WebSocket call\r\nwas issued) but it does not include messages sent prior to the most recent POST\r\nto ```/v3/directline/conversations/{id}```. To retrieve messages sent earlier in the conversation, use the\r\nGET mechanism below.\r\n\r\n### Receiving Activities by GET\r\n\r\nThe GET mechanism is useful for clients who are unable to use the WebSocket, or for clients wishing to retrieve\r\nthe conversation history.\r\n\r\nTo retrieve messages, issue a GET call to the conversation endpoint. Optionally supply a watermark, indicating\r\nthe most recent message seen. The watermark field accompanies all GET/WebSocket messages as a property in the\r\nActivitySet.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nGET /v3/directline/conversations/abc123/activities?watermark=0001a-94 HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }, {\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0001\",\r\n \"from\": {\r\n \"id\": \"bot1\"\r\n },\r\n \"text\": \"Nice to see you, user1!\"\r\n }],\r\n \"watermark\": \"0001a-95\"\r\n}\r\n```\r\n\r\nClients should page through the available activities by advancing the ```watermark``` value until no activities\r\nare returned.\r\n\r\n\r\n### Timing considerations \r\n\r\nMost clients wish to retain a complete message history. Even though Direct Line is a multi-part protocol with\r\npotential timing gaps, the protocol and service is designed to make it easy to build a reliable client.\r\n\r\n1. The ```watermark``` field sent in the WebSocket stream and GET response is reliable. You will not miss\r\n messages as long as you replay the watermark verbatim.\r\n2. When starting a conversation and connecting to the WebSocket stream, any Activities sent after the POST but\r\n before the socket is opened are replayed before new messages.\r\n3. When refreshing history by GET call while connected to the WebSocket, Activities may be duplicated across both\r\n channels. Keeping a list of all known Activity IDs will allow you to reject duplicate messages should they occur.\r\n\r\nClients using the polling GET interface should choose a polling interval that matches their intended use.\r\n\r\n* Service-to-service applications often use a polling interval of 5s or 10s.\r\n* Client-facing applications often use a polling interval of 1s, and fire an additional request ~300ms after\r\n every message the client sends to rapidly pick up a bot's response. This 300ms delay should be adjusted\r\n based on the bot's speed and transit time.\r\n\r\n## Ending a conversation\r\n\r\nEither a client or a bot may signal the end of a DirectLine conversation. This operation halts communication\r\nand prevents the bot and the client from sending messages. Messages may still be retrieved via the GET mechanism.\r\nSending this messages is as simple as POSTing an EndOfConversation activity.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\nAuthorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0\r\n[other headers]\r\n\r\n{\r\n \"type\": \"endOfConversation\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n }\r\n}\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 200 OK\r\n[other headers]\r\n\r\n{\r\n \"id\": \"0004\"\r\n}\r\n```\r\n\r\n## REST API errors\r\n\r\nHTTP calls to the Direct Line service follow standard HTTP error conventions:\r\n\r\n* 2xx status codes indicate success. (Direct Line 3.0 uses 200 and 201.)\r\n* 4xx status codes indicate an error in your request.\r\n * 401 indicates a missing or malformed Authorization header (or URL token, in calls where a token parameter\r\n is allowed).\r\n * 403 indicates an unauthorized client.\r\n * If calling with a valid but expired token, the ```code``` field is set to ```TokenExpired```.\r\n * 404 indicates a missing path, site, conversation, etc.\r\n* 5xx status codes indicate a service-side error.\r\n * 500 indicates an error inside the Direct Line service.\r\n * 502 indicates an error was returned by the bot. **This is a common error code.**\r\n* 101 is used in the WebSocket connection path, although this is likely handled by your WebSocket client.\r\n\r\nWhen an error message is returned, error detail may be present in a JSON response. Look for an ```error```\r\nproperty with ```code``` and ```message``` fields.\r\n\r\n```\r\n-- connect to directline.botframework.com --\r\nPOST /v3/directline/conversations/abc123/activities HTTP/1.1\r\n[detail omitted]\r\n\r\n-- response from directline.botframework.com --\r\nHTTP/1.1 502 Bad Gateway\r\n[other headers]\r\n\r\n{\r\n \"error\": {\r\n \"code\": \"BotRejectedActivity\",\r\n \"message\": \"Failed to send activity: bot returned an error\"\r\n }\r\n}\r\n```\r\n\r\nThe contents of the ```message``` field may change. The HTTP status code and values in the ```code```\r\nproperty are stable.\r\n\r\n# Schema\r\n\r\nThe Direct Line 3.0 schema is identical to the Bot Framework v3 schema.\r\n\r\nWhen a bot sends an Activity to a client through Direct Line:\r\n\r\n* attachment cards are preserved,\r\n* URLs for uploaded attachments are hidden with a private link, and\r\n* the ```channelData``` property is preserved without modification.\r\n\r\nWhen a client sends an Activity to a bot through Direct Line:\r\n\r\n* the ```type``` property contains the kind of activity you are sending (typically ```message```),\r\n* the ```from``` property must be populated with a user ID, chosen by your client,\r\n* attachments may contain URLs to existing resources or URLs uploaded through the Direct Line attachment\r\n endpoint, and\r\n* the ```channelData``` property is preserved without modification.\r\n\r\nClients and bots may send Activities of any type, including Message Activities, Typing Activities, and\r\ncustom Activity types.\r\n\r\nClients may send a single Activity at a time.\r\n\r\n```\r\n{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n}\r\n```\r\n\r\nClients receive multiple Activities as part of an ActivitySet. The ActivitySet has an array of activities\r\nand a watermark field.\r\n\r\n```\r\n{\r\n \"activities\": [{\r\n \"type\": \"message\",\r\n \"channelId\": \"directline\",\r\n \"conversation\": {\r\n \"id\": \"abc123\"\r\n },\r\n \"id\": \"abc123|0000\",\r\n \"from\": {\r\n \"id\": \"user1\"\r\n },\r\n \"text\": \"hello\"\r\n }],\r\n \"watermark\": \"0000a-42\"\r\n}\r\n```\r\n\r\n# Libraries for the Direct Line API\r\n\r\nThe Direct Line API is designed to be coded directly, but the Bot Framework includes libraries and controls that\r\nhelp you to embed Direct-Line-powered bots into your application.\r\n\r\n* The [Bot Framework Web Chat control](https://github.com/Microsoft/BotFramework-WebChat) is an easy way to embed\r\n the Direct Line protocol into a webpage.\r\n* [Direct Line Nuget package](https://www.nuget.org/packages/Microsoft.Bot.Connector.DirectLine) with libraries for\r\n .Net 4.5, UWP, and .Net Standard.\r\n* [DirectLineJs](https://github.com/Microsoft/BotFramework-DirectLineJs), also available on\r\n [NPM](https://www.npmjs.com/package/botframework-directlinejs)\r\n* You may generate your own from the [Direct Line Swagger file](swagger.json)\r\n\r\nOur [BotBuilder-Samples GitHub repo](https://github.com/Microsoft/BotBuilder-Samples) also contains samples for\r\n [C#](https://github.com/Microsoft/BotBuilder-Samples/tree/master/CSharp/core-DirectLine) and\r\n [JavaScript](https://github.com/Microsoft/BotBuilder-Samples/tree/master/Node/core-DirectLine).", "termsOfService": "https://www.microsoft.com/en-us/legal/intellectualproperty/copyright/default.aspx", "contact": { "name": "Bot Framework", @@ -20,29 +20,6 @@ "https" ], "paths": { - "/v3/directline/session/getsessionid": { - "get": { - "tags": [ - "Session" - ], - "operationId": "Session_GetSessionId", - "consumes": [], - "produces": [ - "application/json", - "text/json", - "application/xml", - "text/xml" - ], - "responses": { - "200": { - "description": "OK", - "schema": { - "type": "object" - } - } - } - } - }, "/v3/directline/conversations": { "post": { "tags": [ @@ -50,29 +27,14 @@ ], "summary": "Start a new conversation", "operationId": "Conversations_StartConversation", - "consumes": [ - "application/json", - "text/json", - "application/xml", - "text/xml", - "application/x-www-form-urlencoded" - ], + "consumes": [], "produces": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml" ], - "parameters": [ - { - "name": "tokenParameters", - "in": "body", - "required": false, - "schema": { - "$ref": "#/definitions/TokenParameters" - } - } - ], "responses": { "200": { "description": "The conversation was successfully created, updated, or retrieved.", @@ -86,9 +48,6 @@ "$ref": "#/definitions/Conversation" } }, - "400": { - "description": "The URL, body, or headers in the request are malformed or invalid." - }, "401": { "description": "The operation included an invalid or missing Authorization header." }, @@ -100,14 +59,9 @@ }, "409": { "description": "The object you are trying to create already exists." - }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, - "500": { - "description": "An internal server error has occurred." } - } + }, + "deprecated": false } }, "/v3/directline/conversations/{conversationId}": { @@ -121,6 +75,7 @@ "produces": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml" ], @@ -145,9 +100,6 @@ "$ref": "#/definitions/Conversation" } }, - "400": { - "description": "The URL, body, or headers in the request are malformed or invalid." - }, "401": { "description": "The operation included an invalid or missing Authorization header." }, @@ -156,14 +108,9 @@ }, "404": { "description": "The requested resource was not found." - }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, - "500": { - "description": "An internal server error has occurred." } - } + }, + "deprecated": false } }, "/v3/directline/conversations/{conversationId}/activities": { @@ -177,6 +124,7 @@ "produces": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml" ], @@ -203,9 +151,6 @@ "$ref": "#/definitions/ActivitySet" } }, - "400": { - "description": "The URL, body, or headers in the request are malformed or invalid." - }, "401": { "description": "The operation included an invalid or missing Authorization header." }, @@ -214,14 +159,9 @@ }, "404": { "description": "The requested resource was not found." - }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, - "500": { - "description": "An internal server error has occurred." } - } + }, + "deprecated": false }, "post": { "tags": [ @@ -232,13 +172,15 @@ "consumes": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml", "application/x-www-form-urlencoded" ], "produces": [ "application/json", - "text/json" + "text/json", + "text/html" ], "parameters": [ { @@ -280,16 +222,14 @@ "404": { "description": "The requested resource was not found." }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, "500": { "description": "An internal server error has occurred." }, "502": { "description": "The bot is unavailable or returned an error." } - } + }, + "deprecated": false } }, "/v3/directline/conversations/{conversationId}/upload": { @@ -304,7 +244,8 @@ ], "produces": [ "application/json", - "text/json" + "text/json", + "text/html" ], "parameters": [ { @@ -351,16 +292,14 @@ "404": { "description": "The requested resource was not found." }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, "500": { "description": "An internal server error has occurred." }, "502": { "description": "The bot is unavailable or returned an error." } - } + }, + "deprecated": false } }, "/v3/directline/tokens/refresh": { @@ -374,6 +313,7 @@ "produces": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml" ], @@ -393,13 +333,11 @@ "404": { "description": "The requested resource was not found." }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, "500": { "description": "An internal server error has occurred." } - } + }, + "deprecated": false } }, "/v3/directline/tokens/generate": { @@ -412,6 +350,7 @@ "consumes": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml", "application/x-www-form-urlencoded" @@ -419,6 +358,7 @@ "produces": [ "application/json", "text/json", + "text/html", "application/xml", "text/xml" ], @@ -448,59 +388,15 @@ "404": { "description": "The requested resource was not found." }, - "429": { - "description": "Too many requests have been submitted to this API. This error may be accompanied by a Retry-After header, which includes the suggested retry interval." - }, "500": { "description": "An internal server error has occurred." } - } + }, + "deprecated": false } } }, "definitions": { - "TokenParameters": { - "description": "Parameters for creating a token", - "type": "object", - "properties": { - "user": { - "$ref": "#/definitions/ChannelAccount", - "description": "User account to embed within the token" - }, - "trustedOrigins": { - "description": "Trusted origins to embed within the token", - "type": "array", - "items": { - "type": "string" - } - }, - "eTag": { - "type": "string" - } - } - }, - "ChannelAccount": { - "description": "Channel account information needed to route a message", - "type": "object", - "properties": { - "id": { - "description": "Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)", - "type": "string" - }, - "name": { - "description": "Display friendly name", - "type": "string" - }, - "aadObjectId": { - "description": "This account's object ID within Azure Active Directory (AAD)", - "type": "string" - }, - "role": { - "description": "Role of the entity behind the account (Example: User, Bot, etc.)", - "type": "string" - } - } - }, "Conversation": { "description": "An object representing a conversation or a conversation token", "type": "object", @@ -549,118 +445,100 @@ } }, "Activity": { - "description": "An Activity is the basic communication type for the Bot Framework 3.0 protocol.", + "description": "An Activity is the basic communication type for the Bot Framework 3.0 protocol", "type": "object", "properties": { "type": { - "description": "Contains the activity type.", + "description": "The type of the activity [message|contactRelationUpdate|converationUpdate|typing|endOfConversation|event|invoke]", "type": "string" }, "id": { - "description": "Contains an ID that uniquely identifies the activity on the channel.", + "description": "ID of this activity", "type": "string" }, "timestamp": { "format": "date-time", - "description": "Contains the date and time that the message was sent, in UTC, expressed in ISO-8601 format.", + "description": "UTC Time when message was sent (set by service)", "type": "string" }, "localTimestamp": { "format": "date-time", - "description": "Contains the local date and time of the message, expressed in ISO-8601 format.\r\nFor example, 2016-09-23T13:07:49.4714686-07:00.", - "type": "string" - }, - "localTimezone": { - "description": "Contains the name of the local timezone of the message, expressed in IANA Time Zone database format.\r\nFor example, America/Los_Angeles.", + "description": "Local time when message was sent (set by client, Ex: 2016-09-23T13:07:49.4714686-07:00)", "type": "string" }, "serviceUrl": { - "description": "Contains the URL that specifies the channel's service endpoint. Set by the channel.", + "description": "Service endpoint where operations concerning the activity may be performed", "type": "string" }, "channelId": { - "description": "Contains an ID that uniquely identifies the channel. Set by the channel.", + "description": "ID of the channel where the activity was sent", "type": "string" }, "from": { "$ref": "#/definitions/ChannelAccount", - "description": "Identifies the sender of the message." + "description": "Sender address" }, "conversation": { "$ref": "#/definitions/ConversationAccount", - "description": "Identifies the conversation to which the activity belongs." + "description": "Conversation" }, "recipient": { "$ref": "#/definitions/ChannelAccount", - "description": "Identifies the recipient of the message." + "description": "(Outbound to bot only) Bot's address that received the message" }, "textFormat": { - "description": "Format of text fields Default:markdown", + "description": "Format of text fields [plain|markdown] Default:markdown", "type": "string" }, "attachmentLayout": { - "description": "The layout hint for multiple attachments. Default: list.", + "description": "Hint for how to deal with multiple attachments: [list|carousel] Default:list", "type": "string" }, "membersAdded": { - "description": "The collection of members added to the conversation.", + "description": "Array of address added", "type": "array", "items": { "$ref": "#/definitions/ChannelAccount" } }, "membersRemoved": { - "description": "The collection of members removed from the conversation.", + "description": "Array of addresses removed", "type": "array", "items": { "$ref": "#/definitions/ChannelAccount" } }, - "reactionsAdded": { - "description": "The collection of reactions added to the conversation.", - "type": "array", - "items": { - "$ref": "#/definitions/MessageReaction" - } - }, - "reactionsRemoved": { - "description": "The collection of reactions removed from the conversation.", - "type": "array", - "items": { - "$ref": "#/definitions/MessageReaction" - } - }, "topicName": { - "description": "The updated topic name of the conversation.", + "description": "Conversations new topic name", "type": "string" }, "historyDisclosed": { - "description": "Indicates whether the prior history of the channel is disclosed.", + "description": "True if the previous history of the channel is disclosed", "type": "boolean" }, "locale": { - "description": "A locale name for the contents of the text field.\r\nThe locale name is a combination of an ISO 639 two- or three-letter culture code associated with a language\r\nand an ISO 3166 two-letter subculture code associated with a country or region.\r\nThe locale name can also correspond to a valid BCP-47 language tag.", + "description": "The language code of the Text field", "type": "string" }, "text": { - "description": "The text content of the message.", + "description": "Content for the message", "type": "string" }, "speak": { - "description": "The text to speak.", + "description": "SSML Speak for TTS audio response", "type": "string" }, "inputHint": { - "description": "Indicates whether your bot is accepting,\r\nexpecting, or ignoring user input after the message is delivered to the client.", + "description": "Indicates whether the bot is accepting, expecting, or ignoring input", "type": "string" }, "summary": { - "description": "The text to display if the channel cannot render cards.", + "description": "Text to display if the channel cannot render cards", "type": "string" }, "suggestedActions": { "$ref": "#/definitions/SuggestedActions", - "description": "The suggested actions for the activity." + "description": "SuggestedActions are used to provide keyboard/quickreply like behavior in many clients" }, "attachments": { "description": "Attachments", @@ -670,97 +548,46 @@ } }, "entities": { - "description": "Represents the entities that were mentioned in the message.", + "description": "Collection of Entity objects, each of which contains metadata about this activity. Each Entity object is typed.", "type": "array", "items": { "$ref": "#/definitions/Entity" } }, "channelData": { - "description": "Contains channel-specific content.", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Channel-specific payload" }, "action": { - "description": "Indicates whether the recipient of a contactRelationUpdate was added or removed from the sender's contact list.", + "description": "ContactAdded/Removed action", "type": "string" }, "replyToId": { - "description": "Contains the ID of the message to which this message is a reply.", - "type": "string" - }, - "label": { - "description": "A descriptive label for the activity.", - "type": "string" - }, - "valueType": { - "description": "The type of the activity's value object.", + "description": "The original ID this message is a response to", "type": "string" }, "value": { - "description": "A value that is associated with the activity.", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Open-ended value" }, "name": { - "description": "The name of the operation associated with an invoke or event activity.", + "description": "Name of the operation to invoke or the name of the event", "type": "string" }, "relatesTo": { "$ref": "#/definitions/ConversationReference", - "description": "A reference to another conversation or activity." + "description": "Reference to another conversation or activity" }, "code": { - "description": "The a code for endOfConversation activities that indicates why the conversation ended.", + "description": "Code indicating why the conversation has ended", "type": "string" - }, - "expiration": { - "format": "date-time", - "description": "The time at which the activity should be considered to be \"expired\" and should not be presented to the recipient.", - "type": "string" - }, - "importance": { - "description": "The importance of the activity.", - "type": "string" - }, - "deliveryMode": { - "description": "A delivery hint to signal to the recipient alternate delivery paths for the activity.\r\nThe default delivery mode is \"default\".", - "type": "string" - }, - "listenFor": { - "description": "List of phrases and references that speech and language priming systems should listen for", - "type": "array", - "items": { - "type": "string" - } - }, - "textHighlights": { - "description": "The collection of text fragments to highlight when the activity contains a ReplyToId value.", - "type": "array", - "items": { - "$ref": "#/definitions/TextHighlight" - } - }, - "semanticAction": { - "$ref": "#/definitions/SemanticAction", - "description": "An optional programmatic action accompanying this request" } } }, - "ConversationAccount": { - "description": "Conversation account represents the identity of the conversation within a channel", + "ChannelAccount": { + "description": "Channel account information needed to route a message", "type": "object", "properties": { - "isGroup": { - "description": "Indicates whether the conversation contains more than two participants at the time the activity was generated", - "type": "boolean" - }, - "conversationType": { - "description": "Indicates the type of the conversation in channels that distinguish between conversation types", - "type": "string" - }, - "tenantId": { - "description": "This conversation's tenant ID", - "type": "string" - }, "id": { "description": "Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)", "type": "string" @@ -768,23 +595,23 @@ "name": { "description": "Display friendly name", "type": "string" - }, - "aadObjectId": { - "description": "This account's object ID within Azure Active Directory (AAD)", - "type": "string" - }, - "role": { - "description": "Role of the entity behind the account (Example: User, Bot, etc.)", - "type": "string" } } }, - "MessageReaction": { - "description": "Message reaction object", + "ConversationAccount": { + "description": "Channel account information for a conversation", "type": "object", "properties": { - "type": { - "description": "Message reaction type", + "isGroup": { + "description": "Is this a reference to a group", + "type": "boolean" + }, + "id": { + "description": "Channel id for the user or bot on this channel (Example: joe@smith.com, or @joesmith or 123456)", + "type": "string" + }, + "name": { + "description": "Display friendly name", "type": "string" } } @@ -822,8 +649,8 @@ "type": "string" }, "content": { - "description": "Embedded content", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Embedded content" }, "name": { "description": "(OPTIONAL) The name of the attachment", @@ -836,15 +663,19 @@ } }, "Entity": { - "description": "Metadata object pertaining to an activity", + "description": "Object of schema.org types", "type": "object", "properties": { "type": { - "description": "Type of this entity (RFC 3987 IRI)", + "description": "Entity Type (typically from schema.org types)", "type": "string" } } }, + "Object": { + "type": "object", + "properties": {} + }, "ConversationReference": { "description": "An object relating to a particular point in a conversation", "type": "object", @@ -875,73 +706,25 @@ } } }, - "TextHighlight": { - "description": "Refers to a substring of content within another field", - "type": "object", - "properties": { - "text": { - "description": "Defines the snippet of text to highlight", - "type": "string" - }, - "occurrence": { - "format": "int32", - "description": "Occurrence of the text field within the referenced text, if multiple exist.", - "type": "integer" - } - } - }, - "SemanticAction": { - "description": "Represents a reference to a programmatic action", - "type": "object", - "properties": { - "state": { - "description": "State of this action. Allowed values: `start`, `continue`, `done`", - "type": "string" - }, - "id": { - "description": "ID of this action", - "type": "string" - }, - "entities": { - "description": "Entities associated with this action", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/Entity" - } - } - } - }, "CardAction": { - "description": "A clickable action", + "description": "An action on a card", "type": "object", "properties": { "type": { - "description": "The type of action implemented by this button", + "description": "Defines the type of action implemented by this button.", "type": "string" }, "title": { - "description": "Text description which appears on the button", + "description": "Text description which appear on the button.", "type": "string" }, "image": { - "description": "Image URL which will appear on the button, next to text label", - "type": "string" - }, - "text": { - "description": "Text for this action", - "type": "string" - }, - "displayText": { - "description": "(Optional) text to display in the chat feed if the button is clicked", + "description": "URL Picture which will appear on the button, next to text label.", "type": "string" }, "value": { - "description": "Supplementary parameter for action. Content of this property depends on the ActionType", - "type": "object" - }, - "channelData": { - "description": "Channel-specific data associated with this action", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Supplementary parameter for action. Content of this property depends on the ActionType" } } }, @@ -996,7 +779,7 @@ "type": "object", "properties": { "url": { - "description": "URL thumbnail image for major content property", + "description": "URL Thumbnail image for major content property.", "type": "string" }, "alt": { @@ -1005,7 +788,7 @@ }, "tap": { "$ref": "#/definitions/CardAction", - "description": "Action assigned to specific Attachment" + "description": "Action assigned to specific Attachment.E.g.navigate to specific URL or play/open media content" } } }, @@ -1030,25 +813,6 @@ "message": { "description": "Error message", "type": "string" - }, - "innerHttpError": { - "$ref": "#/definitions/InnerHttpError", - "description": "Error from inner http call" - } - } - }, - "InnerHttpError": { - "description": "Object representing inner http error", - "type": "object", - "properties": { - "statusCode": { - "format": "int32", - "description": "HttpStatusCode from failed request", - "type": "integer" - }, - "body": { - "description": "Body from failed request", - "type": "object" } } }, @@ -1057,15 +821,15 @@ "type": "object", "properties": { "title": { - "description": "Title of this card", + "description": "Title of the card", "type": "string" }, "subtitle": { - "description": "Subtitle of this card", + "description": "Subtitle of the card", "type": "string" }, "text": { - "description": "Text of this card", + "description": "Text of the card", "type": "string" }, "image": { @@ -1073,21 +837,21 @@ "description": "Thumbnail placeholder" }, "media": { - "description": "Media URLs for this card. When this field contains more than one URL, each URL is an alternative format of the same content.", + "description": "Array of media Url objects", "type": "array", "items": { "$ref": "#/definitions/MediaUrl" } }, "buttons": { - "description": "Actions on this card", + "description": "Set of actions applicable to the current card", "type": "array", "items": { "$ref": "#/definitions/CardAction" } }, "shareable": { - "description": "This content may be shared with others (default:true)", + "description": "Is it OK for this content to be shareable with others (default:true)", "type": "boolean" }, "autoloop": { @@ -1095,39 +859,27 @@ "type": "boolean" }, "autostart": { - "description": "Should the client automatically start playback of media in this card (default:true)", + "description": "Should the client automatically start playback of video in this card (default:true)", "type": "boolean" - }, - "aspect": { - "description": "Aspect ratio of thumbnail/media placeholder. Allowed values are \"16:9\" and \"4:3\"", - "type": "string" - }, - "duration": { - "description": "Describes the length of the media content without requiring a receiver to open the content. Formatted as an ISO 8601 Duration field.", - "type": "string" - }, - "value": { - "description": "Supplementary parameter for this card", - "type": "object" } } }, "ThumbnailUrl": { - "description": "Thumbnail URL", + "description": "Object describing a media thumbnail", "type": "object", "properties": { "url": { - "description": "URL pointing to the thumbnail to use for media content", + "description": "url pointing to an thumbnail to use for media content", "type": "string" }, "alt": { - "description": "HTML alt text to include on this thumbnail image", + "description": "Alt text to display for screen readers on the thumbnail image", "type": "string" } } }, "MediaUrl": { - "description": "Media URL", + "description": "MediaUrl data", "type": "object", "properties": { "url": { @@ -1141,69 +893,13 @@ } }, "AudioCard": { - "description": "Audio card", + "description": "A audio card", "type": "object", "properties": { - "title": { - "description": "Title of this card", - "type": "string" - }, - "subtitle": { - "description": "Subtitle of this card", - "type": "string" - }, - "text": { - "description": "Text of this card", - "type": "string" - }, - "image": { - "$ref": "#/definitions/ThumbnailUrl", - "description": "Thumbnail placeholder" - }, - "media": { - "description": "Media URLs for this card. When this field contains more than one URL, each URL is an alternative format of the same content.", - "type": "array", - "items": { - "$ref": "#/definitions/MediaUrl" - } - }, - "buttons": { - "description": "Actions on this card", - "type": "array", - "items": { - "$ref": "#/definitions/CardAction" - } - }, - "shareable": { - "description": "This content may be shared with others (default:true)", - "type": "boolean" - }, - "autoloop": { - "description": "Should the client loop playback at end of content (default:true)", - "type": "boolean" - }, - "autostart": { - "description": "Should the client automatically start playback of media in this card (default:true)", - "type": "boolean" - }, "aspect": { - "description": "Aspect ratio of thumbnail/media placeholder. Allowed values are \"16:9\" and \"4:3\"", + "description": "Aspect ratio of thumbnail/media placeholder, allowed values are \"16x9\" and \"9x16\"", "type": "string" }, - "duration": { - "description": "Describes the length of the media content without requiring a receiver to open the content. Formatted as an ISO 8601 Duration field.", - "type": "string" - }, - "value": { - "description": "Supplementary parameter for this card", - "type": "object" - } - } - }, - "BasicCard": { - "description": "A basic card", - "type": "object", - "properties": { "title": { "description": "Title of the card", "type": "string" @@ -1213,14 +909,18 @@ "type": "string" }, "text": { - "description": "Text for the card", + "description": "Text of the card", "type": "string" }, - "images": { - "description": "Array of images for the card", + "image": { + "$ref": "#/definitions/ThumbnailUrl", + "description": "Thumbnail placeholder" + }, + "media": { + "description": "Array of media Url objects", "type": "array", "items": { - "$ref": "#/definitions/CardImage" + "$ref": "#/definitions/MediaUrl" } }, "buttons": { @@ -1230,48 +930,8 @@ "$ref": "#/definitions/CardAction" } }, - "tap": { - "$ref": "#/definitions/CardAction", - "description": "This action will be activated when user taps on the card itself" - } - } - }, - "MediaCard": { - "description": "Media card", - "type": "object", - "properties": { - "title": { - "description": "Title of this card", - "type": "string" - }, - "subtitle": { - "description": "Subtitle of this card", - "type": "string" - }, - "text": { - "description": "Text of this card", - "type": "string" - }, - "image": { - "$ref": "#/definitions/ThumbnailUrl", - "description": "Thumbnail placeholder" - }, - "media": { - "description": "Media URLs for this card. When this field contains more than one URL, each URL is an alternative format of the same content.", - "type": "array", - "items": { - "$ref": "#/definitions/MediaUrl" - } - }, - "buttons": { - "description": "Actions on this card", - "type": "array", - "items": { - "$ref": "#/definitions/CardAction" - } - }, "shareable": { - "description": "This content may be shared with others (default:true)", + "description": "Is it OK for this content to be shareable with others (default:true)", "type": "boolean" }, "autoloop": { @@ -1279,20 +939,8 @@ "type": "boolean" }, "autostart": { - "description": "Should the client automatically start playback of media in this card (default:true)", + "description": "Should the client automatically start playback of video in this card (default:true)", "type": "boolean" - }, - "aspect": { - "description": "Aspect ratio of thumbnail/media placeholder. Allowed values are \"16:9\" and \"4:3\"", - "type": "string" - }, - "duration": { - "description": "Describes the length of the media content without requiring a receiver to open the content. Formatted as an ISO 8601 Duration field.", - "type": "string" - }, - "value": { - "description": "Supplementary parameter for this card", - "type": "object" } } }, @@ -1304,13 +952,6 @@ "description": "Title of the card", "type": "string" }, - "facts": { - "description": "Array of Fact objects", - "type": "array", - "items": { - "$ref": "#/definitions/Fact" - } - }, "items": { "description": "Array of Receipt Items", "type": "array", @@ -1318,20 +959,27 @@ "$ref": "#/definitions/ReceiptItem" } }, + "facts": { + "description": "Array of Fact Objects Array of key-value pairs.", + "type": "array", + "items": { + "$ref": "#/definitions/Fact" + } + }, "tap": { "$ref": "#/definitions/CardAction", "description": "This action will be activated when user taps on the card" }, "total": { - "description": "Total amount of money paid (or to be paid)", + "description": "Total amount of money paid (or should be paid)", "type": "string" }, "tax": { - "description": "Total amount of tax paid (or to be paid)", + "description": "Total amount of TAX paid(or should be paid)", "type": "string" }, "vat": { - "description": "Total amount of VAT paid (or to be paid)", + "description": "Total amount of VAT paid(or should be paid)", "type": "string" }, "buttons": { @@ -1343,20 +991,6 @@ } } }, - "Fact": { - "description": "Set of key-value pairs. Advantage of this section is that key and value properties will be \r\nrendered with default style information with some delimiter between them. So there is no need for developer to specify style information.", - "type": "object", - "properties": { - "key": { - "description": "The key for this Fact", - "type": "string" - }, - "value": { - "description": "The value for this Fact", - "type": "string" - } - } - }, "ReceiptItem": { "description": "An item on a receipt card", "type": "object", @@ -1391,6 +1025,20 @@ } } }, + "Fact": { + "description": "Set of key-value pairs. Advantage of this section is that key and value properties will be \r\n rendered with default style information with some delimiter between them. So there is no need for developer to specify style information.", + "type": "object", + "properties": { + "key": { + "description": "The key for this Fact", + "type": "string" + }, + "value": { + "description": "The value for this Fact", + "type": "string" + } + } + }, "SigninCard": { "description": "A card representing a request to sign in", "type": "object", @@ -1408,27 +1056,6 @@ } } }, - "OAuthCard": { - "description": "A card representing a request to perform a sign in via OAuth", - "type": "object", - "properties": { - "text": { - "description": "Text for signin request", - "type": "string" - }, - "connectionName": { - "description": "The name of the registered connection", - "type": "string" - }, - "buttons": { - "description": "Action to use to perform signin", - "type": "array", - "items": { - "$ref": "#/definitions/CardAction" - } - } - } - }, "ThumbnailCard": { "description": "A thumbnail card (card with a single, small thumbnail image)", "type": "object", @@ -1466,19 +1093,23 @@ } }, "VideoCard": { - "description": "Video card", + "description": "A video card", "type": "object", "properties": { + "aspect": { + "description": "Aspect ratio (16:9)(4:3)", + "type": "string" + }, "title": { - "description": "Title of this card", + "description": "Title of the card", "type": "string" }, "subtitle": { - "description": "Subtitle of this card", + "description": "Subtitle of the card", "type": "string" }, "text": { - "description": "Text of this card", + "description": "Text of the card", "type": "string" }, "image": { @@ -1486,21 +1117,21 @@ "description": "Thumbnail placeholder" }, "media": { - "description": "Media URLs for this card. When this field contains more than one URL, each URL is an alternative format of the same content.", + "description": "Array of media Url objects", "type": "array", "items": { "$ref": "#/definitions/MediaUrl" } }, "buttons": { - "description": "Actions on this card", + "description": "Set of actions applicable to the current card", "type": "array", "items": { "$ref": "#/definitions/CardAction" } }, "shareable": { - "description": "This content may be shared with others (default:true)", + "description": "Is it OK for this content to be shareable with others (default:true)", "type": "boolean" }, "autoloop": { @@ -1508,20 +1139,8 @@ "type": "boolean" }, "autostart": { - "description": "Should the client automatically start playback of media in this card (default:true)", + "description": "Should the client automatically start playback of video in this card (default:true)", "type": "boolean" - }, - "aspect": { - "description": "Aspect ratio of thumbnail/media placeholder. Allowed values are \"16:9\" and \"4:3\"", - "type": "string" - }, - "duration": { - "description": "Describes the length of the media content without requiring a receiver to open the content. Formatted as an ISO 8601 Duration field.", - "type": "string" - }, - "value": { - "description": "Supplementary parameter for this card", - "type": "object" } } }, @@ -1567,7 +1186,7 @@ "type": "string" }, "type": { - "description": "Type of this entity (RFC 3987 IRI)", + "description": "Entity Type (typically from schema.org types)", "type": "string" } } @@ -1577,16 +1196,16 @@ "type": "object", "properties": { "address": { - "description": "Address of the place (may be `string` or complex object of type `PostalAddress`)", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Address of the place (may be `string` or complex object of type `PostalAddress`)" }, "geo": { - "description": "Geo coordinates of the place (may be complex object of type `GeoCoordinates` or `GeoShape`)", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Geo coordinates of the place (may be complex object of type `GeoCoordinates` or `GeoShape`)" }, "hasMap": { - "description": "Map to the place (may be `string` (URL) or complex object of type `Map`)", - "type": "object" + "$ref": "#/definitions/Object", + "description": "Map to the place (may be `string` (URL) or complex object of type `Map`)" }, "type": { "description": "The type of the thing", @@ -1612,44 +1231,18 @@ } } }, - "TokenRequest": { - "description": "A request to receive a user token", + "TokenParameters": { + "description": "Parameters for creating a token", "type": "object", "properties": { - "provider": { - "description": "The provider to request a user token from", - "type": "string" + "user": { + "$ref": "#/definitions/ChannelAccount", + "description": "User account to embed within the token" }, - "settings": { - "description": "A collection of settings for the specific provider for this request", - "type": "object", - "additionalProperties": { - "type": "object" - } - } - } - }, - "TokenResponse": { - "description": "A response that includes a user token", - "type": "object", - "properties": { - "channelId": { - "description": "The channelId of the TokenResponse", - "type": "string" - }, - "connectionName": { - "description": "The connection name", - "type": "string" - }, - "token": { - "description": "The user token", - "type": "string" - }, - "expiration": { - "description": "Expiration for the token, in ISO 8601 format (e.g. \"2007-04-05T14:30Z\")", + "eTag": { "type": "string" } } } } -} +} \ No newline at end of file diff --git a/packages/azuredeployer.gbapp/services/AzureDeployerService.ts b/packages/azuredeployer.gbapp/services/AzureDeployerService.ts index bb1ec25c..fea9ac88 100644 --- a/packages/azuredeployer.gbapp/services/AzureDeployerService.ts +++ b/packages/azuredeployer.gbapp/services/AzureDeployerService.ts @@ -124,7 +124,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return subscriptionClient.subscriptions.list(); } - public getKBSearchSchema (indexName) { + public getKBSearchSchema (indexName: any) { return { name: indexName, fields: [ @@ -235,7 +235,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { }; } - public async botExists (botId) { + public async botExists (botId: string) { const baseUrl = `https://management.azure.com/`; const username = GBConfigService.get('CLOUD_USERNAME'); const password = GBConfigService.get('CLOUD_PASSWORD'); @@ -257,7 +257,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return !res.parsedBody.valid; } - public async updateBotProxy (botId, group, endpoint) { + public async updateBotProxy (botId: string, group: string, endpoint: string) { const baseUrl = `https://management.azure.com/`; const username = GBConfigService.get('CLOUD_USERNAME'); const password = GBConfigService.get('CLOUD_PASSWORD'); @@ -316,7 +316,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { GBLog.info(`Bot updated at: ${endpoint}.`); } - public async deleteBot (botId: string, group) { + public async deleteBot (botId: string, group: string) { const baseUrl = `https://management.azure.com/`; const username = GBConfigService.get('CLOUD_USERNAME'); const password = GBConfigService.get('CLOUD_PASSWORD'); @@ -338,7 +338,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { GBLog.info(`Bot ${botId} was deleted from the provider.`); } - public async openStorageFirewall (groupName, serverName) { + public async openStorageFirewall (groupName: string, serverName: string) { const subscriptionId = GBConfigService.get('CLOUD_SUBSCRIPTIONID'); @@ -353,7 +353,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { public async deployFarm ( proxyAddress: string, instance: IGBInstance, - credentials, + credentials: any, subscriptionId: string ): Promise { const culture = 'en-us'; @@ -580,7 +580,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { }); } - public async syncBotServerRepository (group, name) { + public async syncBotServerRepository (group: string, name: string) { await this.webSiteClient.webApps.syncRepository(group, name); } @@ -605,7 +605,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { } } - const token = await new StaticAccessToken(); + const token = new StaticAccessToken(); this.cloud = new ResourceManagementClient(token, subscriptionId); this.webSiteClient = new WebSiteManagementClient(token, subscriptionId); @@ -614,7 +614,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { this.searchClient = new SearchManagementClient(token, subscriptionId); } - private async createStorageServer (group, name, administratorLogin, administratorPassword, serverName, location) { + private async createStorageServer (group: string, name: string, administratorLogin: string, administratorPassword: string, serverName: string, location: string) { const params = { location: location, administratorLogin: administratorLogin, @@ -680,7 +680,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { }); } - private async registerProviders (subscriptionId, baseUrl, accessToken) { + private async registerProviders (subscriptionId: string, baseUrl: string, accessToken: string) { const query = `subscriptions/${subscriptionId}/providers/${this.provider}/register?api-version=2018-02-01`; const requestUrl = urlJoin(baseUrl, query); @@ -793,7 +793,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return await httpClient.sendRequest(req); } - private async createSearch (group, name, location) { + private async createSearch (group: string, name: string, location: string) { const params = { sku: { name: this.freeTier ? 'free' : 'standard' @@ -804,7 +804,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return await this.searchClient.services.beginCreateOrUpdateAndWait(group, name, params as any); } - private async createStorage (group, serverName, name, location) { + private async createStorage (group: string, serverName: string, name: string, location: string) { const params = { sku: { name: this.freeTier ? 'Free' : 'Basic' }, createMode: 'Default', @@ -814,7 +814,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return await this.storageClient.databases.beginCreateOrUpdateAndWait(group, serverName, name, params); } - private async createCognitiveServices (group, name, location, kind): Promise { + private async createCognitiveServices (group: string, name: string, location: string, kind: string): Promise { const params = { sku: { name: name @@ -840,40 +840,40 @@ export class AzureDeployerService implements IGBInstallationDeployer { return await this.cognitiveClient.accounts.beginCreateAndWait(group, name, params); } - private async createSpeech (group, name, location): Promise { + private async createSpeech (group: string, name: string, location: string): Promise { return await this.createCognitiveServices(group, name, location, 'SpeechServices'); } - private async createNLP (group, name, location): Promise { + private async createNLP (group: string, name: string, location: string): Promise { return await this.createCognitiveServices(group, name, location, 'LUIS'); } - private async createNLPAuthoring (group, name, location): Promise { + private async createNLPAuthoring (group: string, name: string, location: string): Promise { return await this.createCognitiveServices(group, name, location, 'LUIS.Authoring'); } - private async createSpellChecker (group, name): Promise { + private async createSpellChecker (group: string, name: string): Promise { return await this.createCognitiveServices(group, name, 'westus', 'CognitiveServices'); } - private async createTextAnalytics (group, name, location): Promise { + private async createTextAnalytics (group: string, name: string, location: string): Promise { return await this.createCognitiveServices(group, name, location, 'TextAnalytics'); } - private async createDeployGroup (name, location) { + private async createDeployGroup (name: string, location: string) { const params = { location: location }; return await this.cloud.resourceGroups.createOrUpdate(name, params); } - private async enableResourceProviders (name) { + private async enableResourceProviders (name: string) { const ret = await this.cloud.providers.get(name); if (ret.registrationState === 'NotRegistered') { await this.cloud.providers.register(name); } } - private async createHostingPlan (group, name, location): Promise { + private async createHostingPlan (group: string, name: string, location: string): Promise { const params = { serverFarmWithRichSkuName: name, location: location, @@ -887,7 +887,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { return await this.webSiteClient.appServicePlans.beginCreateOrUpdateAndWait(group, name, params); } - private async createServer (farmId, group, name, location) { + private async createServer (farmId: string, group: string, name: string, location: string) { let tryed = false; const create = async () => { const parameters: Site = { @@ -937,7 +937,7 @@ export class AzureDeployerService implements IGBInstallationDeployer { } } - private async updateWebisteConfig (group, name, serverFarmId, instance: IGBInstance) { + private async updateWebisteConfig (group: string, name: string, serverFarmId: string, instance: IGBInstance) { const parameters: Site = { location: instance.cloudLocation, serverFarmId: serverFarmId, diff --git a/packages/basic.gblib/services/DialogKeywords.ts b/packages/basic.gblib/services/DialogKeywords.ts index 8a919453..b9500092 100644 --- a/packages/basic.gblib/services/DialogKeywords.ts +++ b/packages/basic.gblib/services/DialogKeywords.ts @@ -56,6 +56,7 @@ import Path from 'path'; import sgMail from '@sendgrid/mail'; import mammoth from 'mammoth'; import qrcode from 'qrcode'; +import { json } from 'body-parser'; /** * Base services of conversation to be called by BASIC. @@ -1028,10 +1029,7 @@ export class DialogKeywords { } public async getSingleton({}) { - const executionId = this.sys().getRandomId(); - GBServer.globals.executions[executionId]={}; return { - executionId: executionId, id: this.sys().getRandomId(), username: this.userName(), mobile: this.userMobile(), diff --git a/packages/basic.gblib/services/GBVMService.ts b/packages/basic.gblib/services/GBVMService.ts index 49884def..baddbfea 100644 --- a/packages/basic.gblib/services/GBVMService.ts +++ b/packages/basic.gblib/services/GBVMService.ts @@ -34,6 +34,7 @@ import { GBLog, GBMinInstance, GBService, IGBCoreService, GBDialogStep } from 'botlib'; import * as Fs from 'fs'; +import { GBServer } from '../../../src/app.js'; import { GBDeployer } from '../../core.gbapp/services/GBDeployer.js'; import { TSCompiler } from './TSCompiler.js'; import { CollectionUtil } from 'pragmatismo-io-framework'; @@ -48,6 +49,10 @@ import walkPromise from 'walk-promise'; import child_process from 'child_process'; import Path from 'path'; import indent from 'indent.js'; +import { GBAdminService } from '../../admin.gbapp/services/GBAdminService.js'; +import pkg from 'swagger-client'; +const {Swagger} = pkg; + /** * @fileoverview Decision was to priorize security(isolation) and debugging, * over a beautiful BASIC transpiler (to be done). @@ -1021,7 +1026,11 @@ export class GBVMService extends GBService { const scriptPath = urlJoin(gbdialogPath, `${text}.js`); let code = min.sandBoxMap[text]; - + + const executionId = GBAdminService.getNumberIdentifier(); + GBServer.globals.executions[executionId]={ + executionId: executionId, + }; if (GBConfigService.get('VM3') === 'true') { try { const vm1 = new NodeVM({ diff --git a/packages/basic.gblib/services/vm2-process/index.ts b/packages/basic.gblib/services/vm2-process/index.ts index cb2000be..64605b18 100644 --- a/packages/basic.gblib/services/vm2-process/index.ts +++ b/packages/basic.gblib/services/vm2-process/index.ts @@ -46,7 +46,7 @@ export const createVm2Pool = ({ min, max, ...limits }) => { let stderrCache = ''; - const run = async (code, scope) => { + const run = async (code: any, scope: any) => { const childProcess = spawn( 'cpulimit', [ diff --git a/packages/core.gbapp/services/GBMinService.ts b/packages/core.gbapp/services/GBMinService.ts index e97a2a07..8da3f7e8 100644 --- a/packages/core.gbapp/services/GBMinService.ts +++ b/packages/core.gbapp/services/GBMinService.ts @@ -38,8 +38,7 @@ import cliProgress from 'cli-progress'; import { DialogSet, TextPrompt } from 'botbuilder-dialogs'; import express from 'express'; -import Swagger from 'swagger-client'; - +import SwaggerClient from 'swagger-client'; import removeRoute from 'express-remove-route'; import AuthenticationContext from 'adal-node'; import wash from 'washyourmouthoutwithsoap'; @@ -331,15 +330,14 @@ export class GBMinService { if (process.env.TEST_MESSAGE) { GBLog.info(`Starting auto test with '${process.env.TEST_MESSAGE}'.`); - const client = await new Swagger({ - spec: JSON.parse(Fs.readFileSync('directline-3.0.json', 'utf8')), - usePromise: true - }); - client.clientAuthorizations.add( - 'AuthorizationBotConnector', - new Swagger.ApiKeyAfuthorization('Authorization', `Bearer ${min.instance.webchatKey}`, 'header') - ); - const response = await client.Conversations.Conversations_StartConversation(); + const client = await new SwaggerClient({ + spec:JSON.parse(Fs.readFileSync('directline-3.0.json', 'utf8')), + requestInterceptor: req => { + req.headers["Authorization"] = `Bearer ${min.instance.webchatKey}` + + }}); + + const response = await client.apis.Conversations.Conversations_StartConversation(); const conversationId = response.obj.conversationId; GBServer.globals.debugConversationId = conversationId; @@ -351,7 +349,7 @@ export class GBMinService { }; await CollectionUtil.asyncForEach(steps, async step => { - client.Conversations.Conversations_PostActivity({ + client.apis.Conversations.Conversations_PostActivity({ conversationId: conversationId, activity: { textFormat: 'plain', @@ -411,7 +409,7 @@ export class GBMinService { GBDeployer.mountGBKBAssets(`${instance.botId}.gbkb`, instance.botId, `${instance.botId}.gbkb`); } - public static isChatAPI(req, res) { + public static isChatAPI(req:any, res: any) { if (!res) { return 'GeneralBots'; }