Bot di chiamata Graph

Panoramica

Questo approccio rende l’agente un’identità Teams chiamabile. Un utente lo cerca per nome e lo chiama in 1:1, e l’agente risponde in tempo reale — senza numero di telefono, PSTN o Communications Credits. È l’unico approccio chiamabile per nome e il più complesso da gestire.

Usa un bot Microsoft Graph per contenuti multimediali in tempo reale (la piattaforma di chiamata Cloud Communications). L’SDK multimediale (Microsoft.Skype.Bots.Media) funziona solo con .NET su Windows Server — non esiste un percorso Linux o non .NET per l’audio raw nelle chiamate Teams.

Come funziona

Il bot risponde con contenuti multimediali ospitati dall’applicazione, riceve 50 frame audio/sec (PCM 16 kHz da 20 ms), li inoltra all’agente ElevenLabs tramite WebSocket e trasmette l’audio dell’agente nella chiamata.

Requisiti

1. Una registrazione Azure Bot + app (registrazione dell’app Entra).
2. Autorizzazioni dell’applicazione Graph con consenso dell’amministratore: Calls.AccessMedia.All (contenuti multimediali raw) più Calls.Initiate.All.
3. Una VM Windows Server (≥ 2 core fisici — ad esempio Standard_D4s_v3) con IP pubblico e porte multimediali aperte.
4. Un certificato TLS firmato da una CA su un FQDN pubblico per l’endpoint di contenuti multimediali/segnalazione (la piattaforma multimediale rifiuta i certificati autofirmati).
5. Un agente ElevenLabs impostato su PCM 16000 Hz su entrambi i lati: formato di output TTS nella scheda Voce, formato audio di input utente nella scheda Avanzate.

Autorizzazioni e ruoli

Passaggio 1 — Registra il bot + autorizzazioni Graph

Crea una registrazione dell’app e un Azure Bot associato, quindi concedi e approva le autorizzazioni di chiamata (per il consenso ti servono i ruoli Amministratore globale / Amministratore ruoli con privilegi):

APPID=$(az ad app create --display-name "ElevenLabs Teams Agent" \
  --sign-in-audience AzureADMyOrg --query appId -o tsv)
az ad sp create --id "$APPID"
# create a client secret and record it
az ad app credential reset --id "$APPID" --display-name bot --query password -o tsv
# Azure Bot bound to the app
az bot create --resource-group $RG --name el-teams-agent-bot \
  --app-type SingleTenant --appid "$APPID" --tenant-id $TENANT \
  --endpoint "https://YOUR_FQDN/api/messages" --sku S1

Concedi i due ruoli dell’applicazione Graph e il consenso dell’amministratore (richiede Amministratore globale / Amministratore ruoli con privilegi), quindi verifica che le assegnazioni siano state applicate:

# Graph app roles: Calls.AccessMedia.All, Calls.Initiate.All
az ad app permission add --id "$APPID" --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions a7a681dc-756e-4909-b988-f160edc6655f=Role \
    284383ee-7f6e-4e40-a2a8-e85dcb029101=Role
az ad app permission admin-consent --id "$APPID"
# Verify — should print both role ids
az rest --method GET \
  --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='$APPID')/appRoleAssignments" \
  --query "value[].appRoleId" -o tsv

GRAPH_SP=$(az ad sp show --id 00000003-0000-0000-c000-000000000000 --query id -o tsv)
BOT_SP=$(az ad sp show --id "$APPID" --query id -o tsv)
for ROLE in a7a681dc-756e-4909-b988-f160edc6655f 284383ee-7f6e-4e40-a2a8-e85dcb029101; do
  az rest --method POST \
    --url "https://graph.microsoft.com/v1.0/servicePrincipals/$GRAPH_SP/appRoleAssignedTo" \
    --body "{\"principalId\": \"$BOT_SP\", \"resourceId\": \"$GRAPH_SP\", \"appRoleId\": \"$ROLE\"}"
done

Nel portale, verifica nell’interfaccia di amministrazione Entra in Registrazioni app → la tua app → Autorizzazioni API: entrambe le autorizzazioni dovrebbero mostrare Concesso con segni di spunta verdi.

Passaggio 2 — Configura la VM Windows, il certificato e le porte

