Prerequisiti Considerazioni sui costi Cerca e fornisci numeri di telefono Creare una funzione Lambda per la gestione delle chiamate Crea un'applicazione multimediale SIP Configura il routing delle chiamate con le regole SIP Configura la ridondanza con più applicazioni multimediali SIP Crea chiamate in uscita Attiva Lambda durante una chiamata attiva Pulizia delle risorse Andare alla produzione Passaggi successivi

Instradamento delle chiamate alle AWS Lambda funzioni per l'audio PSTN di Amazon Chime SDK ()AWS CLI

Questo tutorial ti guida attraverso il processo di configurazione del routing delle chiamate verso le funzioni Lambda utilizzando il servizio audio PSTN Amazon Chime SDK. Imparerai come creare funzioni Lambda, configurare applicazioni multimediali SIP e configurare le regole SIP per gestire le chiamate in arrivo.

Prerequisiti

Prima di iniziare questo tutorial, assicurati di fare quanto segue:

Installa il AWS CLI. Per ulteriori informazioni, vedere Installazione o aggiornamento alla versione più recente di AWS CLI nella Guida per l'AWS CLI utente.
Configura il tuo AWS CLI con le credenziali appropriate. Esegui aws configure se non hai ancora impostato le tue credenziali.
Acquisisci familiarità di base con AWS Lambda i concetti di Amazon Chime SDK.
Configura autorizzazioni sufficienti per creare e gestire risorse Amazon Chime SDK e Lambda nel tuo account AWS.
Per il routing basato sul numero di telefono, devi avere un numero di telefono nell'inventario dei numeri di telefono dell'SDK Amazon Chime.
Per il routing basato su Voice Connector, devi avere un Voice Connector configurato nel tuo account.

Considerazioni sui costi

Il tutorial include istruzioni di pulizia per assicurarti di non incorrere in addebiti continui dopo il completamento. Per ulteriori informazioni, consulta i prezzi di Amazon Chime SDK.

Iniziamo con la configurazione del routing delle chiamate per l'audio PSTN di Amazon Chime SDK.

Cerca e fornisci numeri di telefono

Prima di creare regole SIP con trigger di numeri di telefono, devi avere numeri di telefono nell'inventario dell'SDK Amazon Chime. Ecco come cercare i numeri di telefono disponibili e fornirli.

Esempio : Cerca i numeri di telefono disponibili



# 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

Questo comando cerca i numeri di telefono gratuiti disponibili con il prefisso 844 negli Stati Uniti. È possibile modificare i parametri per cercare diversi tipi di numeri.

Esempio : Fornisci un numero di telefono

Dopo aver trovato un numero di telefono disponibile, puoi assegnarlo utilizzando il seguente comando:



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

Sostituiscilo +18445550100 con un numero di telefono effettivamente disponibile tra i risultati della ricerca. Questo comando fornirà il numero di telefono al tuo account.

Esempio : Controlla lo stato del numero di telefono

Dopo aver ordinato un numero di telefono, puoi verificarne lo stato:



# 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

Sostituisci l'ID dell'ordine con quello restituito dal create-phone-number-order comando.

Esempio : Elenca i numeri di telefono nel tuo inventario

Per visualizzare tutti i numeri di telefono presenti nel tuo inventario:



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

Per trovare numeri di telefono non assegnati che possono essere utilizzati per le regole SIP:



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

Creare una funzione Lambda per la gestione delle chiamate

Ora, creiamo una funzione Lambda che gestirà le chiamate in arrivo. La funzione riceverà eventi dal servizio audio PSTN e risponderà con istruzioni su come gestire la chiamata.

Esempio : crea un ruolo IAM per Lambda

Prima di creare la funzione Lambda, devi creare un ruolo IAM che conceda le autorizzazioni necessarie.



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

Questi comandi creano un ruolo IAM che consente a Lambda di assumerlo e di allegare la politica di esecuzione di base, che fornisce le autorizzazioni su cui Lambda può scrivere i log. CloudWatch

Esempio Crea una funzione Lambda:

Ora, crea una semplice funzione Lambda che gestirà le chiamate in arrivo.



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

Questa funzione Lambda risponde alle chiamate in arrivo con un messaggio vocale e poi si interrompe.

Esempio : Aggiungi l'autorizzazione Lambda per Amazon Chime SDK

Concedi l'autorizzazione al servizio Amazon Chime SDK per richiamare la tua funzione 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}

Questo comando consente al servizio Amazon Chime SDK Voice Connector di richiamare la funzione Lambda.

Crea un'applicazione multimediale SIP

Le applicazioni multimediali SIP collegano la funzione Lambda al servizio audio PSTN. In questa sezione, creerai un'applicazione multimediale SIP che utilizza la tua funzione Lambda.

Esempio : Create l'applicazione multimediale 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}\"}]"

L'applicazione multimediale SIP funge da ponte tra il servizio audio PSTN e la funzione Lambda.

Esempio : Ottieni l'ID dell'applicazione multimediale SIP

Dopo aver creato l'applicazione multimediale SIP, è necessario recuperarne l'ID per utilizzarlo più avanti nel 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}"

Prendi nota dell'ID dell'applicazione multimediale SIP restituito da questo comando, poiché ti servirà per creare le regole SIP.

Configura il routing delle chiamate con le regole SIP

Le regole SIP determinano il modo in cui le chiamate in arrivo vengono instradate alle applicazioni multimediali SIP. È possibile creare regole basate sui numeri di telefono o sui nomi host di Voice Connector.

Esempio : crea una regola SIP con attivazione del numero di telefono

