As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Noções básicas sobre as notificações do SDK do Amazon Chime
A análise de voz envia eventos automaticamente para um alvo quando as tarefas de pesquisa de locutores ou análise do tom de voz começam, enquanto são executadas e quando terminam. Use destinos de notificação para receber esses eventos. Recomendamos usar vários destinos de notificação se seu fluxo de trabalho ou aplicativo precisar de alta disponibilidade.
Além disso, você deve usar um perfil do IAM com as políticas necessárias para acessar os destinos de notificação. Para obter mais informações, consulte [Usar o perfil de acesso ao recurso de analytics de chamadas do SDK do Amazon Chime](call-analytics-resource-access-role.md).
**nota**
Para o Amazon SQS e o Amazon SNS, não oferecemos suporte a filas. first-in-first-out Como resultado, as mensagens podem chegar fora de ordem. Recomendamos verificar os carimbos de data/hora para ordenar as mensagens conforme necessário e manter as mensagens em um armazenamento de dados como o Amazon DynamoDB. Você também pode usar a APIs descrição em [Pesquisar resultados de tarefas do SDK do Amazon Chime](va-task-result-poll.md) para receber os resultados mais recentes.
A tabela a seguir lista os eventos e seus tipos de detalhes correspondentes.
| Evento de notificação | Tipo de detalhe |
| --- | --- |
| Metadados de análise de voz | `VoiceAnalyticsStatus` |
| Pesquisa de locutor | `SpeakerSearchStatus` |
| Análise de tom de voz | `VoiceToneAnalysisStatus` |
# Noções básicas sobre as políticas do IAM para destinos de notificação do SDK do Amazon Chime
Você deve usar políticas no perfil do IAM em uma configuração do Call Analytics que permita acesso aos seus destinos de notificação do Amazon SQS, Amazon SNS, AWS Lambda ou Amazon KDS. Para obter mais informações, consulte [Usar o perfil de acesso ao recurso de analytics de chamadas do SDK do Amazon Chime](call-analytics-resource-access-role.md) neste guia.
## Eventos de pesquisa de locutor
Os eventos de pesquisa de locutor têm o tipo de detalhe `SpeakerSearchStatus`.
Os conectores de voz do SDK do Amazon Chime enviam os seguintes eventos de pesquisa de locutor:
+ Identificação corresponde
+ Geração de incorporação de voz
Os eventos podem ter os seguintes status:
+ `IdentificationSuccessful`: identificou com sucesso pelo menos um ID de perfil de voz correspondente com uma alta pontuação de confiança em determinado domínio de perfil de voz.
+ `IdentificationFailure`: falha ao realizar a identificação. Causas: o chamador não fala por pelo menos 10 segundos, baixa qualidade de áudio.
+ `IdentificationNoMatchesFound`: não foi possível encontrar uma correspondência de alta confiança no domínio do perfil de voz fornecido. O chamador pode ser novo ou sua voz pode ter mudado.
+ `VoiceprintGenerationSuccessful`: o sistema gerou uma incorporação de voz usando 20 segundos de áudio não silencioso.
+ `VoiceprintGenerationFailure`: o sistema falhou ao gerar uma incorporação de voz. Causas: o chamador não fala por pelo menos 20 segundos, baixa qualidade de áudio.
### Identificação corresponde
Depois que a API [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) é chamada para um `transactionId` específico, o serviço Voice Connector exibe uma notificação de correspondência de identificação após dez segundos de fala não silenciosa. O serviço retorna as 10 melhores correspondências, junto com um ID de perfil de voz e uma pontuação de confiança que varia de [0, 1]. Quanto maior a pontuação de confiança, maior a probabilidade de o locutor da chamada corresponder ao ID do perfil de voz. Se o modelo de machine learning não encontrar correspondências, o campo `detailStatus` da notificação conterá `IdentificationNoMatchesFound`.
O exemplo a seguir mostra a notificação de uma correspondência bem-sucedida.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "uuid",
"detailStatus": "IdentificationSuccessful",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
"confidenceScore": "0.94567856",
},
{
"voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
"confidenceScore": "0.82783350",
},
{
"voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
"confidenceScore": "0.77136436",
}
]
},
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
### Geração de incorporação de voz
Depois de mais 10 segundos de fala não silenciosa, o Voice Connector envia uma notificação de geração de incorporação de voz para os destinos de notificação. Você pode inscrever novas incorporações de voz em um perfil de voz ou atualizar uma impressão que já está em um perfil de voz.
O exemplo a seguir mostra a notificação de uma correspondência bem-sucedida, o que significa que você pode atualizar o perfil de voz associado.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "guid",
"detailStatus": "VoiceprintGenerationSuccess",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
## Eventos de análise do tom de voz
Os eventos de análise do tom de voz têm o tipo de detalhe `VoiceToneAnalysisStatus`. As análises podem retornar esses status:
+ `VoiceToneAnalysisSuccessful`: analisou com sucesso as vozes do chamador e do atendente em probabilidades de sentimento: positivo, negativo ou neutro.
+ `VoiceToneAnalysisFailure`: falha ao realizar a análise do tom. Isso pode acontecer se o chamador ficar sem falar por 10 segundos ou se a qualidade do áudio ficar muito ruim.
+ `VoiceToneAnalysisCompleted`: analisou com sucesso as vozes do usuário e do atendente quanto às probabilidades de sentimento durante toda a chamada. Esse é o evento final, enviado quando a análise do tom de voz é concluída.
O exemplo abaixo mostra um evento típico de análise do tom de voz.
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "216539279014",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"detail": {
"taskId": "uuid",
"detailStatus": "VoiceToneAnalysisSuccessful",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "2022-08-26T17:55:15.563Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "neutral",
"voiceToneScore": {
"neutral": "0.83",
"positive": "0.13",
"negative": "0.04"
}
},
"overallAverageVoiceTone": {
"startTime": "2022-08-26T16:23:13.344Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "positive",
"voiceToneScore": {
"neutral": "0.25",
"positive": "0.65",
"negative": "0.1"
}
}
},
"startFragmentNumber": "01234567890123456789",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
},
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}
```
## Eventos resumidos após a chamada
Os eventos de resumo pós-chamada são enviados 5 minutos após o término da chamada. Esses resumos fornecem uma visão geral das tarefas de pesquisa de locutor que ocorreram durante a chamada.
O exemplo a seguir mostra um resumo pós-chamada com a melhor correspondência de perfil de voz, identidade confirmada do locutor e uma lista dos perfis de voz criados ou atualizados por meio das chamadas de API `CreateVoiceProfile` e `UpdateVoiceProfile` feitas durante a chamada.
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "VoiceAnalyticsStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "PostCallVoiceAnalytics",
"callId": "22e8dee8-bbd7-4f94-927b-2d0ebaeddc1c",
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "abcdef1ghij2klmno3pqr4",
"isCaller": true | false,
"speakerSearchResults": {
"bestMatchedVoiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"customerValidatedCallerIdentity": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"createVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z"
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
],
"updateVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
]
}
}
}
```
# Exemplo de analytics de voz: função do Lambda para o SDK do Amazon Chime
O código Python no exemplo a seguir processa as notificações recebidas de um Voice Connector. Você pode adicionar o código a uma função AWS Lambda. Você também pode usar para acionar sua fila do Amazon SQS, tópico do Amazon SNS ou Amazon Kinesis Data Stream. Em seguida, você pode armazenar as notificações em um arquivo `EventTable` para processamento futuro. Para obter os formatos exatos de notificação, consulte [Noções básicas sobre as notificações do SDK do Amazon Chime](va-notification-targets.md).
```
import base64
import boto3
import json
import logging
import time
from datetime import datetime
from enum import Enum
log = logging.getLogger()
log.setLevel(logging.INFO)
dynamo = boto3.client("dynamodb")
EVENT_TABLE_NAME = "EventTable"
class EventType(Enum):
"""
This example code uses a single Lambda processor to handle either
triggers from SQS, SNS, Lambda, or Kinesis. You can adapt it to fit your
desired infrastructure depending on what you prefer. To distinguish
where we get events from, we use an EventType enum as an
example to show the different ways of parsing the notifications.
"""
SQS = "SQS"
SNS = "SNS"
LAMBDA = "LAMBDA"
KINESIS = "KINESIS"
class AnalyticsType(Enum):
"""
Define the various analytics event types that this Lambda will
handle.
"""
SPEAKER_SEARCH = "SpeakerSearch"
VOICE_TONE_ANALYSIS = "VoiceToneAnalysis"
ANALYTICS_READY = "AnalyticsReady"
UNKNOWN = "UNKNOWN"
class DetailType(Enum):
"""
Define the various detail types that Voice Connector's voice
analytics feature can return.
"""
SPEAKER_SEARCH_TYPE = "SpeakerSearchStatus"
VOICE_TONE_ANALYSIS_TYPE = "VoiceToneAnalysisStatus"
ANALYTICS_READY = "VoiceAnalyticsStatus"
def handle(event, context):
"""
Example of how to handle incoming Voice Analytics notification messages
from Voice Connector.
"""
logging.info(f"Received event of type {type(event)} with payload {event}")
is_lambda = True
# Handle triggers from SQS, SNS, and KDS. Use the below code if you would like
# to use this Lambda as a trigger for an existing SQS queue, SNS topic or Kinesis
# stream.
if "Records" in event:
logging.info("Handling event from SQS or SNS since Records exists")
is_lambda = False
for record in event.get("Records", []):
_process_record(record)
# If you would prefer to have your Lambda invoked directly, use the
# below code to have the Voice Connector directly invoke your Lambda.
# In this scenario, there are no "Records" passed.
if is_lambda:
logging.info(f"Handling event from Lambda")
event_type = EventType.LAMBDA
_process_notification_event(event_type, event)
def _process_record(record):
# SQS and Kinesis use eventSource.
event_source = record.get("eventSource")
# SNS uses EventSource.
if not event_source:
event_source = record.get("EventSource")
# Assign the event type explicitly based on the event source value.
event_type = None
if event_source == "aws:sqs":
event = record["body"]
event_type = EventType.SQS
elif event_source == "aws:sns":
event = record["Sns"]["Message"]
event_type = EventType.SNS
elif event_source == "aws:kinesis":
raw_data = record["kinesis"]["data"]
raw_message = base64.b64decode(raw_data).decode('utf-8')
event = json.loads(raw_message)
event_type = EventType.KINESIS
else:
raise Exception(f"Event source {event_source} is not supported")
_process_notification_event(event_type, event)
def _process_notification_event(
event_type: EventType,
event: dict
):
"""
Extract the attributes from the Voice Analytics notification message
and store it as a DynamoDB item to process later.
"""
message_id = event.get("id")
analytics_type = _get_analytics_type(event.get("detail-type"))
pk = None
if analytics_type == AnalyticsType.ANALYTICS_READY.value or analytics_type == AnalyticsType.UNKNOWN.value:
transaction_id = event.get("detail").get("transactionId")
pk = f"transactionId#{transaction_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
else:
task_id = event.get("detail").get("taskId")
pk = f"taskId#{task_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
logging.info(f"Generated PK {pk}")
_create_request_record(pk, message_id, json.dumps(event))
def _create_request_record(pk: str, sk: str, body: str):
"""
Record this notification message into the Dynamo db table
"""
try:
# Use consistent ISO8601 date format.
# 2019-08-01T23:09:35.369156 -> 2019-08-01T23:09:35.369Z
time_now = (
datetime.utcnow().isoformat()[:-3] + "Z"
)
response = dynamo.put_item(
Item={
"PK": {"S": pk},
"SK": {"S": sk},
"body": {"S": body},
"createdOn": {"S": time_now},
},
TableName=EVENT_TABLE_NAME,
)
logging.info(f"Added record in table {EVENT_TABLE_NAME}, response : {response}")
except Exception as e:
logging.error(f"Error in adding record: {e}")
def _get_analytics_type(detail_type: str):
"""
Get analytics type based on message detail type value.
"""
if detail_type == DetailType.SPEAKER_SEARCH_TYPE.value:
return AnalyticsType.SPEAKER_SEARCH.value
elif detail_type == DetailType.VOICE_TONE_ANALYSIS_TYPE.value:
return AnalyticsType.VOICE_TONE_ANALYSIS.value
elif detail_type == DetailType.ANALYTICS_READY.value:
return AnalyticsType.ANALYTICS_READY.value
else:
return AnalyticsType.UNKNOWN.value
```
**Importante**
Você deve receber o consentimento antes de ligar para o [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask)ou [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) APIs. Recomendamos que você mantenha os eventos em uma área de espera, como o Amazon DynamoDB, até receber o consentimento.