az vm create -g $RG -n teams-media-bot --image Win2022Datacenter \
  --size Standard_D4s_v3 --admin-username azureuser --admin-password '<strong-pw>' \
  --public-ip-sku Standard --public-ip-address-dns-name elevenmediabot
az vm open-port -g $RG -n teams-media-bot --port 80,443,8445,9441 --priority 300

Sulla VM (il codice nativo della piattaforma multimediale li richiede — Windows Server non li include per impostazione predefinita):

# VC++ runtime + Media Foundation feature (required by NativeMedia.dll)
choco install -y vcredist140
Install-WindowsFeature Server-Media-Foundation
# CA cert for the VM's FQDN via win-acme (HTTP-01), then import to LocalMachine\My
& wacs.exe --target manual --host <vm-fqdn>.cloudapp.azure.com `
  --validation selfhosting --store pfxfile --pfxfilepath C:\bot\certs --accepttos

Apri le stesse porte nel firewall di Windows e annota l’impronta digitale del certificato — il bot associa Kestrel (443 + una porta per le notifiche) e la piattaforma multimediale (8445) al certificato.

Passaggio 3 — Compila ed esegui il bot

Parti da PublicSamples/EchoBot di microsoft-graph-comms-samples di Microsoft — usa net6.0 e viene compilato con l’SDK .NET (non servono Visual Studio Build Tools):

git clone --depth 1 https://github.com/microsoftgraph/microsoft-graph-comms-samples.git C:\bot\samples
cd C:\bot\samples\Samples\PublicSamples\EchoBot\src
dotnet build EchoBot.sln -c Release

Configura la sezione AppSettings di appsettings.json con AadAppId, AadAppSecret, ServiceDnsName/MediaDnsName (l’FQDN della VM), CertificateThumbprint e le porte (chiamate 443, notifiche 9441, contenuti multimediali 8445). Aggiungi due impostazioni per il bridge ElevenLabs indicato sotto: ElevenLabsAgentId e ElevenLabsOrigin (wss://api.elevenlabs.io, o il tuo host di residenza). Eseguilo come attività/servizio pianificato di Windows, così rimane attivo dopo i riavvii.

$s = New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Seconds 0) `
  -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -StartWhenAvailable
Set-ScheduledTask -TaskName EchoBot -Settings $s

Sostituisci l’eco con ElevenLabs

Il collegamento audio di EchoBot è semplice: SpeechService.AppendAudioBuffer(in) e un evento OnSendMediaBufferEventArgs(out). Sostituisci il corpo Azure Speech con un bridge WebSocket dell’agente ElevenLabs che mantiene la stessa interfaccia:

