Bot Framework Direct Line API 3.0

https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0
Admin
Bot Framework Direct Line API 3.0 is a REST API that enables clients to authenticate and communicate...
Tokens:17,352
Snippets:195
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Reconnect Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-reconnect-to-conversation

An example of the GET request to generate a new WebSocket stream URL, including a conversation ID and watermark.

```HTTP
GET https://directline.botframework.com/v3/directline/conversations/abc123?watermark=0000a-42
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
```

--------------------------------

### Direct Line API 3.0 Request Example

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Example of a POST request to send an activity to a conversation. The request targets the /v3/directline/conversations/{conversationId}/activities endpoint.

```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

```

--------------------------------

### Get Conversation Activities Response Example

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

This is an example of the JSON response when retrieving activities. The 'watermark' property indicates the latest activity processed, and clients should use this to page through subsequent messages.

```json
{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }, 
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0001",
            "from": {
                "id": "bot1"
            },
            "text": "Nice to see you, user1!"
        }
    ],
    "watermark": "0001a-95"
}

```

--------------------------------

### Start Conversation

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Opens a new conversation with the bot.

```APIDOC
## POST /v3/directline/conversations

### Description
Opens a new conversation with the bot.

### Method
POST

### Endpoint
/v3/directline/conversations

### Parameters
#### Request Body
- **TokenParameters** (object) - Required - A TokenParameters object

### Response
#### Success Response (200)
- **Conversation** (object) - A Conversation object
```

--------------------------------

### Start a New Direct Line Conversation

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Initiates a new conversation with the bot. The request body should be a TokenParameters object.

```http
POST /v3/directline/conversations

```

--------------------------------

### Start Conversation Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-start-conversation

Use this POST request to initiate a new conversation with the Direct Line API. Ensure you include your authorization token in the header.

```http
POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN
```

```http
POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
```

--------------------------------

### Direct Line API 3.0 Error Response Example

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Example of an error response indicating a 'Bad Gateway' status. The response body contains an ErrorResponse object detailing the error code and message.

```http
HTTP/1.1 502 Bad Gateway
[other headers]

```

```json
{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

```

--------------------------------

### Start Conversation Response

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-start-conversation

A successful response to the start conversation request will return a 201 Created status and a JSON object containing the conversation ID, token, token expiration, and a stream URL for WebSocket communication.

```json
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}
```

--------------------------------

### Send Activity Request - HTTP

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Use this endpoint to send an activity to the bot. Ensure the Authorization header contains a valid token obtained from starting a conversation.

```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]

```

--------------------------------

### Retrieve Activities with HTTP GET

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

Use this GET request to retrieve messages for a specific conversation, optionally specifying a watermark to indicate the most recent message seen by the client. Clients should page through activities by advancing the watermark until no more activities are returned.

```http
GET https://directline.botframework.com/v3/directline/conversations/abc123/activities?watermark=0001a-94
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

```

--------------------------------

### Retrieve activities with HTTP GET

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

Clients that are unable to use WebSockets can retrieve activities by using HTTP GET. To retrieve messages for a specific conversation, issue a GET request to the `/v3/directline/conversations/{conversationId}/activities` endpoint, optionally specifying the `watermark` parameter to indicate the most recent message seen by the client. Clients should page through the available activities by advancing the `watermark` value until no activities are returned.

```APIDOC
## GET /v3/directline/conversations/{conversationId}/activities

### Description
Retrieves a set of activities for a given conversation, optionally filtered by a watermark.

### Method
GET

### Endpoint
`/v3/directline/conversations/{conversationId}/activities`

### Parameters
#### Query Parameters
- **watermark** (string) - Optional - The watermark indicating the most recent message seen by the client. Used for pagination.

### Request Example
```http
GET https://directline.botframework.com/v3/directline/conversations/abc123/activities?watermark=0001a-94
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
```

### Response
#### Success Response (200)
- **activities** (array) - An array of activity objects.
- **watermark** (string) - The watermark for the next page of activities.

#### Response Example
```json
{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        },
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0001",
            "from": {
                "id": "bot1"
            },
            "text": "Nice to see you, user1!"
        }
    ],
    "watermark": "0001a-95"
}
```
```

--------------------------------

### Open a new conversation

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-start-conversation

To open a new conversation from your client, issue POST to the /v3/directline/conversations endpoint. This operation starts the conversation, contacts the bot, and creates a WebSocket stream URL.

