Quick Start

The following sections layout the steps to building and registering a bot, and configuring it to work on one or more channels.

Getting an authentication token

To use the Bot Framework, you must get an authenication token and pass it in the Authentication header with each API request. For information about getting a token, see Authentication.

Note that to get a token, you must have an app ID and password, and to get the app ID and password, you must register your bot (see below).

The following shows the call to get an authentication token.

POST https://login.microsoftonline.com/common/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=<YOUR MICROSOFT APP ID>&client_secret=<YOUR MICROSOFT APP PASSWORD>&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default

The following shows the JSON response to the above request.

HTTP/1.1 200 OK
(other headers) 

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Replying to a user’s message

A conversation is a series of messages exchanged between a user and your bot. When the user sends a message, the connector POSTs a request to your bot’s endpoint that you specified when you registered your bot. The body of the request is an Activity object. Access the type property to determine the type of message that the user sent.

If the user sent a message of type message, create a new Activity object. Set the conversation property to the contents of the conversation property in the user’s message; set the from property to the contents of the recipient property in the user’s message; and set the recipient property to the contents of the from property in the user’s message. Then, set the text and attachments properties as appropriate.

The following shows a message from a user.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "channel's service URL",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

The following shows a reply to the user’s message that prompts them to select an available appointment.

POST https://api.botframework.com/v3/conversations/abcd1234/activities/bf3cc9a2f5de... HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have these times available:",
    "replyToId": "bf3cc9a2f5de..."
}

The following shows the second reply that contains the available times.

POST https://api.botframework.com/v3/conversations/abcd1234/activities/bf3cc9a2f5de... HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.thumbnail",
        "content": {
          "buttons": [
            {
              "type": "imBack",
              "title": "10:30",
              "value": "10:30"
            },
            {
              "type": "imBack",
              "title": "11:30",
              "value": "11:30"
            },
            {
              "type": "openUrl",
              "title": "See more",
              "value": "http://www.contososalon.com/scheduling"
            }
          ]
        }
      }
    ],
    "replyToId": "bf3cc9a2f5de..."
}

For information about adding attachments to messages, see Adding Attachments to a Message.

For information about adding channel-specific data to messages, see Adding Channel Data to a Message.

For information about storing user data, see Saving User Data.

Publishing your bot

You can host your bot on any reachable service such as Azure. For information about hosting your bot on Azure, see Publishing your Bot to Microsoft Azure.

Registering your bot

To use the Bot Framework, you need to register your bot. To register your bot, go to Register a bot and provide your bot’s name, handle, description, and the endpoint that it uses to receive messages. Registration also gathers information about you, the publisher. When you register your bot you also request an app ID and password, which you use to get an authentication token.

Configuring your bot to work on a channel

The Bot Framework supports multiple popular channels such as SMS, Skype, Slack, and Facebook. To configure your bot to work on these channels, go to My bots and sign in. Select the bot that you want to configure, and then select the channel by clicking Add. Follow the configuration steps.

Quick starts for .NET and Node.js

If you’re considering using the .NET SDK or the Node SDK, see Getting Started with the .NET SDK and Getting Started with the Node SDK for quick start guides.