API reference - Direct Line API 3.0

APPLIES TO: SDK v3

You can enable your client application to communicate with your bot by using Direct Line API 3.0. Direct Line API 3.0 uses industry-standard REST and JSON over HTTPS.

Base URI

To access Direct Line API 3.0, use this base URI for all API requests:

https://directline.botframework.com

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

For details about how to obtain a secret or token that your client can use to authenticate its Direct Line API requests, see Authentication.

HTTP status codes

The HTTP status code that is returned with each response indicates the outcome of the corresponding request.

HTTP status code	Meaning
200	The request succeeded.
201	The request succeeded.
202	The request has been accepted for processing.
204	The request succeeded but no content was returned.
400	The request was malformed or otherwise incorrect.
401	The client is not authorized to make the request. Often this status code occurs because the Authorization header is missing or malformed.
403	The client is not allowed to perform the requested operation. If the request specified a token that was previously valid but has expired, the code property of the Error that is returned within the ErrorResponse object is set to TokenExpired.
404	The requested resource was not found. Typically this status code indicates an invalid request URI.
500	An internal server error occurred within the Direct Line service.
502	The bot is unavailable or returned an error. This is a common error code.

Note

HTTP status code 101 is used in the WebSocket connection path, although this is likely handled by your WebSocket client.

Errors

Any response that specifies an HTTP status code in the 4xx range or 5xx range will include an ErrorResponse object in the body of the response that provides information about the error. If you receive an error response in the 4xx range, inspect the ErrorResponse object to identify the cause of the error and resolve your issue prior to resubmitting the request.

Note

HTTP status codes and values specified in the code property inside the ErrorResponse object are stable. Values specified in the message property inside the ErrorResponse object may change over time.

The following snippets show an example request and the resulting error response.

Request

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

Response

HTTP/1.1 502 Bad Gateway
[other headers]

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

Token operations

Use these operations to create or refresh a token that a client can use to access a single conversation.

Operation	Description
Generate Token	Generate a token for a new conversation.
Refresh Token	Refresh a token.

Generate Token

Generates a token that is valid for one conversation.

POST /v3/directline/tokens/generate

Request body	A TokenParameters object
Returns	A Conversation object

Refresh Token

Refreshes the token.

POST /v3/directline/tokens/refresh

Request body	n/a
Returns	A Conversation object

Conversation operations

Use these operations to open a conversation with your bot and exchange activities between client and bot.

Operation	Description
Start Conversation	Opens a new conversation with the bot.
Get Conversation Information	Gets information about an existing conversation. This operation generates a new WebSocket stream URL that a client may use to reconnect to a conversation.
Get Activities	Retrieves activities from the bot.
Send an Activity	Sends an activity to the bot.
Upload and Send File(s)	Uploads and sends file(s) as attachment(s).

Start Conversation

Opens a new conversation with the bot.

POST /v3/directline/conversations

Request body	A TokenParameters object
Returns	A Conversation object

Get Conversation Information

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.

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

Request body	n/a
Returns	A Conversation object

Get Activities

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.

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

Request body	n/a
Returns	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.

Send an Activity

Sends an activity to the bot.

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

Request body	An Activity object
Returns	A ResourceResponse that contains an id property which specifies the ID of the Activity that was sent to the bot.

Upload and Send File(s)

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).

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

Request body	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.
Returns	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.

Schema

The Direct Line 3.0 schema includes all of the objects that are defined by the Bot Framework schema as well as some objects that are specific to Direct Line.

ActivitySet object

Defines a set of activities.

Property	Type	Description
activities	Activity[]	Array of Activity objects.
watermark	string	Maximum watermark of activities within the set. A client may use the watermark value to indicate the most recent message it has seen either when retrieving activities from the bot or when generating a new WebSocket stream URL.

Conversation object

Defines a Direct Line conversation.

Property	Type	Description
conversationId	string	ID that uniquely identifies the conversation for which the specified token is valid.
eTag	string	An HTTP ETag (entity tag).
expires_in	number	Number of seconds until the token expires.
referenceGrammarId	string	ID for the reference grammar for this bot.
streamUrl	string	URL for the conversation's message stream.
token	string	Token that is valid for the specified conversation.

TokenParameters object

Parameters for creating a token.

Property	Type	Description
eTag	string	An HTTP ETag (entity tag).
trustedOrigins	string[]	Trusted origins to embed within the token.
user	ChannelAccount	User account to embed within the token.

Activities

For each Activity that a client receives from a bot via Direct Line:

• Attachment cards are preserved.
• URLs for uploaded attachments are hidden with a private link.
• The channelData property is preserved without modification.

Clients may receive multiple activities from the bot as part of an ActivitySet.

When a client sends an Activity to a bot via Direct Line:

• The type property specifies the type activity it is sending (typically message).
• The from property must be populated with a user ID, chosen by the client.
• Attachments may contain URLs to existing resources or URLs uploaded through the Direct Line attachment endpoint.
• The channelData property is preserved without modification.
• The total size of the activity, when serialized to JSON and encrypted, must not exceed 256K characters. Therefore it is recommended that activities are kept under 150K. If more data is needed consider breaking the activity into multiple and/or consider using attachments.

Clients may send a single activity per request.

Additional resources

• Bot Framework Activity spec