Pré-requisitos Considerações sobre custos Pesquise e forneça números de telefone Crie uma função Lambda para tratamento de chamadas Crie um aplicativo de mídia SIP Configurar o roteamento de chamadas com regras SIP Configure a redundância com vários aplicativos de mídia SIP Crie chamadas externas Acione o Lambda durante uma chamada ativa Limpar recursos Indo para a produção Próximas etapas

Roteamento de chamadas para AWS Lambda funções para áudio PSTN do SDK do Amazon Chime ()AWS CLI

Este tutorial orienta você pelo processo de configuração do roteamento de chamadas para funções Lambda usando o serviço de áudio PSTN do Amazon Chime SDK. Você aprenderá a criar funções Lambda, configurar aplicativos de mídia SIP e configurar regras SIP para lidar com chamadas recebidas.

Pré-requisitos

Antes de começar este tutorial, faça o seguinte:

Instale AWS CLI o. Para obter mais informações, consulte Instalar ou atualizar para a versão mais recente da AWS CLI no Guia do usuário do AWS CLI .
Configure seu AWS CLI com as credenciais apropriadas. Execute aws configure se você ainda não configurou suas credenciais.
Tenha familiaridade básica com AWS Lambda os conceitos do Amazon Chime SDK.
Configure permissões suficientes para criar e gerenciar recursos do Amazon Chime SDK e Lambda em sua conta da AWS.
Para o roteamento baseado em números de telefone, você precisa ter um número de telefone em seu inventário de números de telefone do Amazon Chime SDK.
Para o roteamento baseado no Voice Connector, você precisa ter um conector de voz configurado em sua conta.

Considerações sobre custos

O tutorial inclui instruções de limpeza para garantir que você não incorra em cobranças contínuas após a conclusão. Para obter mais informações, consulte os preços do Amazon Chime SDK.

Vamos começar a configurar o roteamento de chamadas para o áudio PSTN do SDK do Amazon Chime.

Pesquise e forneça números de telefone

Antes de criar regras SIP com acionadores de números de telefone, você precisa ter números de telefone em seu inventário do Amazon Chime SDK. Veja como pesquisar os números de telefone disponíveis e provisioná-los.

exemplo : Pesquise os números de telefone disponíveis



# Search for available toll-free phone numbers
aws chime-sdk-voice search-available-phone-numbers \
  --phone-number-type TollFree \
  --country US \
  --toll-free-prefix 844 \
  --max-results 5 \
  --region us-east-1

Esse comando procura os números de telefone gratuitos disponíveis com o prefixo 844 nos EUA. Você pode modificar os parâmetros para pesquisar diferentes tipos de números.

exemplo : Provisionar um número de telefone

Depois de encontrar um número de telefone disponível, você pode provisioná-lo usando o seguinte comando:



# Order a phone number
aws chime-sdk-voice create-phone-number-order \
  --product-type SipMediaApplicationDialIn \
  --e164-phone-numbers "+18445550100" \
  --region us-east-1

+18445550100Substitua por um número de telefone real disponível nos resultados da pesquisa. Esse comando provisionará o número de telefone para sua conta.

exemplo : Verifique o status do número de telefone

Depois de solicitar um número de telefone, você pode verificar seu status:



# Get the phone number order status
aws chime-sdk-voice get-phone-number-order \
  --phone-number-order-id abcd1234-5678-90ab-cdef-EXAMPLE55555 \
  --region us-east-1

Substitua o ID do pedido pelo retornado pelo create-phone-number-order comando.

exemplo : Liste números de telefone em seu inventário

Para ver todos os números de telefone em seu inventário:



# List all phone numbers
aws chime-sdk-voice list-phone-numbers \
  --region us-east-1

Para encontrar números de telefone não atribuídos que possam ser usados para regras SIP:



# List unassigned phone numbers
aws chime-sdk-voice list-phone-numbers \
  --region us-east-1 \
  --query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber"

Crie uma função Lambda para tratamento de chamadas

Agora, vamos criar uma função Lambda que manipulará as chamadas recebidas. A função receberá eventos do serviço de áudio PSTN e responderá com instruções sobre como lidar com a chamada.

exemplo : Crie uma função do IAM para o Lambda

Antes de criar a função Lambda, você precisa criar uma função do IAM que conceda as permissões necessárias.



cat > lambda-trust-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "lambda.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF



aws iam create-role --role-name ChimeSDKLambdaRole \
  --assume-role-policy-document file://lambda-trust-policy.json



aws iam attach-role-policy --role-name ChimeSDKLambdaRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Esses comandos criam uma função do IAM que permite ao Lambda assumi-la e anexar a política de execução básica, que fornece permissões para o Lambda gravar registros. CloudWatch