```APIDOC
## POST /v3/directline/conversations

### Description
Initiates a new conversation with the bot via the Direct Line API.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/conversations

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
HTTP
```
POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN
```

### Response
#### Success Response (201 Created)
Returns details of the newly created conversation.
- **conversationId** (string) - The unique identifier for the conversation.
- **token** (string) - The token to use for subsequent requests to this conversation.
- **expires_in** (integer) - The number of seconds until the token expires.
- **streamUrl** (string) - The URL for receiving activities via WebSocket stream.

#### Response Example (201 Created)
JSON
```json
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}
```

#### Success Response (200 OK)
Returned if a client submits a start conversation request with a Direct Line token that has previously been used to start a conversation. Indicates the request was acceptable but no new conversation was created.

### Notes
- You have 60 seconds to connect to the WebSocket stream URL. If the connection cannot be established within this time, you can reconnect to the conversation to generate a new stream URL.
```

--------------------------------

### Receive activities via WebSocket stream

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

Clients can connect to a WebSocket stream using the `streamUrl` provided in the Start Conversation response. This stream allows for efficient, real-time reception of activities from the bot. The connection does not require an `Authorization` header as the `streamUrl` is pre-authorized.

```APIDOC
## Receive activities via WebSocket stream

### Description
Clients can connect to a WebSocket stream using the `streamUrl` provided in the Start Conversation response. This stream allows for efficient, real-time reception of activities from the bot. The connection does not require an `Authorization` header as the `streamUrl` is pre-authorized.

### Method
GET

### Endpoint
`wss://directline.botframework.com/v3/directline/conversations/{conversationId}/stream?t={token}`

### Headers
- **Upgrade**: websocket
- **Connection**: upgrade
- [other headers]

### Response
#### Success Response (101 Switching Protocols)
- The service responds with status code HTTP 101 ("Switching Protocols").

### Receiving Messages
After connecting via WebSocket, clients can receive:
- An `ActivitySet` containing one or more activities and a watermark.
- An empty message to ensure the connection is valid.
- Additional message types to be defined later.

#### ActivitySet Example
```json
{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }
    ],
    "watermark": "0000a-42"
}
```
```

--------------------------------

### Connect to WebSocket stream

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

Use the streamUrl obtained from the Start Conversation request to connect to the Direct Line service via WebSocket. This connection does not require an Authorization header.

```http
-- connect to wss://directline.botframework.com --
GET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA... HTTP/1.1
Host: directline.botframework.com
Upgrade: websocket
Connection: upgrade
[other headers]


```

--------------------------------

### Get Activities

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Retrieves activities from the bot for the specified conversation. You may optionally supply the `watermark` parameter in the request URI to indicate the most recent message seen by the client.

```APIDOC
## GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

### Description
Retrieves activities from the bot for the specified conversation. You may optionally supply the `watermark` parameter in the request URI to indicate the most recent message seen by the client.

### Method
GET

### Endpoint
/v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.
#### Query Parameters
- **watermark** (string) - Optional - The most recent message seen by the client.

### Response
#### Success Response (200)
- **ActivitySet** (object) - An ActivitySet object. The response contains `watermark` as a property of the `ActivitySet` object. Clients should page through the available activities by advancing the `watermark` value until no activities are returned.
```

--------------------------------

### Get Activities from Direct Line Conversation

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Retrieves activities for a specified conversation. Optionally, provide a watermark to indicate the last seen message. The response includes a watermark for paging.

```http
GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

```

--------------------------------

### Generate New WebSocket Stream URL Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-reconnect-to-conversation

Issue this GET request to generate a new WebSocket stream URL for reconnecting to an existing conversation. Include the conversation ID and an optional watermark to replay messages from a specific point.

```HTTP
GET https://directline.botframework.com/v3/directline/conversations/{conversationId}?watermark={watermark_value}
Authorization: Bearer SECRET_OR_TOKEN
```

--------------------------------

### Get Direct Line Conversation Information

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Retrieves information about an existing conversation and generates a new WebSocket stream URL. Optionally, provide a watermark to indicate the last seen message.

```http
GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

```

--------------------------------

### Generate a new WebSocket stream URL

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-reconnect-to-conversation

To generate a new WebSocket stream URL for reconnecting to an existing conversation, issue a GET request to the conversations endpoint. The conversation ID is required, and a watermark can optionally be included to replay messages from a specific point.

```APIDOC
## GET /conversations/{conversationId}?watermark={watermark_value}

### Description
Generates a new WebSocket stream URL to reconnect to an existing conversation.

