Getting Started

You’ve come to the right place to build and publish a Skype bot - with cards, groups and calling - using the Microsoft Bot Framework.

Creating a Skype bot

All bots created using the Microsoft Bot Framework are automatically configured and ready to work in Skype.

See the Microsoft Bot Framework Overview to learn how to:

  1. Build a bot using the C# SDK, Node.js SDK or REST API
  2. Test it using the Bot Framework Emulator
  3. Deploy the bot to a cloud service, such as Microsoft Azure
  4. Register the bot with the Microsoft Bot Framework, which will automatically add Skype as a channel. When you first register a bot it will be in Preview, which means it can be added by up to 100 users using an add button or URL. To remove the limit you can easily publish it in Skype via the Microsoft Bot Framework Portal.
  5. Add the bot and test it using the latest version of Skype

Publishing

Publish your bot from the Bot Dashboard to remove user limits and request for it to be shown in the Skype app bot directory and Microsoft bot directory. You can choose to automatically show in directories, or enable it later from the Bot Dashboard. Skype will review your bot to remove the limit, and may select it for the Skype app bot directory and/or Microsoft bot directory.

Please make sure to read the Best Practices, Review Guidelines, Terms of use and Code of Conduct before publishing your bot.

The Terms of Use contains Sample Terms you can use to help create your own Terms of Service and the Code of Conduct contains links to third party Privacy Statement resources.

Finding and adding bots in Skype

Users can find and add your Skype bot in several ways.

Add button or URL

You can create an add button here or copy and paste the add URL from the bot dashboard which will look like this https://join.skype.com/bot/YourAppID e.g.https://join.skype.com/bot/29415286-5a43-4a00-9dc5-bcbc2ce1f59e.

Add button

When a user taps or clicks the add button or add URL they will be prompted to sign into Skype if necessary and redirected to a web page with information about your bot and its capabilities. After they tap to add your bot they will be redirected straight into a chat with the bot in a Skype app or the Skype web app.

Add to contacts

Skype bot directory

In specific markets (Currently USA, Canada, UK, Ireland, Australia, and New Zealand) Skype users will see an Add bots button which opens the Skype bot directory.

Search for a bot

Find a bot

View bot profile

Welcome page

Microsoft bot directory

Bots that are approved for Skype will also appear in the Microsoft bot directory

How a bot appears in Skype

Once a bot has been added it will appear in your conversation history in the same way as a chat with another user, but with a hexagonal avatar.

Bot in Skype

Bots in Skype always appear online and do not have a mood message

Messages

Your bot can send rich text, emoticons, pictures and cards to a user or group. Users can send rich text and pictures to your bot. You can specify the type of content your bot can handle in the Skype settings page for your bot.

  From user to bot From bot to user  
Rich text Including emoticons :)
Pictures PNG, JPEG or GIF up to 20Mb
Video Coming soon MP4, AAC+h264 up to 15Mb (approx. 1 minute), plus JPEG thumbnail
Cards  

Basic format

Each Skype user is assigned a unique ID for your bot, which is sent along with the Display Name with every message.

{
  "text": "Hello (wave)",
  "id": "1466182688092",
  "type": "message/text",
  "timestamp": "2016-06-17T16:58:08.74Z",
  "channelId": "skype",
  "serviceUrl": "https://apis.skype.com",
  "from": {
    "id": "29:2hJJkjmGn4ljB2X7YYEju-sgFwgvnISvE6G3abGde8ts",
    "name": "Display Name"
  },
  "conversation": {
    "id": "29:2hJJkjmGn4ljB2X7YYEju-sgFwgvnISvE6G3abGde8ts"
  },
  "recipient": {
    "id": "28:29415286-5a43-4a00-9dc5-bcbc2ce1f59e",
    "name": "Trivia Master"
  }
}

The from field contains the unique user ID (prefixed by 29:) and user Display Name. The to field contains the App ID (prefixed by 28: which indicates a bot in Skype) and bot Display Name.

Note: You cannot currently use slash (“/”) commands as part of conversations with your bot. This is a reserved character in Skype.

Rich text