exemplo Crie uma função do Lambda:

Agora, crie uma função Lambda simples que manipulará as chamadas recebidas.



mkdir -p lambda
cat > lambda/index.js << EOF
exports.handler = async (event) => {
  console.log('Received event:', JSON.stringify(event, null, 2));
  
  // Simple call handling logic
  const response = {
    SchemaVersion: '1.0',
    Actions: [
      {
        Type: 'Speak',
        Parameters: {
          Engine: 'neural',
          Text: 'Hello! This is a test call from Amazon Chime SDK PSTN Audio.',
          VoiceId: 'Joanna'
        }
      },
      {
        Type: 'Hangup',
        Parameters: {
          SipResponseCode: '200'
        }
      }
    ]
  };
  
  return response;
};
EOF



cd lambda
zip -r function.zip index.js
cd ..



# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws lambda create-function \
  --function-name ChimeSDKCallHandler \
  --runtime nodejs18.x \
  --role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
  --handler index.handler \
  --zip-file fileb://lambda/function.zip

Essa função Lambda responde às chamadas recebidas com uma mensagem falada e depois desliga.

exemplo : Adicione a permissão Lambda para o Amazon Chime SDK

Conceda permissão ao serviço Amazon Chime SDK para invocar sua função Lambda.



# Get your AWS account ID
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws lambda add-permission \
  --function-name ChimeSDKCallHandler \
  --statement-id ChimeSDK \
  --action lambda:InvokeFunction \
  --principal voiceconnector.chime.amazonaws.com \
  --source-account ${ACCOUNT_ID}

Esse comando permite que o serviço Amazon Chime SDK Voice Connector invoque sua função Lambda.

Crie um aplicativo de mídia SIP

Os aplicativos de mídia SIP conectam sua função Lambda ao serviço de áudio PSTN. Nesta seção, você criará um aplicativo de mídia SIP que usa sua função Lambda.

exemplo : Crie o aplicativo de mídia SIP



# Get your Lambda function ARN
LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKCallHandler --query Configuration.FunctionArn --output text)

aws chime-sdk-voice create-sip-media-application \
  --aws-region us-east-1 \
  --name "MyCallHandlerApp" \
  --endpoints "[{\"LambdaArn\":\"${LAMBDA_ARN}\"}]"

O aplicativo de mídia SIP atua como uma ponte entre o serviço de áudio PSTN e sua função Lambda.

exemplo : Obtenha o ID do aplicativo de mídia SIP

Depois de criar o aplicativo de mídia SIP, você precisa recuperar seu ID para uso posterior no tutorial.



SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
  --output text)

echo "SIP Media Application ID: ${SIP_MEDIA_APP_ID}"

Anote o ID do aplicativo de mídia SIP retornado por esse comando, pois você precisará dele ao criar regras SIP.

Configurar o roteamento de chamadas com regras SIP

As regras SIP determinam como as chamadas recebidas são roteadas para seus aplicativos de mídia SIP. Você pode criar regras com base em números de telefone ou nomes de host do Voice Connector.

exemplo : Crie uma regra SIP com gatilho de número de telefone

Para rotear chamadas com base em um número de telefone, use o seguinte comando:



# Get an unassigned phone number from your inventory
PHONE_NUMBER=$(aws chime-sdk-voice list-phone-numbers \
  --query "PhoneNumbers[?Status=='Unassigned'].E164PhoneNumber | [0]" \
  --output text)

# If no unassigned phone number is found, you'll need to provision one
if [ -z "$PHONE_NUMBER" ] || [ "$PHONE_NUMBER" == "None" ]; then
  echo "No unassigned phone numbers found. Please provision a phone number first."
  exit 1
fi

echo "Using phone number: ${PHONE_NUMBER}"

aws chime-sdk-voice create-sip-rule \
  --name "IncomingCallRule" \
  --trigger-type ToPhoneNumber \
  --trigger-value "${PHONE_NUMBER}" \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"

Esse comando cria uma regra SIP que encaminha as chamadas para o seu número de telefone para o aplicativo de mídia SIP.

exemplo : Crie uma regra SIP com o gatilho Request URI hostname

Como alternativa, você pode rotear chamadas com base no URI de solicitação de uma chamada SIP recebida do Voice Connector:



# Replace with your Voice Connector hostname
VOICE_CONNECTOR_HOST="example.voiceconnector.chime.aws"

aws chime-sdk-voice create-sip-rule \
  --name "VoiceConnectorRule" \
  --trigger-type RequestUriHostname \
  --trigger-value "${VOICE_CONNECTOR_HOST}" \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1}]"

