Notifications in Calling

Refer to Registering a Calling Bot on how to register the callback URL. This callback is used for all incoming calls to the application.

Protocol determination

The incoming notification is provided in legacy format for compatibility with the previous protocol. In order to convert the call to the Microsoft Graph protocol, the bot must determine the notification is in legacy format and reply with:

HTTP/1.1 204 No Content

The application will again receive the notification but this time it will be in the Microsoft Graph protocol.

You may configure the protocol your application supports and avoid receiving the initial callback in legacy format. The setting is available as a configuration option in the Skype Channel.

Redirects for region affinity

We will invoke your callback from the data-center hosting the call. The call may start in any data-center and does not take into account region affinities. The notification will be sent to your deployment depending on the GeoDNS resolution. If your application determines, by inspecting the initial notification payload or otherwise, that it needs to run in a different deployment, the application may reply with:

HTTP/1.1 302 Found
Location: your-new-location

You may decide to pickup the call and answer. You can specify the callback URL to handle this particular call. This is useful for stateful instances where your call is handled by a particular partition and you want to embed this information on the callback URL for routing to the right instance.

Authenticating the callback

Application should inspect the token passed by on the notification to validate the request. Whenever the API raises a web hook event, the API gets an OAUTH token from us, with audience as the application's App ID and adds it in the Authorization header as a Bearer token.

The application is expected to validate this token before accepting the callback request.

POST https://bot.contoso.com/api/calls
Content-Type: application/json
Authentication: Bearer <TOKEN>

"value": [
    "subscriptionId": "2887CEE8344B47C291F1AF628599A93C",
    "subscriptionExpirationDateTime": "2016-11-20T18:23:45.9356913Z",
    "changeType": "updated",
    "resource": "/app/calls/8A934F51F25B4EE19613D4049491857B",
    "resourceData": {
        "@odata.type": "#microsoft.graph.call",
        "state": "Established"
    }
]

The OAUTH token would have values like the following, and will be signed by us. The openid configuration published at https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration can be used to verify the token.

{
    "aud": "0efc74f7-41c3-47a4-8775-7259bfef4241",
    "iss": "https://api.botframework.com",
    "iat": 1466741440,
    "nbf": 1466741440,
    "exp": 1466745340,
    "tid": "1fdd12d0-4620-44ed-baec-459b611f84b2"
}

• aud audience is the App ID URI specified for the application.
• tid is the tenant id for contoso
• iss is the token issuer, https://api.botframework.com

The listener interface on the web hook URL can validate the token, ensure it has not expired, checking whether it has been signed by our published openid configuration. You must also check whether audience matches your App ID before accepting the callback request.

Sample shows how to validate inbound requests.

Additional information

You can read more about AAD tokens and Validation