For Skype you should set the TextFormat property to XML. Skype supports Bold, Italic, Underline, Strikethrough and link tags.

Skype emoticons

Skype emoticons can be sent by using emoticon keyword in parentheses.

{
  "text": "(heart)"
}

Heart emoticon

Note If a user sends your bot an emoticon it may include <ss> tags around the emoticon, which can be ignored e.g. <ss type=\"skype\">(wave)</ss>
Note Sending Skype Mojis (short, expressive video clips) is not currently supported.

Welcome messages

To send a welcome message to a user listen for the contactRelationUpdate activity. To send a welcome message to a group list for the conversationUpdate activity.

Pictures and videos

Pictures and videos are sent by adding attachments to a message.

Pictures can be PNG, JPEG or GIF up to 20Mb.

Videos can be MP4, AAC+h264 up to 15Mb (approx. 1 minute), plus JPEG thumbnail. To send a video cards with inline playback, autostart and autoloop properties see Video cards.

Typing indicator

Your bot can send a typing indicator using the C# SDK, Node.js SDK or REST API to tell the user that the bot is preparing to respond, for example when processing a request.

Cards and buttons

Skype supports the following cards which may have several properties and attachments. You can find information on how to use cards in the .NET SDK and Node.js SDK docs.

  • Hero card
  • Thumbnail card
  • Video card
  • Audio card
  • Animated GIF card
  • Carousel card (with hero or thumbnail images)
  • Sign in card
  • Receipt card
Note: Images sent to Skype cards need to be stored on an HTTPS endpoint
Note: Skype cards do not currently support postBack actions

Images

Images are scaled up or down in size while maintaining the aspect ratio to cover the image area, and then cropped from center to achieve the image aspect ratio for the card.

Images should be HTTPS, up to 1024x1024, up to 1MB in size, and PNG or JPEG.

Property Type Description
url URL URL to the image. Must be HTTPS
alt String Accessible description of the image
value String Action assigned to the image

Buttons

Buttons are shown at the bottom of the card - in a single row if they fit, or stacked. Button text is always on a single line and will be trimmed if too long. If more buttons than can be supported by the card are included the will not be shown.

Actions

Property Type Description
type string Required field. One of openURL (opens the given URL), imBack (posts a message in the chat to the bot that sent the card), call (skype or phone number), showImage (for images only, displays the image), signin (sign in card only).
title String Text description that appears on the button
tap Action object Value depending on the type of action. For openURL is a URL, for signin is the URL to the authentication flow, for imBack is a user defined string, for call can be “skype:skypeid” or “tel:telephone”, for showImage not required.

Sending context with actions

It can be useful to send context back to your bot (e.g. a request ID) without showing this information to the user in a message. To do this you can append hidden XML to the visible string shown to the user, which is only seen by your bot.

Visible message &lt;context hiddenId='10'/&gt;

Hero card

The hero card renders a title, subtitle, text, large image and buttons.

Hero card

The hero card provides a very flexible layout, for example it might contain:

  • Image, title, subtitle, text + 3 buttons
  • Title, subtitle, text + 5 buttons
  • Title + 6 buttons
  • Image + 6 buttons
Property Type Description
title Rich text Title of the card. Maximum 2 lines
subtitle Rich text Subtitle appears just below the Title. Maximum 2 lines
text Rich text Text appears just below the subtitle. 2, 4 or 6 lines depending on whether title and subtitle are specified
images:[] Array of images Image displayed at top of card. Aspect ratio 16:9
buttons:[] Array of action objects Set of actions applicable to the current card. 3 buttons up to a maximum of 6 (+2 if no image is shown, +1 if title or subtitle not included, +2 if text is not included)
tap Action object This action will be activated when the user taps on the card itself

Thumbnail card

The thumbnail card renders a title, subtitle, text, small thumbmail image and buttons.

Thumbnail card

Property Type Description
title Rich text Title of the card. Maximum 2 lines
subtitle Rich text Subtitle appears just below the Title. Maximum 2 lines
text Rich text Text appears just below the subtitle. 2, 4 or 6 lines depending on whether title and subtitle are specified
images Array of images Image displayed at top of card. The image aspect ratio in a thumbnail card is 1:1
buttons Array of action objects Set of actions applicable to the current card. Maximum 3 buttons.
tap Action object This action will be activated when the user taps on the card itself