public class SpeechService
{
    private readonly AppSettings _settings;
    private readonly ILogger _logger;
    private ClientWebSocket _ws;
    private bool _started;
    private bool _connecting;
    public event EventHandler<MediaStreamEventArgs> SendMediaBuffer; // agent audio -> call
    public event EventHandler FlushMedia;                            // barge-in: drop queued audio
    public SpeechService(AppSettings settings, ILogger logger) { _settings = settings; _logger = logger; }
    // Caller audio -> ElevenLabs
    public async Task AppendAudioBuffer(AudioMediaBuffer buffer)
    {
        if (!_started)
        {
            if (_connecting) return;            // a connect attempt is already in flight
            _connecting = true;
            try { await Connect(); _started = true; }
            catch (Exception ex) { _logger.Error(ex, "ElevenLabs connect failed; retry on next frame"); return; }
            finally { _connecting = false; }
        }
        if (_ws?.State != WebSocketState.Open || buffer.Length <= 0) return;
        var pcm = new byte[buffer.Length];
        Marshal.Copy(buffer.Data, pcm, 0, (int)buffer.Length);
        var msg = JsonSerializer.Serialize(new { user_audio_chunk = Convert.ToBase64String(pcm) });
        await _ws.SendAsync(Encoding.UTF8.GetBytes(msg), WebSocketMessageType.Text, true, default);
    }
    private async Task Connect()
    {
        _ws = new ClientWebSocket();
        // ElevenLabsOrigin: wss://api.elevenlabs.io, or a residency host (.eu./.in./.sg.)
        var url = $"{_settings.ElevenLabsOrigin}/v1/convai/conversation?agent_id={_settings.ElevenLabsAgentId}";
        await _ws.ConnectAsync(new Uri(url), default);
        await _ws.SendAsync(Encoding.UTF8.GetBytes(
            JsonSerializer.Serialize(new { type = "conversation_initiation_client_data" })),
            WebSocketMessageType.Text, true, default);
        _ = Task.Run(ReceiveLoop);
    }
    private async Task ReceiveLoop()
    {
        var buf = new byte[32768]; var sb = new StringBuilder();
        while (_ws.State == WebSocketState.Open)
        {
            sb.Clear(); WebSocketReceiveResult r;
            do { r = await _ws.ReceiveAsync(buf, default); sb.Append(Encoding.UTF8.GetString(buf, 0, r.Count)); }
            while (!r.EndOfMessage);
            using var doc = JsonDocument.Parse(sb.ToString());
            var type = doc.RootElement.GetProperty("type").GetString();
            if (type == "audio")            // ElevenLabs audio -> call
                Emit(Convert.FromBase64String(doc.RootElement
                    .GetProperty("audio_event").GetProperty("audio_base_64").GetString()));
            else if (type == "ping")
                await _ws.SendAsync(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(new {
                    type = "pong", event_id = doc.RootElement.GetProperty("ping_event").GetProperty("event_id").GetInt32() })),
                    WebSocketMessageType.Text, true, default);
            else if (type == "interruption")  // barge-in: drop any agent audio still queued
                FlushMedia?.Invoke(this, EventArgs.Empty);
        }
    }
    // slice PCM into 20 ms / 640-byte frames the media platform expects
    private void Emit(byte[] pcm)
    {
        var all = new List<AudioMediaBuffer>(); long tick = DateTime.Now.Ticks;
        for (int off = 0; off < pcm.Length; off += 640)
        {
            var frame = new byte[640];
            Array.Copy(pcm, off, frame, 0, Math.Min(640, pcm.Length - off));
            all.AddRange(Utilities.CreateAudioMediaBuffers(frame, tick, _logger));
            tick += 20 * 10000;
        }
        if (all.Count > 0) SendMediaBuffer?.Invoke(this, new MediaStreamEventArgs { AudioMediaBuffers = all });
    }
}

Entrambi i lati sono PCM mono a 16 kHz, quindi è un passthrough base64 — imposta l’agente su pcm_16000. In caso di interruption di ElevenLabs (barge-in), il bridge genera FlushMedia; collegalo al tuo stream multimediale affinché elimini eventuali AudioMediaBuffer in coda, altrimenti l’agente continua a parlare sopra il chiamante. Il riferimento completo dei messaggi è nella documentazione WebSocket. La chiusura al termine della chiamata e il trasferimento assistito sono descritti nelle sezioni seguenti.

Passaggio 4 — Rendilo chiamabile in Teams

1. Abilita le chiamate nel canale Teams dell’Azure Bot e imposta il webhook di chiamata su https://YOUR_FQDN/api/calling:

   az bot msteams create -g $RG -n el-teams-agent-bot \
     --enable-calling --calling-web-hook "https://YOUR_FQDN/api/calling"

   Nel portale si trova nella risorsa Azure Bot → Canali → Microsoft Teams → scheda Chiamate:

   

   

2. Crea un manifest dell’app Teams con bots[0].supportsCalling: true e l’ID app del bot, quindi caricalo localmente (App → Gestisci le tue app → Carica un’app personalizzata), oppure pubblicalo a livello di organizzazione senza l’interfaccia: New-TeamsApp -DistributionMethod organization -Path ./bot-app.zip (modulo PowerShell MicrosoftTeams).

Cerca l’app per nome in Teams e chiamala — il bot risponde e l’agente ElevenLabs parla.

Chat di testo (stesso bot)

Lo stesso Azure Bot può anche rispondere ai messaggi di testo in Teams — gli utenti possono quindi chiamare l’agente oppure chattare con lui. Le chiamate e la messaggistica sono canali indipendenti del bot: il webhook di chiamata gestisce la voce, mentre un endpoint di messaggistica Bot Framework (/api/messages) gestisce la chat.

