Direct Line API 3.0

You can enable communication between your bot and Unity by using the Direct Line API.
I will explain how to do it in Unity but before, let me provide some information about the mechanism.

Authentication

Direct Line API 3.0 requests can be authenticated either by using a secret that you obtain from the Direct Line channel configuration page in the Azure Portal or by using a token that you obtain at runtime.

  • A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. A secret can also be used to obtain a token. Secrets do not expire.
  • A Direct Line token is a key that can be used to access a single conversation. A token expires but can be refreshed.

Starting conversation

https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-start-conversation?view=azure-bot-service-4.0

Direct Line conversations are explicitly opened by clients and may run as long as the bot and client participate and have valid credentials. While the conversation is open, both the bot and client may send messages.

More than one client may connect to a given conversation and each client may participate on behalf of multiple users.

To open conversation, issue a POST Request to the endpoint

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET OR TOKEN

If the request is successful, the response will contain an ID for the conversation, a token, a value that indicates the number of seconds until the token expires, and a stream URL that the client may use to receive activities.

{
  "conversationId": "-ABC-",
  "token": "-123-",
  "expires_in": 3600,
  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/-ABC-/stream?watermark=-&t=-123-",
  "referenceGrammarId": "ddf0cd2c-b093-595c-b951-8431afebed17"
}

To perform this action in Unity, we have to:

  1. Call the HTTP Service and store the answer for later purpose.
  2. Initiate discussion to have the greetings (optional – see Microsoft Bot Channel activities)
class Conversation
{
    public string conversationId;
    public string token;
    public string expires_in;
    public string streamUrl;
    public string referenceGrammarId;
}

You can find the full code on Github : YAKAGameStudio/unity-chatbot-azure (github.com)

Sending messages

By using Direct Line API, Unity can send messages to your bot by issuing HTTP POST requests.

You may send a single message per request.

To send a message to the bot, the client must create an Activity and then issue a request to https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, specifying the Activity object in the body of the request.

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA
Content-Type: application/json

Activity must at least to provide sender identity and text, as shown bellow

{
  "type": "message",
  "from": {
    "id": "user1"
  },
  "text": "hello"
}

When the activity is delivered to the bot, the service responds with an HTTP status code that reflects the bot’s status code. If the POST is successful, the response contains a JSON payload that specifies the ID of the Activity that was sent to the bot.

class Activity
{
    public string type;
    public string id;
    public DateTime timestamp;
    public string channelId;
    public UserAccount from;
    public ConversationReference conversation;
    public string text;
    public string textFormat;
    public string inputHint;
    public string replyToId;
}
class UserAccount
{
    public string id;
    public string name;
}
class ConversationReference
{
    public string id;
}

You can find the full code on Github : YAKAGameStudio/unity-chatbot-azure (github.com)

Receiving messages

Using Direct Line API 3.0, a client can receive messages from your bot either via WebSocket stream or by issuing HTTP GET requests. Using either of these techniques, a client may receive multiple messages from the bot at a time as part of an ActivitySet.

In Unity, you can manage HTTP request with the native UnityWebRequest (UWR) or rely on Nuget Package to implement Websockets.

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.

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

The Get Conversation Activities response contains watermark as a property of the ActivitySet. Clients should page through the available activities by advancing the watermark value until no activities are returned.

{
    "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"
}
class Activities
{
    public List<Activity> activities;
    public string watermark;
}

You can find the full code on Github : YAKAGameStudio/unity-chatbot-azure (github.com)

Share for immortality
Default image
Laurent LEFEVRE

I'm a Microsoft employee, working on Technology Strategy for large Enterprise account.
I focus on industry business trends and explain how you can leverage Azure Game Stack & Xbox services.
I assume that I don't know anything. This is a great habit to do a full knowledge refresh and avoiding bias.