### Method
GET

### Endpoint
`https://directline.botframework.com/v3/directline/conversations/{conversationId}?watermark={watermark_value}`

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.

#### Query Parameters
- **watermark** (string) - Optional - The watermark value. If specified, the conversation replays from this watermark. If omitted, only messages received after reconnection are replayed.

### Headers
- **Authorization**: Bearer SECRET_OR_TOKEN

### Request Example
```http
GET https://directline.botframework.com/v3/directline/conversations/abc123?watermark=0000a-42
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
```

### Response
#### Success Response (200)
- **conversationId** (string) - The ID of the conversation.
- **token** (string) - The authentication token.
- **streamUrl** (string) - The new WebSocket stream URL for reconnecting.

#### Response Example
```json
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?watermark=000a-4&t=RCurR_XV9ZA.cwA..."
}
```
```

--------------------------------

### Send an Activity

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Sends an activity to the bot.

```APIDOC
## POST /v3/directline/conversations/{conversationId}/activities

### Description
Sends an activity to the bot.

### Method
POST

### Endpoint
/v3/directline/conversations/{conversationId}/activities

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.
#### Request Body
- **Activity** (object) - Required - An Activity object

### Response
#### Success Response (200)
- **ResourceResponse** (object) - A ResourceResponse that contains an `id` property which specifies the ID of the Activity that was sent to the bot.
```

--------------------------------

### Generate Direct Line Token and User ID in C#

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Use this C# controller to generate a Direct Line token and user ID when enhanced authentication is enabled. Ensure you have the necessary Newtonsoft.Json library for JSON serialization.

```csharp
public class HomeController : Controller
{
    public async Task<ActionResult> Index()
    {
        var secret = GetSecret();

        HttpClient client = new HttpClient();

        HttpRequestMessage request = new HttpRequestMessage(
            HttpMethod.Post,
            $"https://directline.botframework.com/v3/directline/tokens/generate");

        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);

        var userId = $"dl_{Guid.NewGuid()}";

        request.Content = new StringContent(
            JsonConvert.SerializeObject(
                new { User = new { Id = userId } }),
                Encoding.UTF8,
                "application/json");

        var response = await client.SendAsync(request);
        string token = String.Empty;

        if (response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
        }

        var config = new ChatConfig()
        {
            Token = token,
            UserId = userId
        };

        return View(config);
    }
}

public class DirectLineToken
{
    public string conversationId { get; set; }
    public string token { get; set; }
    public int expires_in { get; set; }
}
public class ChatConfig
{
    public string Token { get; set; }
    public string UserId { get; set; }
}
```

--------------------------------

### Get Conversation Information

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Gets information about an existing conversation and also generates a new WebSocket stream URL that a client may use to reconnect to a conversation. You may optionally supply the `watermark` parameter in the request URI to indicate the most recent message seen by the client.

```APIDOC
## GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

### Description
Gets information about an existing conversation and also generates a new WebSocket stream URL that a client may use to reconnect to a conversation. You may optionally supply the `watermark` parameter in the request URI to indicate the most recent message seen by the client.

### Method
GET

### Endpoint
/v3/directline/conversations/{conversationId}?watermark={watermark_value}

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.
#### Query Parameters
- **watermark** (string) - Optional - The most recent message seen by the client.

### Response
#### Success Response (200)
- **Conversation** (object) - A Conversation object
```

--------------------------------

### Send an Activity

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Send a single activity (e.g., message, typing indicator) to the bot. The request includes an Activity object in the body and requires an Authorization header.

```APIDOC
## POST /v3/directline/conversations/{conversationId}/activities

### Description
Send a single activity to the bot. This can include messages, typing indicators, or custom activities.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.

#### Request Body
- **locale** (string) - Optional - The locale of the activity.
- **type** (string) - Required - The type of the activity (e.g., "message").
- **from** (object) - Required - An object representing the sender of the activity.
  - **id** (string) - Required - The ID of the sender.
- **text** (string) - Optional - The text content of the message activity.

### Request Example
HTTP
```
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
```

JSON
```json
{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hello"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the activity that was sent to the bot.

#### Response Example
HTTP
```
HTTP/1.1 200 OK
[other headers]
```

JSON
```json
{
    "id": "0001"
}
```

#### Error Response (502)
- **Bad Gateway** - Returned if the bot generates an error or an incorrect token is used.
```

--------------------------------

### Receive ActivitySet via WebSocket

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-receive-activities