Substitua o nome do host pelo nome do host de saída do Voice Connector.

Configure a redundância com vários aplicativos de mídia SIP

Para redundância e failover, você pode criar vários aplicativos de mídia SIP na mesma região da AWS e especificar sua ordem de prioridade.

exemplo : Crie uma função Lambda de backup

Primeiro, crie uma função Lambda de backup na mesma região.


cat > lambda/backup-index.js >< EOF
exports.handler = async (event) => {
  console.log('Received event in backup handler:', JSON.stringify(event, null, 2));

  // Simple call handling logic for backup
  const response = {
    SchemaVersion: '1.0',
    Actions: [
      {
        Type: 'Speak',
        Parameters: {
          Engine: 'neural',
          Text: 'Hello! This is the backup handler for Amazon Chime SDK PSTN Audio.',
          VoiceId: 'Matthew'
        }
      },
      {
        Type: 'Hangup',
        Parameters: {
          SipResponseCode: '200'
        }
      }
    ]
  };

  return response;
};
EOF



                    cd lambda
                    zip -r backup-function.zip backup-index.js
                    cd ..



                    # Get your AWS account ID
                    ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
                    
                    aws lambda create-function \
                    --function-name ChimeSDKBackupHandler \
                    --runtime nodejs18.x \
                    --role arn:aws:iam::${ACCOUNT_ID}:role/ChimeSDKLambdaRole \
                    --handler backup-index.handler \
                    --zip-file fileb://lambda/backup-function.zip

exemplo : Adicione a permissão Lambda para o Amazon Chime SDK à função de backup



                    # Get your AWS account ID
                    ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
                    
                    aws lambda add-permission \
                    --function-name ChimeSDKBackupHandler \
                    --statement-id ChimeSDK \
                    --action lambda:InvokeFunction \
                    --principal voiceconnector.chime.amazonaws.com \
                    --source-account ${ACCOUNT_ID}

exemplo : Crie um aplicativo de mídia SIP de backup


# Get your backup Lambda function ARN
BACKUP_LAMBDA_ARN=$(aws lambda get-function --function-name ChimeSDKBackupHandler --query Configuration.FunctionArn --output text)

aws chime-sdk-voice create-sip-media-application \
  --aws-region us-east-1 \
  --name "BackupCallHandlerApp" \
  --endpoints "[{\"LambdaArn\":\"${BACKUP_LAMBDA_ARN}\"}]"

# Get the backup SIP media application ID
BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
  --output text)

exemplo : Obtenha o ID da regra SIP


SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
  --query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
  --output text)

exemplo : atualize a regra SIP para incluir os dois aplicativos com prioridades


aws chime-sdk-voice update-sip-rule \
  --sip-rule-id ${SIP_RULE_ID} \
  --target-applications "[{\"SipMediaApplicationId\":\"${SIP_MEDIA_APP_ID}\",\"Priority\":1},{\"SipMediaApplicationId\":\"${BACKUP_SIP_MEDIA_APP_ID}\",\"Priority\":2}]"

Esse comando atualiza a regra SIP para incluir os aplicativos de mídia SIP primários e de backup com suas respectivas prioridades.

Crie chamadas externas

Você também pode criar chamadas externas que invocam sua função Lambda usando a API. CreateSIPMediaApplicationCall


# Use a phone number from your inventory for outbound calling
FROM_PHONE_NUMBER=${PHONE_NUMBER}
TO_PHONE_NUMBER="+12065550102"  # Replace with a valid destination number

aws chime-sdk-voice create-sip-media-application-call \
  --from-phone-number "${FROM_PHONE_NUMBER}" \
  --to-phone-number "${TO_PHONE_NUMBER}" \
  --sip-media-application-id ${SIP_MEDIA_APP_ID}

Substitua o número de telefone de destino por um número válido. Você precisa ter os números de telefone em seu inventário para fazer chamadas reais.

Acione o Lambda durante uma chamada ativa

Você pode acionar sua função Lambda durante uma chamada ativa usando a UpdateSIPMediaApplicationCall API.


# Replace with an actual transaction ID from an active call
TRANSACTION_ID="txn-3ac9de3f-6b5a-4be9-9e7e-EXAMPLE33333"

aws chime-sdk-voice update-sip-media-application-call \
  --sip-media-application-id ${SIP_MEDIA_APP_ID} \
  --transaction-id ${TRANSACTION_ID} \
  --arguments '{"action":"custom-action"}'

O ID da transação é fornecido nos dados do evento enviados para sua função Lambda quando uma chamada está ativa.

