Notificações de chamadas recebidas

  • Artigo

Ao registrar um bot de chamadas e reuniões para o Microsoft Teams, o Webhook para a URL de chamada é mencionado. Essa URL é o ponto de extremidade do webhook para todas as chamadas de entrada para o seu bot.

Determinação de protocolo

A notificação de entrada é fornecida em um formato herdado para compatibilidade com o protocolo Skypeanterior. Para converter a chamada no protocolo do Microsoft Graph, o bot deve determinar se a notificação está em um formato herdado e fornece a seguinte resposta:

HTTP/1.1 204 No Content

Seu bot recebe a notificação novamente, mas desta vez no Microsoft Graph protocolo.

Em uma versão futura da Plataforma de Mídia em Tempo Real, você pode configurar o protocolo compatível com seu aplicativo para evitar o recebimento do retorno de chamada inicial no formato herdado.

A próxima seção fornece detalhes sobre as notificações de chamada de entrada redirecionadas para afinidade de região para sua implantação.

Redirecionamentos para afinidade de região

Você chama o webhook do data center que hospeda a chamada. A chamada começa em qualquer data center e não leva em conta afinidades de região. A notificação é enviada para sua implantação, dependendo da resolução do GeoDNS. 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 fornecerá a seguinte resposta:

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

Habilite o bot para responder a uma chamada de entrada usando a API de resposta. Você pode especificar o callbackUri para manipular essa chamada específica. Isso é útil para instâncias com estado em que sua chamada é tratada por uma partição específica e você deseja inserir essas informações no callbackUri para roteamento para a instância certa.

A próxima seção fornece detalhes sobre como autenticar o retorno de chamada inspecionando o token postado no webhook.

Autenticar o retorno de chamada

Seu bot deve inspecionar o token postado no webhook para validar a solicitação. Sempre que a API posta no webhook, a mensagem HTTP POST contém um token OAuth no cabeçalho de Autorização como um token de portador, com a audiência como a ID do aplicativo.

Seu aplicativo deve validar esse token antes de aceitar a solicitação de retorno de chamada.

O código de exemplo a seguir é usado para autenticar o retorno de chamada:

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:

{
    "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 em https://api.aps.skype.com/v1/.well-known/OpenIdConfiguration pode ser usada para verificar o token. Cada valor de token OAuth é usado da seguinte maneira:

  • aud em que audiência é o URI da ID do Aplicativo especificado para o aplicativo.
  • tid é a ID do locatário Contoso.com.
  • iss é o emissor do token, https://api.botframework.com.

Para o tratamento de código, o webhook deve validar o token, garantir que ele não expirou e marcar se ele foi assinado pela configuração OpenID publicada. Você também deve verificar se a aud corresponde à ID do aplicativo antes de aceitar a solicitação de retorno de chamada.

Para obter mais informações, consulte validar solicitações de entrada.

Próxima etapa

Requisitos e considerações para bots de mídia hospedados pelo aplicativo

Confira também