After connecting via WebSocket, the client can receive ActivitySet objects from the Direct Line service. These sets contain activities sent by the bot and users, along with a watermark.

```json
{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }
    ],
    "watermark": "0000a-42"
}

```

--------------------------------

### Send multiple attachments by upload

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Send multiple attachments by uploading them as a multipart request. An optional Activity object can be included to associate with the attachments.

```APIDOC
## POST /conversations/{conversationId}/upload

### Description
Sends multiple attachments by uploading them as a multipart request. An optional Activity object can be included.

### Method
POST

### Endpoint
/v3/directline/conversations/{conversationId}/upload

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user sending the message.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be `multipart/form-data` with a boundary specified.

### Request Body Structure
The request body consists of multiple parts, each representing an attachment or an Activity.

- **Attachment Part**: Requires `Content-Type` and `Content-Disposition` headers for each attachment.
- **Activity Part**: Requires `Content-Type` header set to `application/vnd.microsoft.activity`.

### Request Example
```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89

----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"

[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity

{
  "type": "message",
  "from": {
    "id": "user1"
  },
  "text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}

----DD4E5147-E865-4652-B662-F223701A8A89
```

### Response
#### Success Response (200)
Returns an object containing the ID of the sent Activity.

#### Response Example
```json
{
    "id": "0004"
}
```
```

--------------------------------

### Generate Direct Line Token and User ID in JavaScript

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

This JavaScript controller uses the express framework to obtain a Direct Line token and user ID. It requires the 'request' library for making HTTP requests.

```javascript
var router = express.Router(); // get an instance of the express Router

// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();

router.get('/config', function(req, res) {
    const options = {
        method: 'POST',
        uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
        headers: {
            'Authorization': 'Bearer ' + secret
        },
        json: {
            User: { Id: userId }
        }
    };

    request.post(options, (error, response, body) => {
        if (!error && response.statusCode < 300) {
            res.json({
                    token: body.token,
                    userId: userId
                });
        }
        else {
            res.status(500).send('Call to retrieve token from Direct Line failed');
        }
    });
});

```

--------------------------------

### Upload and Send File(s)

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Uploads and sends file(s) as attachment(s). Set the `userId` parameter in the request URI to specify the ID of the user that is sending the attachment(s).

```APIDOC
## POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

### Description
Uploads and sends file(s) as attachment(s). Set the `userId` parameter in the request URI to specify the ID of the user that is sending the attachment(s).

### Method
POST

### Endpoint
/v3/directline/conversations/{conversationId}/upload?userId={userId}

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.
- **userId** (string) - Required - The ID of the user that is sending the attachment(s).
#### Request Body
- **File contents** (binary) - Required - For a single attachment, populate the request body with the file contents. For multiple attachments, create a multipart request body that contains one part for each attachment, and also (optionally) one part for the Activity object that should serve as the container for the specified attachment(s). For more information, see Send an activity to the bot.

### Response
#### Success Response (200)
- **ResourceResponse** (object) - A ResourceResponse that contains an `id` property which specifies the ID of the Activity that was sent to the bot.

### Note
Uploaded files are deleted after 24 hours.
```

--------------------------------

### Send Multiple Attachments by Upload (HTTP Request)

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

To send multiple attachments, use a multipart request with Content-Type set to 'multipart/form-data'. Each attachment requires its own Content-Type and Content-Disposition headers. An optional Activity part can be included.

```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]

----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]

[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]

{
  "type": "message",
  "from": {
    "id": "user1"
  },
  "text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}

----DD4E5147-E865-4652-B662-F223701A8A89

```

--------------------------------

### Generate Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Generates a token that is valid for one conversation.

```APIDOC
## POST /v3/directline/tokens/generate

### Description
Generates a token that is valid for one conversation.

### Method
POST

### Endpoint
/v3/directline/tokens/generate

### Parameters
#### Request Body
- **TokenParameters** (object) - Required - A TokenParameters object

### Response
#### Success Response (200)
- **Conversation** (object) - A Conversation object
```

--------------------------------

### Upload and Send File(s) via Direct Line

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Uploads and sends file(s) as attachments to the bot. Specify the sending user ID in the request URI. The request body can be file content or a multipart request.

```http
POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

```

--------------------------------

### Authentication Header

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

All Direct Line API requests must include an Authorization header specifying a secret or token for authentication.

```APIDOC
## Headers
In addition to the standard HTTP request headers, a Direct Line API request must include an `Authorization` header that specifies a secret or token to authenticate the client that is issuing the request. Specify the `Authorization` header using this format:
```
Authorization: Bearer SECRET_OR_TOKEN
```
```

--------------------------------

### Generate Direct Line Token Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Use this POST request to generate a token for a Direct Line conversation. Include an optional JSON payload with user details and trusted origins for enhanced security and to enable immediate conversation updates.

```http
POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
```

```json
{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
```

--------------------------------

### Send Activity Response - Success

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

A successful response to a Send Activity request will return a 200 OK status and a JSON payload containing the ID of the activity that was sent.

```http
HTTP/1.1 200 OK
[other headers]

```

--------------------------------

### Send Attachments by URL

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Include attachment(s) within an Activity object by specifying their URLs in the `contentUrl` property. This method uses the same endpoint as sending a regular activity.

```APIDOC
## POST /v3/directline/conversations/{conversationId}/activities (with attachments)

### Description
Send one or more attachments as part of an Activity object by including Attachment objects with a `contentUrl` property set to the attachment's URI.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.

#### Request Body
- **locale** (string) - Optional - The locale of the activity.
- **type** (string) - Required - The type of the activity (e.g., "message").
- **from** (object) - Required - An object representing the sender of the activity.
  - **id** (string) - Required - The ID of the sender.
- **attachments** (array) - Optional - An array of Attachment objects.
  - **contentType** (string) - Required - The MIME type of the attachment.
  - **contentUrl** (string) - Required - The HTTP, HTTPS, or `data` URI of the attachment.
  - **name** (string) - Optional - The name of the attachment.
```

--------------------------------

### Generate Direct Line Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Use this endpoint to generate a token valid for a single conversation. The request body should contain a TokenParameters object.

```http
POST /v3/directline/tokens/generate

```

--------------------------------

### Send an Activity to Direct Line

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Sends an activity to the bot within a conversation. The request body should be an Activity object.

```http
POST /v3/directline/conversations/{conversationId}/activities

```

--------------------------------

### Authorization Header Format

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

The secret or token should be specified in the `Authorization` header of each request.

```APIDOC
## Authorization Header

### Description
Clients must include an `Authorization` header with each request to Direct Line API 3.0.

### Header
- **Authorization**: Bearer SECRET_OR_TOKEN
```

--------------------------------

### Send Attachments by Upload

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Upload one or more attachments directly to the bot using a dedicated endpoint. The request format depends on whether a single or multiple attachments are being sent.

```APIDOC
## POST /v3/directline/conversations/{conversationId}/upload

### Description
Upload one or more attachments directly to the bot when you do not have URLs for the files. The request format varies for single vs. multiple attachments.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The ID of the conversation.
```

--------------------------------

### Token Operations

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Operations available for managing tokens, including generating new tokens and refreshing existing ones for conversation access.

```APIDOC
## Token operations
Use these operations to create or refresh a token that a client can use to access a single conversation.
Expand table
Operation | Description  
---|---  
Generate Token | Generate a token for a new conversation.  
Refresh Token | Refresh a token.  
```

--------------------------------

### Send Single Attachment by Upload (HTTP Request)

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Use this request to send a single attachment to a conversation. Ensure the Content-Type and Content-Disposition headers are correctly set for the attachment.

```http
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]

[file content]
```

```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]

[JPEG content]
```

--------------------------------

### Refresh Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Refreshes the token.

```APIDOC
## POST /v3/directline/tokens/refresh

### Description
Refreshes the token.

### Method
POST

### Endpoint
/v3/directline/tokens/refresh

### Parameters
#### Request Body
- **n/a**

### Response
#### Success Response (200)
- **Conversation** (object) - A Conversation object
```

--------------------------------

### Authorization Header Format

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Use this format for the Authorization header in Direct Line API requests. Replace SECRET_OR_TOKEN with your Direct Line secret or a generated token.

```http
Authorization: Bearer SECRET_OR_TOKEN

```

--------------------------------

### Send Multiple Attachments Response (JSON)

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

A successful response for multiple attachment uploads will return a JSON object containing the ID of the sent Activity.

```json
{
    "id": "0004"
}
```

--------------------------------

### Reconnect Response with Stream URL

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-reconnect-to-conversation

A successful HTTP 200 OK response containing the conversation ID, token, and a new WebSocket stream URL for reconnection.

```HTTP
HTTP/1.1 200 OK
[other headers]
```

```JSON
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?watermark=000a-4&amp;t=RCurR_XV9ZA.cwA..."
}
```

--------------------------------

### Authorization Header Format

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication

All requests to the Direct Line API 3.0 must include an Authorization header with either a secret or a token.

```APIDOC
## Authorization Header

### Description
All requests to the Direct Line API 3.0 must include an `Authorization` header with either a secret or a token.

### Format
```
Authorization: Bearer SECRET_OR_TOKEN
```
```

--------------------------------

### Generate Direct Line Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Generates a Direct Line token that can be used to access a single conversation. Providing user information and trusted origins in the request payload enhances security and enables immediate conversation updates.

```APIDOC
## POST /v3/directline/tokens/generate

### Description
Generates a Direct Line token for a conversation. The request payload is optional but recommended for enhanced security and immediate conversation updates.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/tokens/generate

### Parameters
#### Request Body
- **user** (object) - Optional. Contains user information.
  - **id** (string) - Required. Channel-specific ID of the user. Must begin with `dl_` for Direct Line users. Should be unique and unguessable per conversation.
  - **name** (string) - Optional. Display-friendly name of the user.
- **trustedOrigins** (string array) - Optional. A list of trusted domains that can host the bot's Web Chat client. Must match the Direct Line configuration for your bot.

### Request Example
```json
{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
```

### Response
#### Success Response (200)
- **conversationId** (string) - The ID of the conversation.
- **token** (string) - The generated Direct Line token.
- **expires_in** (integer) - The number of seconds until the token expires.

#### Response Example
```json
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}
```
```

--------------------------------

### Send a single attachment by upload

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

Send a single attachment by uploading it to a conversation. The request includes attachment details in headers and the file content in the body.

```APIDOC
## POST /conversations/{conversationId}/upload

### Description
Sends a single attachment by uploading it to a specified conversation.

### Method
POST

### Endpoint
/v3/directline/conversations/{conversationId}/upload

### Parameters
#### Query Parameters
- **userId** (string) - Required - The ID of the user sending the message.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - The MIME type of the attachment (e.g., `image/jpeg`).
- **Content-Disposition** (string) - Required - Attachment information, including filename.

### Request Example
```http
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"

[JPEG content]
```

### Response
#### Success Response (200)
Returns an object containing the ID of the sent Activity.

#### Response Example
```json
{
  "id": "0003"
}
```
```

--------------------------------

### Send Activity Response - Success Payload

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

This JSON payload indicates the successful delivery of an activity to the bot, providing the unique ID assigned to that activity.

```json
{
    "id": "0001"
}

```

--------------------------------

### Send Activity Request - JSON Payload

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-send-activity

This JSON object represents a 'message' activity being sent to the bot. It includes the locale, type, sender's ID, and the text of the message.

```json
{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hello"
}

```

--------------------------------

### Generate Direct Line Token Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Send a POST request to this endpoint to exchange a Direct Line secret for a Direct Line token. Ensure the Authorization header includes your Direct Line secret.

```http
POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer SECRET

```

--------------------------------

### Generate Direct Line Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Exchange a Direct Line secret for a Direct Line token that can be used to access a single conversation.

```APIDOC
## Generate Direct Line Token

### Description
This endpoint generates a Direct Line token that is valid for a single conversation and has an expiration.

### Method
POST

### Endpoint
https://directline.botframework.com/v3/directline/tokens/generate

### Parameters
#### Request Header
- **Authorization** (string) - Required - The Direct Line secret, formatted as `Bearer SECRET`.

### Request Example
```http
POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer YOUR_DIRECT_LINE_SECRET
```

### Response
#### Success Response (200)
- **token** (string) - The generated Direct Line token.
- **conversationId** (string) - The ID of the conversation associated with the token.
- **expires_in** (integer) - The time in seconds until the token expires.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "conversationId": "someConversationId",
  "expires_in": 7200
}
```
```

--------------------------------

### Refresh Direct Line Token

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference

Use this endpoint to refresh an existing token. No request body is required.

```http
POST /v3/directline/tokens/refresh

```

--------------------------------

### Refresh Direct Line Token Request

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

Issue this POST request to refresh an existing Direct Line token. Ensure the token has not expired, as expired tokens cannot be refreshed.

```http
POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED
```

```http
POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
```

--------------------------------

### Generate Direct Line Token Response

Source: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0

A successful response contains a conversation ID, a token valid for one conversation, and the token's expiration time in seconds. Refresh the token before it expires to maintain usability.

```http
HTTP/1.1 200 OK
[other headers]
```

```json
{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800
}
```
Tokens:
Raw