Perguntas frequentes sobre a API de registros de chamadas do Microsoft Graph

Este tópico fornece respostas para perguntas frequentes sobre a API de registros de chamadas no Microsoft Graph.

O que é a API de registros de chamadas do Microsoft Graph?

A API de registros de chamadas do Microsoft Graph oferece informações de uso e diagnóstico para chamadas e reuniões online que ocorrem em sua organização ao usar o Microsoft Teams ou o Skype for Business. As organizações, também chamadas de "locatários", podem usar a API de registros de chamadas para assinar, listar, recuperar registros de chamadas por IDs de chamadas e procurar chamadas para um participante. Para obter mais informações, consulte Trabalhando com a API de registros de chamadas no Microsoft Graph.

Qual permissão é necessária para usar a API de registros de chamada?

Seu aplicativo precisa da permissão CallRecords.Read.All para acessar registros de chamada no Microsoft Graph. Um administrador deve conceder essa permissão ao aplicativo. Para saber mais, confira Referência de permissões do Microsoft Graph.

Posso usar permissões delegadas com a API de registros de chamadas?

Não, a API de registros de chamadas não dá suporte a permissões delegadas.

Por que não posso usar permissões delegadas com a API de registros de chamada?

Você não pode usar permissões delegadas porque não há como limitar a permissão CallRecords.Read.All a chamadas ou usuários específicos. A permissão do aplicativo é concedida no nível da organização, não no nível do usuário individual.

Como fazer solicitar um registro de chamada usando a API de registros de chamada?

Para solicitar um registro de chamada, você precisa fazer uma GET solicitação ao /communications/callRecords/{id} endpoint, onde {id} está o identificador exclusivo da sua chamada. Verifique se você tem a permissão CallRecords.Read.All e inclua o cabeçalho Authorization com um token de portador válido. Para obter mais informações, consulte a documentação Obter callRecord.

Onde posso encontrar as IDs de chamada das chamadas que ocorreram na minha organização?

Você pode localizar e coletar IDs de chamadas das seguintes maneiras:

• Assinar notificações: assine para alterar o feed de notificações e receba notificações contendo IDs de chamada sempre que um novo registro de chamada for criado.
• Listar registros de chamadas: obtenha uma lista de IDs de chamada solicitando-a da API Listar callRecords.
• Pesquisa manual: se você tiver acesso à Análise de Chamadas no Centro de Administração do Microsoft Teams, poderá pesquisar manualmente por uma ID de chamada no histórico de um usuário. No entanto, nenhum sistema automatizado está disponível para recuperar todas as IDs de chamada da Análise de Chamada.
• Use callChainId:: procure a ID da chamada usando a callChainId API Obter chamada após a conclusão da chamada. Use essa abordagem quando a chamada for criada programaticamente e você estiver trabalhando com o tipo de recurso de chamada. Além disso, o callChainId pode ser diferente da ID do registro de chamada em determinados cenários, como chamadas de transferência, devido a especificidades de arquitetura. Portanto, use os outros métodos nesta lista quando possível.

Quando um registro de chamada está disponível?

Uma primeira versão de um registro de chamada é normalmente gerada e uma notificação é enviada dentro de 30 minutos após o término de uma chamada. No entanto, pode levar até 150 minutos para que o serviço disponibilize o registro de chamada. Para obter mais informações, consulte a página Latência .

Por quanto tempo os registros de chamadas são retidos?

Os registros de chamada são mantidos por 30 dias após o término da chamada.

Posso recuperar registros de chamadas com mais de 30 dias?

Não, a API de registros de chamadas não retorna registros de chamadas com mais de 30 dias. As solicitações para tais registros resultam em uma resposta de 404 Not Found erro.

Por que minha notificação de registro de primeira chamada está atrasada?

A notificação do registro de chamada pode ser atrasada porque pode levar até 150 minutos para que o serviço disponibilize a primeira versão de um registro de chamada. Se você experimentar um atraso maior para a entrega da versão do registro da primeira chamada, Marque se há interrupções relatadas pela equipe da API de registros de chamada na guia Integridade do portal de Administração do Teams. Além disso, você pode abrir um tíquete de suporte com a equipe da API de registros de chamadas.

Por que as versões subsequentes do meu registro de chamadas estão atrasadas?