Per indirizzare le chiamate in base a un numero di telefono, utilizzate il seguente 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}]"

Questo comando crea una regola SIP che indirizza le chiamate verso il numero di telefono dell'utente verso l'applicazione multimediale SIP.

Esempio : crea una regola SIP con il trigger Request URI hostname

In alternativa, puoi instradare le chiamate in base all'URI di richiesta di una chiamata SIP Voice Connector in entrata:



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

Sostituisci il nome host con l'hostname in uscita del Voice Connector.

Configura la ridondanza con più applicazioni multimediali SIP

Per la ridondanza e il failover, puoi creare più applicazioni multimediali SIP nella stessa regione AWS e specificarne l'ordine di priorità.

Esempio : crea una funzione Lambda di backup

Innanzitutto, crea una funzione Lambda di backup nella stessa regione.


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

Esempio : Aggiungi l'autorizzazione Lambda per Amazon Chime SDK alla funzione di 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}

Esempio : crea un'applicazione multimediale SIP di 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)

Esempio : Ottieni l'ID della regola SIP


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

Esempio : aggiorna la regola SIP per includere entrambe le applicazioni con priorità


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

Questo comando aggiorna la regola SIP per includere sia le applicazioni multimediali SIP primarie che quelle di backup con le rispettive priorità.

Crea chiamate in uscita

Puoi anche creare chiamate in uscita che richiamano la tua funzione Lambda utilizzando l'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}

Sostituisci il numero di telefono di destinazione con un numero valido. È necessario disporre dei numeri di telefono nell'inventario per effettuare chiamate reali.

Attiva Lambda durante una chiamata attiva

È possibile attivare la funzione Lambda durante una chiamata attiva utilizzando l'UpdateSIPMediaApplicationCallAPI.


# 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"}'

L'ID della transazione viene fornito nei dati dell'evento inviati alla funzione Lambda quando una chiamata è attiva.

Pulizia delle risorse

Al termine di questo tutorial, dovresti eliminare le risorse che hai creato per evitare di incorrere in costi aggiuntivi.

Esempio : Eliminare le regole 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}

Esempio : Eliminare le applicazioni multimediali 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}

Esempio : Elimina le funzioni Lambda


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

Esempio : elimina il ruolo 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

Esempio : rilascia i numeri di telefono

Se non ti servono più i numeri di telefono, puoi rilasciarli:


# 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}

Tieni presente che i numeri di telefono entrano nello stato ReleaseInProgress "" per 7 giorni prima di essere rilasciati completamente. Durante questo periodo, è possibile ripristinarli utilizzando il restore-phone-number comando, se necessario.

Andare alla produzione

Questo tutorial illustra le funzionalità di base del routing delle chiamate verso le funzioni Lambda utilizzando l'audio PSTN di Amazon Chime SDK. Tuttavia, per gli ambienti di produzione, dovresti prendere in considerazione le seguenti best practice:

Considerazioni relative alla sicurezza

Implementa le autorizzazioni con privilegi minimi. Crea policy IAM personalizzate che concedono solo le autorizzazioni specifiche necessarie per le tue funzioni Lambda.
Aggiungi condizioni ARN di origine alle autorizzazioni Lambda. Limita le applicazioni multimediali SIP che possono richiamare le tue funzioni Lambda.
Implementa la convalida degli input. Aggiungi la convalida alle tue funzioni Lambda per assicurarti che elaborino solo eventi validi.
Prendi in considerazione l'implementazione di un VPC. Per una maggiore sicurezza, distribuisci le tue funzioni Lambda all'interno di un VPC con gruppi di sicurezza appropriati.
Crittografa i dati sensibili. AWS Key Management Service Utilizzalo per crittografare tutti i dati sensibili utilizzati dall'applicazione.

Considerazioni sull'architettura

Implementa il monitoraggio e la registrazione. Imposta CloudWatch allarmi e registri per monitorare lo stato e le prestazioni dell'applicazione.
Aggiungi la gestione degli errori. Implementa una gestione completa degli errori nelle tue funzioni Lambda.
Prendi in considerazione i limiti di scalabilità. Fai attenzione alle quote di servizio e richiedi aumenti, se necessario, per volumi di chiamate elevati.
Implementa l'infrastruttura come codice. Usa AWS CloudFormation o poi AWS CDK per implementare la tua infrastruttura.
Configura le CI/CD pipeline. Implementa l'integrazione e la distribuzione continue per le tue funzioni Lambda.

Per ulteriori informazioni sulla creazione di applicazioni pronte per la produzione, consulta:

Passaggi successivi

Ora che hai imparato a instradare le chiamate verso le funzioni Lambda utilizzando l'audio PSTN di Amazon Chime SDK, puoi esplorare funzionalità più avanzate:

Esegui l'integrazione con Amazon Lex per gestire l'interazione di dialogo per uno scenario di agenti intelligenti. Per ulteriori informazioni, consulta Creazione di un bot Amazon Lex V2 per la messaggistica SDK Amazon Chime.
Configura l'analisi vocale per ottenere informazioni dettagliate dalle tue chiamate. Per ulteriori informazioni, consulta Generazione di informazioni dettagliate dalle chiamate utilizzando l'analisi delle chiamate per l'SDK Amazon Chime.
Esplora le azioni avanzate di controllo delle chiamate per creare flussi di chiamata sofisticati. Per ulteriori informazioni, consulta Utilizzo delle configurazioni di analisi delle chiamate per l'SDK Amazon Chime.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Instradamento di chiamate ed eventi verso le funzioni AWS Lambda

Scopri come usare i leg di chiamata del servizio audio PSTN