Video card

Use the Bot Connector REST API video card to send a video card with inline playback, autostart and autoloop controls. The content is served directly from your own service. Video can be set to automatically play by setting the autoplay capability in the Skype channel settings for your bot, which notifies the user that content will be autoplayed from an external source.

Skype supported properties

Property Type Description
title Rich text Title text
subtitle Rich text Subtitle text
image.url URL Mandatory thumbnail image 360x202, 202x360 (JPEG)
image.alt String Image text used by screenreaders
media[] Array List of media objects each with a single profile.
media.url URL (must be HTTPS) URL to media source which can be SD (360x202 or 202x360, ~300kpbs, H.264 AAC) or HD (1280x720, 720x1280 ~1.5 mbps, H.264 AAC)
media.profile string Name of profile (sd or hd).
aspect string Aspect ratio of thumbnail. Allowed values are 16:9 or 9:16.
autostart Boolean Automatically play muted media as soon as it is received. This the autoplay setting to be in the Skype channel setting, which notifies the user that media will be autoplayed from an external source
autoloop Boolean Automatically loop media when set to true.
buttons Array of action objects Set of button actions applicable to the current card. Maximum 3 buttons.

Example JSON

{
  "type": "message/card",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.video",
      "content": {
        "title": "Video card",
        "subtitle": "About this video",
        "aspect": "16:9",
        "autoloop": true,
        "autostart": true,
        "image": { "url": "https://c.s-microsoft.com/en-gb/CMSImages/Ofc365_Enterprise_1201_540x304_ROW.jpg?version=abf91106-cacc-e236-fd10-59e8b612bea6" },
        "media": [
          {
            "profile": "hd",
            "url": "https://archive.org/download/BigBuckBunny_328/BigBuckBunny_512kb.mp4"
          }
        ],
        "buttons": [
          {
            "type": "imBack",
            "title": "More like this",
            "value": "More like this"
          },
          {
            "type": "imBack",
            "title": "No more like this",
            "value": "No more like this"
          }
        ]
      }
    }
  ]
}

Audio card

Use the Bot Connector REST API audio card to send an audio card with inline playback, autostart and autoloop properties. The content is served directly from your own service.

Property Type Description
title Rich text Title text
subtitle Rich text Subtitle text
image.url URL Optional thumbnail image 360x202, 202x360 (JPEG).
image.alt String Image text used by screenreaders
media[] Array List of media objects each with a single profile.
media.url URL (must be HTTPS) URL to media source.
media.profile string Name of presentation profile (audio).
aspect string Aspect ratio of thumbnail. Allowed values are 16:9 or 9:16.
autoloop Boolean Automatically loop media when set to true.
buttons Array of action objects Set of button actions applicable to the current card. Maximum 3 buttons.

Example JSON

{
  "type": "message/card",
  "attachments": [
     {
      "contentType": "application/vnd.microsoft.card.audio",
      "content": {
        "title": "Audio card",
        "subtitle": "About this card",
        "autoloop": true,
        "image": { "url": "https://img.youtube.com/vi/FyKYBei9D08/default.jpg" },
        "media": [
          {
            "profile": "audio",
            "url": "https://ia802608.us.archive.org/10/items/SmallPercussion/small%20percussion.mp3"
          }
        ]
      }
    }
  ]
}

Animated GIF card

Use the Bot Connector REST API animation card to send animated GIFs.

Property Type Description
title Rich text Title text
subtitle Rich text Subtitle text
image.url URL Mandatory thumbnail image 360x202, 202x360 (JPEG).
image.alt String Image text used by screenreaders
media[] Array List of media objects each with a single profile.
media.url URL (must be HTTPS) URL to media source.
media.profile string Name of presentation profile (animation).
aspect string Aspect ratio of thumbnail. Allowed values are 16:9 or 9:16.
autoloop Boolean Automatically loop media when set to true.
buttons Array of action objects Set of button actions applicable to the current card. Maximum 3 buttons.

