Notificações de chamadas recebidasIncoming call notifications

Ao registrar um bot de chamadas e reuniões para o Microsoft Teams,o Webhook para a URL de chamada é mencionado.In registering a calls and meetings bot for Microsoft Teams, the Webhook for calling URL is mentioned. Essa URL é o ponto de extremidade do webhook para todas as chamadas de entrada para seu bot.This URL is the webhook endpoint for all incoming calls to your bot.

Determinação do protocoloProtocol determination

A notificação de entrada é fornecida em um formato herdado para compatibilidade com o protocolo anterior do Skype.The incoming notification is provided in a legacy format for compatibility with the previous Skype protocol. Para converter a chamada no protocolo Microsoft Graph, o bot deve determinar se a notificação está em um formato herdado e fornecer a seguinte resposta:In order to convert the call to the Microsoft Graph protocol, your bot must determine whether the notification is in a legacy format and provide the following response:

HTTP/1.1 204 No Content

Seu bot recebe a notificação novamente, mas desta vez no protocolo do Microsoft Graph.Your bot receives the notification again, but this time in the Microsoft Graph protocol.

Em uma versão futura da Plataforma de Mídia em tempo real, você pode configurar o protocolo compatível com o aplicativo para evitar receber o retorno de chamada inicial no formato herddo.In a future release of the Real-time Media Platform, you can configure the protocol your application supports to avoid receiving the initial callback in the legacy format.

A próxima seção fornece detalhes sobre notificações de chamadas de entrada redirecionadas para afinidade de região para sua implantação.The next section provides details on incoming call notifications redirected for region affinity to your deployment.

Redirecionamentos para afinidade de regiãoRedirects for region affinity

Você chama seu webhook do data-center que hospeda a chamada.You call your webhook from the data-center hosting the call. A chamada começa em qualquer data center e não leva em conta as afinidades de região.The call starts in any data center and does not take into account region affinities. A notificação é enviada para sua implantação, dependendo da resolução GeoDNS.The notification is sent to your deployment depending on the GeoDNS resolution. Se o aplicativo determinar, inspecionando a carga de notificação inicial ou de outra forma, que ele precisa ser executado em uma implantação diferente, o aplicativo fornece a seguinte resposta:If your application determines, by inspecting the initial notification payload or otherwise, that it needs to run in a different deployment, the application provides the following response:

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

Habilita o bot a responder a uma chamada de entrada usando a API de resposta.Enable your bot to answer an incoming call using the answer API. Você pode especificar o callbackUri para manipular essa chamada específica.You can specify the callbackUri to handle this particular call. Isso é útil para instâncias de estado em que sua chamada é manipulada por uma partição específica e você deseja inserir essas informações no roteamento para callbackUri a instância certa.This is useful for stateful instances where your call is handled by a particular partition, and you want to embed this information in the callbackUri for routing to the right instance.

A próxima seção fornece detalhes sobre a autenticação do retorno de chamada inspecionando o token postado em seu webhook.The next section provides details on authenticating the callback by inspecting the token posted to your webhook.

Autenticar o retorno de chamadaAuthenticate the callback

Seu bot deve inspecionar o token postado no webhook para validar a solicitação.Your bot must inspect the token posted to your webhook to validate the request. Sempre que a API posta no webhook, a mensagem HTTP POST contém um token OAuth no cabeçalho Autorização como um token de portador, com a audiência como iD do aplicativo.Every time the API posts to the webhook, the HTTP POST message contains an OAuth token in the Authorization header as a bearer token, with the audience as your application's App ID.

Seu aplicativo deve validar esse token antes de aceitar a solicitação de retorno de chamada.Your application must validate this token before accepting the callback request.

O código de exemplo a seguir é usado para autenticar o retorno de chamada:The following sample code is used to authenticate the callback:

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"
    }
]

O token OAuth tem os seguintes valores e é assinado pelo Skype:The OAuth token has the following values, and is signed by Skype:

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

A configuração OpenID publicada https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration em pode ser usada para verificar o token.The OpenID configuration published at https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration can be used to verify the token. Cada valor de token OAuth é usado da seguinte forma:Each OAuth token value is used as follows:

  • aud onde audiência é o URI de ID do aplicativo especificado para o aplicativo.aud where audience is the App ID URI specified for the application.
  • tid é a ID do locatário para Contoso.com.tid is the tenant id for Contoso.com.
  • iss é o emissor de token, https://api.botframework.com .iss is the token issuer, https://api.botframework.com.

Para a manipulação de código, o webhook deve validar o token, garantir que ele não expirou e verificar se ele foi assinado pela configuração OpenID publicada.For your code handling, the webhook must validate the token, ensure it has not expired, and check whether it has been signed by the published OpenID configuration. Você também deve verificar se a aud corresponde à ID do aplicativo antes de aceitar a solicitação de retorno de chamada.You must also check whether aud matches your App ID before accepting the callback request.

Para obter mais informações, consulte validate inbound requests.For more information, see validate inbound requests.

Próxima etapaNext step