As versões subsequentes de um registro de chamada podem ser entregues após a latência inicial de 150 minutos. Isso significa que, embora a primeira versão esteja disponível em 150 minutos, atualizações posteriores no registro de chamada podem chegar mais tarde devido à telemetria atrasada do cliente e a outros fatores.

Por que um registro de chamada tem campos ausentes?

Um registro de chamada pode ter campos ausentes devido à telemetria atrasada de um cliente. Quando novos dados de telemetria ficam disponíveis, o sistema gera um novo registro de chamada com informações atualizadas, incrementa o valor da version propriedade e envia o registro de chamada atualizado para você. Se o registro de chamada estiver com propriedades ausentes, aguarde a próxima versão do registro de chamada.

No entanto, é importante observar que alguns campos podem permanecer vazios por design ou porque a telemetria do cliente nunca chegou, como valores de fluxo de mídia.

Se campos críticos ou entregues anteriormente estiverem ausentes, abra um tíquete de suporte com a equipe de API de registros de chamadas.

Como faço para listar todos os participantes que participaram de uma chamada?

Você pode usar os seguintes métodos para listar todos os participantes da chamada:

1. API de participants_v2 de Lista

   Use a API List participants_v2 para coletar a lista completa de participantes para uma ID de chamada solicitada.

2. Use o parâmetro de consulta OData $expand no objeto callRecords para expandir a propriedade participants_v2

   Você pode ligar GET communications/callRecords/{id}?$expand=participants_v2 para recuperar detalhes de chamadas de alto nível junto com a lista de participantes.

3. Criar uma lista de participantes personalizada

   Para ver todos os participantes, implemente uma solução personalizada para criar a lista de participantes a partir dos dados dos registros de chamadas:

   1. Chame a API Get callRecord e expanda a sessions propriedade: GET /communications/callRecords/{id}?$expand=sessions.
   2. Para chamadas ponto a ponto (P2P), leia as caller propriedades and callee de cada uma session na lista recebida sessions . Para chamadas de reunião, leia somente a caller propriedade.
   3. Crie sua lista de participantes personalizada com base na identidade do caller ponto de extremidade. Para chamadas P2P, inclua também a identidade do callee ponto de extremidade. Colete o id, displayNamee outras propriedades necessárias para cada participante.

Por que não vejo todos os participantes que participaram de uma chamada durante a lista de chamadas participants_v2 API?

Talvez você não veja todos os participantes porque a API List participants_v2 dá suporte à paginação, limitando o número de participantes na resposta a 130 por página. Se houver mais de 130 usuários na chamada, a primeira resposta do registro de chamada conterá 130 participantes junto com uma @odata.nextLink propriedade. Essa propriedade inclui a URL para chamar a API e receber o próximo conjunto de participantes. Continue esse processo até que o próximo link esteja vazio, o que indica que não há mais participantes a serem recuperados.

Por que há sessões duplicadas retornadas para um registro de chamada?

Uma sessão de registro de chamada representa exclusivamente uma única comunicação usuário-usuário em chamadas ponto a ponto ou uma única comunicação de serviço do usuário em uma chamada ou reunião em grupo. No entanto, em alguns cenários de chamada, uma única comunicação usuário-serviço pode envolver várias identidades de serviço em uma única sessão, como uma transferência virtual entre um atendedor automático e uma fila de chamadas. Nesses cenários, uma ID de sessão pode ser duplicada uma ou mais vezes para representar adequadamente cada identidade envolvida na comunicação e a respectiva duração da comunicação.

Por que recebo um erro 404 Não Encontrado?

Veja a seguir alguns motivos pelos quais você pode encontrar um 404 Not Found erro:

• Chamada recente: se a chamada foi feita nos últimos 150 minutos, o registro de chamada pode ainda não ter sido gerado. Aguarde 150 minutos após o término da chamada e tente novamente.
• Chamada antiga: se a chamada tiver mais de 30 dias, a API de registros de chamada retornará um 404 Not Found erro por design.
• Outros problemas: se nenhum dos motivos se aplicar, Marque se há interrupções relatadas pela equipe da API de registros de chamadas na guia Integridade do portal de Administração do Teams. Além disso, você pode abrir um tíquete de suporte com a equipe da API de registros de chamadas para obter assistência.