The carousel card can be used to show a carousel of cards, with associated action buttons.

Carousel card

Each card attachment in a carousel can be a hero, thumbnail, video, audio or animated GIF card.

Sign in

Sign in card

The sign in card can be used to initiate an authentication flow with predefined images and title.

Property Type Description
text Rich text Text appears just below the subtitle. 2 lines maximum
buttons:[] Array of action objects Single button of type signin

Receipt

The receipt card can be used to send a receipt.

Receipt card

Property Type Description
title Rich text Title of the card.
subtitle Rich text Appears below title.
text Rich text Appears below substitle.
facts:[] Array of Fact key-value pairs Fact key is left aligned, value is right aligned
items:[] Array of Purchased objects Properties: title (Maximum 2 lines), subtitle (1 line), text (Up to 6 lines depending if title, subtitle and price are present), price, image (1:1 aspect ratio), tap
total Rich text Total purchase amount, mandatory for receipt card.
tax Rich text Amount of tax charged.
vat Rich text Amount of vat charged.
buttons:[] Array of action objects Set of actions applicable to the current card
tap Action object This action will be activated when the user taps on the card itself

Groups

A bot can be enabled for groups in the Skype settings for the bot. It can be added to a group chat in the same way as adding a participant to a chat. In a group the bot will only receive messages directly addressed to it e.g. “@YourBot This is the message”. It will not receive other messages sent by group participants or notifications of users joining or leaving the group.

At mention

To enable a bot to be added to a group chat you need to add this capability in Settings. Go to your Bot Dashboard and Edit the Skype channel.

Add groups

Calling

You can build Skype bots that can receive and handle voice calls using the .NET SDK, Node.js SDK or Skype API.

Each time a Skype user places a call to your bot, the Skype bot platform will notify the bot using the calling webhook you specify in settings. In response the bot can provide a set of basic actions called a workflow.

Supported actions:

  • Answer
  • Play prompt
  • Record audio
  • Speech to text
  • DTMF tones
  • Hang up

The Skype bot platform will execute the actions on the bot’s behalf according to the workflow.

If the workflow is successful, Skype will post a result of the last action to your calling webhook. For example, if the last action was to record an audio message the result will be audio content.

During a voice call your bot can decide after each result on how to continue interaction with the Skype user.

Note: Bots can handle 1:1 calls, but not group calls

Bing Entity and Intent Detection (Preview)

You can choose to have entities and intents automatically detected and sent along with the message text to your bot. A single intent and several entities may be returned.

{
  "text": "What's the weather like in Prague today?",
  "id": "8995507496412",
  "entities": [
    {
      "type": "intent/bing.dialog.api",
      "data": {
        "domain": "prebuilt",
        "intent": "microsoft.weather.check_weather",
        "confidence": 0.00755978003144264,
        "entities": [
          {
            "name": "microsoft.generic.absolute_location",
            "value": "Prague",
            "source": "Prague"
          },
          {
            "name": "microsoft.generic.date_range",
            "value": "today",
            "source": "today"
          }
        ]
      }
    }
  ],
  "type": "message/text",
  "timestamp": "2016-06-17T22:55:06.656Z",
  "channelId": "skype",
  "serviceUrl": "https://df-apis.skype.com",
  "from": {
    "id": "29:2hJJkjmGn4ljB2X7YYEju-sgFwgvnISvE6G3abGde8ts",
    "name": "Display Name"
  },
  "conversation": {
    "id": "29:2hJJkjmGn4ljB2X7YYEju-sgFwgvnISvE6G3abGde8ts"
  },
  "recipient": {
    "id": "28:29415286-5a43-4a00-9dc5-bcbc2ce1f59e",
    "name": "Trivia Master"
  },
}

To turn on Bing Entity and Intent Detection go to the Skype settings page for your bot.

Turn on Bing Entity and Intent Detection

Bot settings

Disabling a bot

To stop your bot receiving messages and remove it from directories go to your Bot Dashboard and Edit the Skype channel. Disable the bot in settings.

Disable bot

Deleting a bot

To delete your bot completely go to your Bot Dashboard and Edit the Skype channel. Select the Delect button at the bottom.