Indirizza l’endpoint di messaggistica del bot all’host che lo serve (il bot multimediale o qualsiasi altro servizio — non deve essere necessariamente la VM Windows):

az bot update -g $RG -n el-teams-agent-bot --endpoint "https://YOUR_FQDN/api/messages"

Implementa l’endpoint con l’SDK Bot Framework e inoltra ogni messaggio all’agente in modalità testo tramite lo stesso WebSocket di conversazione usato per la voce — invia un evento user_message, leggi l’evento agent_response. Prima abilita il campo primo messaggio nelle impostazioni delle sostituzioni dell’agente — il codice seguente lo sostituisce con un valore vuoto, affinché la risposta risponda al messaggio dell’utente anziché al saluto dell’agente:

public class ChatBot : ActivityHandler
{
    private readonly AppSettings _settings;
    public ChatBot(AppSettings settings) => _settings = settings;
    protected override async Task OnMessageActivityAsync(
        ITurnContext<IMessageActivity> turn, CancellationToken ct)
    {
        var reply = await AskAgent(turn.Activity.Text, ct);
        await turn.SendActivityAsync(MessageFactory.Text(reply), ct);
    }
    private async Task<string> AskAgent(string text, CancellationToken ct)
    {
        using var ws = new ClientWebSocket();
        var url = $"{_settings.ElevenLabsOrigin}/v1/convai/conversation?agent_id={_settings.ElevenLabsAgentId}";
        await ws.ConnectAsync(new Uri(url), ct);
        // Suppress the agent's greeting: with no override, the first agent_response is the
        // configured first message, not the answer to this user_message.
        await Send(ws, new
        {
            type = "conversation_initiation_client_data",
            conversation_config_override = new { agent = new { first_message = "" } },
        }, ct);
        await Send(ws, new { type = "user_message", text }, ct);
        var buf = new byte[16384]; var sb = new StringBuilder();
        while (ws.State == WebSocketState.Open)
        {
            sb.Clear(); WebSocketReceiveResult r;
            do { r = await ws.ReceiveAsync(buf, ct); sb.Append(Encoding.UTF8.GetString(buf, 0, r.Count)); }
            while (!r.EndOfMessage);
            using var doc = JsonDocument.Parse(sb.ToString());
            switch (doc.RootElement.GetProperty("type").GetString())
            {
                case "agent_response":
                    return doc.RootElement.GetProperty("agent_response_event")
                              .GetProperty("agent_response").GetString();
                case "ping":
                    await Send(ws, new { type = "pong", event_id = doc.RootElement
                        .GetProperty("ping_event").GetProperty("event_id").GetInt32() }, ct);
                    break;
            }
        }
        return "Sorry, I couldn't reach the agent.";
    }
    private static Task Send(ClientWebSocket ws, object msg, CancellationToken ct) =>
        ws.SendAsync(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(msg)),
            WebSocketMessageType.Text, true, ct);
}

Registralo nel modo standard (un CloudAdapter, il bot tramite AddTransient<IBot, ChatBot>() e un controller /api/messages) e aggiungi gli ambiti di chat alla voce del bot nel manifest:

"bots": [
  { "botId": "YOUR_APP_ID", "supportsCalling": true, "scopes": ["personal", "team", "groupChat"] }
]

Fine della chiamata

Quando ElevenLabs termina la conversazione (il relativo strumento Termina chiamata chiude il WebSocket), riaggancia la parte Teams:

await this.Call.DeleteAsync(); // after a short delay so the goodbye audio finishes

Trasferimento assistito a una persona

L’agente attiva uno strumento client personalizzato transfer_to_human; il bot invita un utente Teams nella chiamata in corso (aggiunta consultiva), quindi si ritira:

var target = new IdentitySet { User = new Identity { Id = humanObjectId } };
await this.Call.Participants.InviteAsync(target, replacesCallId: null);
// suppress the end-call hangup while transferring, and mute the bot

Risoluzione dei problemi

Link utili

• Panoramica dei bot per chiamate e riunioni
• Concetti relativi ai contenuti multimediali in tempo reale
• Registrare un bot di chiamata
• microsoft-graph-comms-samples (EchoBot)
• call: transfer (consultivo)
• Protocollo WebSocket dell’agente