Limpar recursos

Ao concluir este tutorial, você deve excluir os recursos criados para evitar cobranças adicionais.

exemplo : Excluir regras SIP


# Get the SIP rule ID if you don't have it
SIP_RULE_ID=$(aws chime-sdk-voice list-sip-rules \
  --query "SipRules[?Name=='IncomingCallRule'].SipRuleId" \
  --output text)

aws chime-sdk-voice delete-sip-rule --sip-rule-id ${SIP_RULE_ID}

exemplo : Excluir aplicativos de mídia SIP


# Get SIP media application IDs if you don't have them
SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='MyCallHandlerApp'].SipMediaApplicationId" \
  --output text)

BACKUP_SIP_MEDIA_APP_ID=$(aws chime-sdk-voice list-sip-media-applications \
  --query "SipMediaApplications[?Name=='BackupCallHandlerApp'].SipMediaApplicationId" \
  --output text)

aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${SIP_MEDIA_APP_ID}
aws chime-sdk-voice delete-sip-media-application --sip-media-application-id ${BACKUP_SIP_MEDIA_APP_ID}

exemplo : Excluir funções do Lambda


aws lambda delete-function --function-name ChimeSDKCallHandler
aws lambda delete-function --function-name ChimeSDKBackupHandler

exemplo : Excluir função do IAM


aws iam detach-role-policy --role-name ChimeSDKLambdaRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

aws iam delete-role --role-name ChimeSDKLambdaRole

exemplo : Divulgue números de telefone

Se você não precisar mais dos números de telefone, você pode liberá-los:


# List phone numbers
aws chime-sdk-voice list-phone-numbers

# Delete a specific phone number
aws chime-sdk-voice delete-phone-number --phone-number-id ${PHONE_NUMBER}

Observe que os números de telefone entram no status ReleaseInProgress "" por 7 dias antes de serem totalmente liberados. Durante esse período, você pode restaurá-los usando o restore-phone-number comando, se necessário.

Indo para a produção

Este tutorial demonstra a funcionalidade básica de rotear chamadas para funções do Lambda usando o áudio PSTN do SDK do Amazon Chime. No entanto, para ambientes de produção, você deve considerar as seguintes práticas recomendadas:

Considerações sobre segurança

Implemente permissões de privilégio mínimo. Crie políticas personalizadas do IAM que concedam somente as permissões específicas necessárias para suas funções do Lambda.
Adicione condições de ARN de origem às permissões do Lambda. Restrinja quais aplicativos de mídia SIP podem invocar suas funções do Lambda.
Implemente a validação de entrada. Adicione validação às suas funções do Lambda para garantir que elas processem somente eventos válidos.
Considere a implantação de VPC. Para aumentar a segurança, implante suas funções do Lambda em uma VPC com grupos de segurança apropriados.
Criptografe dados confidenciais. Use AWS Key Management Service para criptografar todos os dados confidenciais usados pelo seu aplicativo.

Considerações sobre arquitetura

Implemente monitoramento e registro. Configure CloudWatch alarmes e registros para monitorar a integridade e o desempenho do seu aplicativo.
Adicione tratamento de erros. Implemente um tratamento abrangente de erros em suas funções do Lambda.
Considere os limites de escala. Esteja ciente das cotas de serviço e dos aumentos de solicitações, se necessário, para altos volumes de chamadas.
Implemente a infraestrutura como código. Use AWS CloudFormation ou o AWS CDK para implantar sua infraestrutura.
Configure CI/CD oleodutos. Implemente integração e implantação contínuas para suas funções Lambda.

Para obter mais informações sobre a criação de aplicativos prontos para produção, consulte:

Próximas etapas

Agora que você aprendeu a rotear chamadas para funções do Lambda usando o áudio PSTN do SDK do Amazon Chime, você pode explorar recursos mais avançados:

Integre-se ao Amazon Lex para gerenciar a interação de diálogo para um cenário de agente inteligente. Para obter mais informações, consulte Criar um bot do Amazon Lex V2 para o sistema de mensagens do SDK do Amazon Chime.
Configure a análise de voz para obter informações sobre suas chamadas. Para obter mais informações, consulte Gerar insights de chamadas usando analytics de chamadas para o SDK do Amazon Chime.
Explore ações avançadas de controle de chamadas para criar fluxos de chamadas sofisticados. Para obter mais informações, consulte Usar as configurações de analytics de chamadas do SDK do Amazon Chime.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Encaminhamento de chamadas e eventos para funções AWS Lambda

Saiba mais sobre o uso dos trechos de chamada do serviço de áudio PSTN