Crie um assistente de voz de IA utilizando o Twilio Voice, a Realtime API da OpenAI e Node.js

Time to read:

August 28, 2025

Escrito por

Paul Kamp

Twilion

Dominik Kundel

Contribuidor

Revisado por

Brent Schooley

Twilion

Marius Obert

Twilion

Sarah Biffle

Twilion

Chris Gargotta

Twilion

Rishab Kumar

Twilion

Crie um assistente de voz de IA utilizando o Twilio Voice, a Realtime API da OpenAI e Node.js

Estamos muito animados com o lançamento da Realtime API pela OpenAI. A API abre recursos de fala em fala (S2S) para seu modelo multimodal GPT Realtime, que fornece suporte para entrada e saída diretas de áudio, eliminando a necessidade de converter texto em voz (SST) ou texto em fala (TTS).

O que isso significa na prática? Os modelos S2S reduzem a latência. A Realtime API da OpenAI possibilita conversas fluidas que se aproximam de um diálogo humano real. Você certamente concordará. É por isso que estamos tão animados em fornecer essa integração de lançamento em colaboração com a OpenAI.

Neste tutorial, mostrarei como criar um assistente de voz de IA usando o Twilio Voice e a Realtime API da OpenAI com Node.js. Depois de criar a ferramenta, você poderá conversar com o assistente como se estivesse interagindo com uma pessoa, solicitar informações e até pedir para ele contar piadas! Juntos, configuraremos um servidor Twilio Media Stream para receber o áudio de uma chamada telefônica, processá-lo com a Realtime API da OpenAI e enviar a resposta da IA de volta à Twilio para dar continuidade à conversa.

Tudo pronto? Vamos começar!

Este app também está disponível como um aplicativo pré-configurado no Code Exchange. Você pode encontrá-lo aqui.

Demonstrarei chamadas outbound para um assistente de IA de voz em Node.js aqui.

Pré-requisitos

Para acompanhar este tutorial, você precisará do seguinte:

Node.js 18+ (usei a versão 18.20.4 neste tutorial; você pode baixá-la aqui)
Uma conta da Twilio. Se ainda não tiver, cadastre-se para uma avaliação gratuita aqui.
Um número de telefone da Twilio com recursos de voz. Confira as instruções para comprar um número de telefone.
Uma conta da OpenAI e uma chave de API da OpenAI. Você pode se inscrever aqui.
Acesso à Realtime API da OpenAI. Clique aqui para obter mais informações.
(Opcional) ngrok ou outra solução de tunelamento para expor o servidor local à internet para testes. Baixe o ngrok aqui.
Um telefone celular ou telefone fixo capaz de realizar chamadas telefônicas.

E, com isso, você pode começar a criar!

Configure o projeto Node de fala em fala com a Realtime API

Nas próximas etapas, explicarei como configurar o projeto, instalar dependências e escrever o código necessário para fazer proxy das conexões websocket entre a Twilio e a OpenAI.

Ou acesse nosso repositório aqui. Também disponibilizamos uma versão em vídeo deste tutorial, que você pode conferir aqui:

Muito bem, vamos começar!

Etapa 1: inicializar o projeto

Primeiro, configure um novo projeto Node.js:

mkdir speech-assistant-openai-realtime-api-node
cd speech-assistant-openai-realtime-api-node
npm init -y; npm pkg set type="module";

Etapa 2: instalar dependências

Em seguida, instale as dependências necessárias para o projeto. Usaremos a estrutura web Fastify e precisaremos de suporte para websocket. Também armazenaremos a variável de ambiente sensível em um arquivo .env.

npm install fastify ws dotenv @fastify/formbody @fastify/websocket

Etapa 3: criar os arquivos do projeto

Criaremos um arquivo chamado index.js para o código principal. Também teremos um arquivo .env para armazenar variáveis de ambiente. Confira mais informações sobre essa estratégia aqui.

Nesse caso, você só precisará da chave de API da OpenAI no arquivo .env. Verifique se ela tem acesso à Realtime API.

Etapa 3.1: criar o arquivo .env

Primeiro, crie o arquivo .env:

touch .env

Em seguida, no editor de texto de sua preferência, adicione a OPENAI_API_KEY na primeira linha:

OPENAI_API_KEY="your_openai_api_key_here"

Etapa 3.2: criar o arquivo index.js

Em seguida, crie um novo arquivo chamado index.js no diretório do projeto:

touch index.js

Etapa 4: escrever o código do servidor

Ótimo. Tudo pronto para conferirmos o tutorial. Vou dividir o código index.js em várias etapas e explicar cada uma delas. Para agilizar o processo, você pode migrar para o app Code Exchange ou para o repositório.

Etapa 4.1: importar dependências, carregar a variável de ambiente e inicializar o Fastify

É simples. Vamos começar importando os módulos necessários, configurando a resolução de caminhos e carregando as variáveis de ambiente do arquivo .env.

Cole o seguinte código no arquivo index.js:

import Fastify from 'fastify';
import WebSocket from 'ws';
import fs from 'fs';
import dotenv from 'dotenv';
import fastifyFormBody from '@fastify/formbody';
import fastifyWs from '@fastify/websocket';
// Load environment variables from .env file
dotenv.config();
// Retrieve the OpenAI API key from environment variables. You must have OpenAI Realtime API access.
const { OPENAI_API_KEY } = process.env;
if (!OPENAI_API_KEY) {
    console.error('Missing OpenAI API key. Please set it in the .env file.');
    process.exit(1);
}
// Initialize Fastify
const fastify = Fastify();
fastify.register(fastifyFormBody);
fastify.register(fastifyWs);

Etapa 4.2: definir algumas constantes

Depois, definimos constantes para a mensagem do sistema, a voz e a porta do servidor. Também selecionaremos os eventos da OpenAI que serão registrados no console.

Veja o que você deve colar em seguida no arquivo:

// Constants
const SYSTEM_MESSAGE = 'You are a helpful and bubbly AI assistant who loves to chat about anything the user is interested about and is prepared to offer them facts. You have a penchant for dad jokes, owl jokes, and rickrolling – subtly. Always stay positive, but work in a joke when appropriate.';
const VOICE = 'alloy';
const TEMPERATURE = 0.8; // Controls the randomness of the AI's responses
const PORT = process.env.PORT || 5050; // Allow dynamic port assignment
// List of Event Types to log to the console. See the OpenAI Realtime API Documentation: https://platform.openai.com/docs/api-reference/realtime
const LOG_EVENT_TYPES = [
    'error',
    'response.content.done',
    'rate_limits.updated',
    'response.done',
    'input_audio_buffer.committed',
    'input_audio_buffer.speech_stopped',
    'input_audio_buffer.speech_started',
    'session.created',
    'session.updated'
];

Aqui, a SYSTEM_MESSAGE define o tom e o comportamento da IA durante a conversa, que posteriormente serão enviados à OpenAI como instruções. Ao personalizar essa mensagem, você pode controlar a personalidade e o estilo de interação da IA. Em algumas seções, veremos como enviá-la à OpenAI para influenciar a conversa. Para obter mais detalhes sobre o prompt, consulte o Guia de prompts da Realtime da OpenAI.

A constante VOICE define a voz da IA. Você pode escolher uma voz aqui.

A TEMPERATURE controla o grau de aleatoriedade das respostas do LLM (quanto maior o valor, mais aleatórias elas serão).

A constante PORT controla em qual porta o aplicativo será executado. Falaremos mais a respeito na seção do ngrok a seguir.

Por fim, LOG_EVENT_TYPES define os tipos de eventos da OpenAI que serão exibidos na linha de comando. Você pode encontrar a lista completa na documentação da Realtime API da OpenAI.

Etapa 4.3: definir duas rotas

Agora, vamos ao coração do código! Definimos uma rota raiz (principalmente para verificações de integridade) e uma rota para processar chamadas recebidas. A rota /incoming-call retornará TwiML, a Twilio Markup Language, para instruir a Twilio sobre como processar a chamada. Veremos mais detalhes em instantes.

Cole o trecho no arquivo index.js após definir a lista de constantes LOG_EVENT_TYPES:

// Root Route
fastify.get('/', async (request, reply) => {
    reply.send({ message: 'Twilio Media Stream Server is running!' });
});
// Route for Twilio to handle incoming and outgoing calls
// <Say> punctuation to improve text-to-speech translation
fastify.all('/incoming-call', async (request, reply) => {
    const twimlResponse = `<?xml version="1.0" encoding="UTF-8"?>
                          <Response>
                              <Say voice="Google.en-US-Chirp3-HD-Aoede">Please wait while we connect your call to the A. I. voice assistant, powered by Twilio and the Open A I Realtime API</Say>
                              <Pause length="1"/>
                              <Say voice="Google.en-US-Chirp3-HD-Aoede">O.K. you can start talking!</Say>
                              <Connect>
                                  <Stream url="wss://${request.headers.host}/media-stream" />
                              </Connect>
                          </Response>`;

    reply.type('text/xml').send(twimlResponse);
});

Como acontece em todo o TwiML, começamos com a versão XML e abrimos uma tag <Response>. Em seguida, fazemos a Twilio reproduzir uma breve mensagem para o autor da chamada, como, por exemplo, "divirta-se!", inserimos uma pausa de 2 segundos e pedimos que ele comece a falar.

O verbo <Connect> trabalha em conjunto com o substantivo <Stream> para abrir um fluxo bidirecional usando o Media Streams da Twilio. É aqui que a demonstração se transforma em realidade. Na próxima etapa, mostrarei como usaremos o proxy de áudio entre dois websockets.

Etapa 4.4: gerenciar conexões WebSocket

Agora, precisamos configurar a rota WebSocket para streaming de mídia (a rota que fornecemos à Twilio na seção anterior) e configurar websockets com a Twilio e a OpenAI. Este código é um pouco extenso, mas vou explicar o que está acontecendo logo após o bloco.

Cole este código a seguir onde definimos as rotas:

// WebSocket route for media-stream
fastify.register(async (fastify) => {
    fastify.get('/media-stream', { websocket: true }, (connection, req) => {
        console.log('Client connected');
        const openAiWs = new WebSocket(`wss://api.openai.com/v1/realtime?model=gpt-realtime&temperature=${TEMPERATURE}`, {
            headers: {
                Authorization: `Bearer ${OPENAI_API_KEY}`,
            }
        });
        let streamSid = null;

        const sendSessionUpdate = () => {
            const sessionUpdate = {
                type: 'session.update',
                session: {
                    type: 'realtime',
                    model: "gpt-realtime",
                    output_modalities: ["audio"],
                    audio: {
                        input: { format: { type: 'audio/pcmu' }, turn_detection: { type: "server_vad" } },
                        output: { format: { type: 'audio/pcmu' }, voice: VOICE },
                    },
                    instructions: SYSTEM_MESSAGE,
                },
            };
            console.log('Sending session update:', JSON.stringify(sessionUpdate));
            openAiWs.send(JSON.stringify(sessionUpdate));
        };

        // Open event for OpenAI WebSocket
        openAiWs.on('open', () => {
            console.log('Connected to the OpenAI Realtime API');
            setTimeout(sendSessionUpdate, 250); // Ensure connection stability, send after .25 seconds
        });
        // Listen for messages from the OpenAI WebSocket (and send to Twilio if necessary)
        openAiWs.on('message', (data) => {
            try {
                const response = JSON.parse(data);
                if (LOG_EVENT_TYPES.includes(response.type)) {
                    console.log(`Received event: ${response.type}`, response);
                }
                if (response.type === 'session.updated') {
                    console.log('Session updated successfully:', response);
                }
                if (response.type === 'response.output_audio.delta' && response.delta) {
                    const audioDelta = {
                        event: 'media',
                        streamSid: streamSid,
                        media: { payload: Buffer.from(response.delta, 'base64').toString('base64') }
                    };
                    connection.send(JSON.stringify(audioDelta));
                }
            } catch (error) {
                console.error('Error processing OpenAI message:', error, 'Raw message:', data);
            }
        });
        // Handle incoming messages from Twilio
        connection.on('message', (message) => {
            try {
                const data = JSON.parse(message);
                switch (data.event) {
                    case 'media':
                        if (openAiWs.readyState === WebSocket.OPEN) {
                            const audioAppend = {
                                type: 'input_audio_buffer.append',
                                audio: data.media.payload
                            };
                            openAiWs.send(JSON.stringify(audioAppend));
                        }
                        break;
                    case 'start':
                        streamSid = data.start.streamSid;
                        console.log('Incoming stream has started', streamSid);
                        break;
                    default:
                        console.log('Received non-media event:', data.event);
                        break;
                }
            } catch (error) {
                console.error('Error parsing message:', error, 'Message:', message);
            }
        });
        // Handle connection close
        connection.on('close', () => {
            if (openAiWs.readyState === WebSocket.OPEN) openAiWs.close();
            console.log('Client disconnected.');
        });
        // Handle WebSocket close and errors
        openAiWs.on('close', () => {
            console.log('Disconnected from the OpenAI Realtime API');
        });
        openAiWs.on('error', (error) => {
            console.error('Error in the OpenAI WebSocket:', error);
        });
    });
});

Como você pode ver, primeiro configuramos uma rota WebSocket (/media-stream) para gerenciar o streaming de mídia entre a Twilio e a OpenAI. Essa é a rota que mencionamos no TwiML anteriormente. As próximas duas áreas exigem uma explicação mais detalhada.

Configure a sessão e a conversa da Realtime API da OpenAI

Então, configuramos nossa sessão com a OpenAI. Essa configuração é enviada ao WebSocket da OpenAI como um objeto JSON em seguida à abertura da conexão, após um pequeno atraso.

Em seguida, usamos a função sendSessionUpdate() para definir como a IA interage e responde. Você pode ler mais sobre as opções que escolhi na documentação da Realtime API da OpenAI.

A função sendSessionUpdate também configura os atributos da sessão da OpenAI:

type: aqui informamos à OpenAI que estamos usando realtime
model: estamos usando o modelo gpt-realtime
audio.input.turn_detection: habilita a detecção de atividade de voz (VAD) no lado do servidor com server_vad.
audio.input.format.type/audio.output.format.type: especifica formatos de áudio, que alteramos para audio/pcmu devido aos requisitos da Twilio.
audio.output.voice : o modelo usará a VOICE definida anteriormente.
instructions: influencia a interação da IA usando SYSTEM_MESSAGE.
output_modalities: habilita a comunicação por áudio.

Proxy entre os WebSockets da Twilio e da OpenAI

As linhas a seguir fazem o proxy dos dados de áudio (usando o formato G.711 u-law, compatível com a Twilio) entre as conexões Twilio Media Stream e WebSocket da Realtime API da OpenAI. Quando a chamada começa, é aqui que a voz do autor da chamada é processada e o áudio gerado pela IA é transmitido de volta.

Confira em detalhes como fazemos o proxy entre a Realtime da OpenAI e a Twilio:

Evento start: captura o ID exclusivo do stream (streamSid).
Evento media: processa e encaminha os pacotes de dados de áudio da chamada em andamento para a OpenAI.
response.output_audio.delta: processa os dados de áudio gerados pela IA da OpenAI e recodifica-os para envio à Twilio.
Evento close do WebSocket da Twilio: processa a desconexão do cliente e encerra os streams.

Etapa 4.5: preparar o servidor

E, para concluir, iniciamos o servidor Fastify usando a porta definida anteriormente. Cole o trecho a seguir e pronto!

fastify.listen({ port: PORT }, (err) => {
    if (err) {
        console.error(err);
        process.exit(1);
    }
    console.log(`Server is listening on port ${PORT}`);
});

Execute o servidor

Saia do arquivo.

Você pode executar o servidor com o seguinte comando:

node index.js

Se o servidor iniciar corretamente, você verá a mensagem Server is listening on port 5050 (Servidor em execução na porta 5050) (ou na porta especificada) em seu terminal.

Conclua a configuração

Agora é hora de fornecer instruções à Twilio e finalizar a integração. Vamos usar o proxy reverso do ngrok para tornar o servidor acessível publicamente.

Etapa 5: expor o servidor à Twilio usando ngrok

Agora, você precisa usar o ngrok ou um serviço semelhante (ou um servidor virtual privado etc.) para expor o servidor local à internet pública. A Twilio requer um URL público para enviar solicitações ao servidor e receber instruções dele.

Neste artigo, fornecerei instruções para usar o ngrok. Você pode encontrar outras opções de proxy reverso ou tunelamento aqui e observações sobre outras opções aqui.

Baixe e instale o ngrok, se ainda não tiver instalado a ferramenta, e execute o comando a seguir. Se você alterou a porta 5050, atualize-a aqui:

ngrok http 5050

Será fornecido um URL público (por exemplo, https://abc123.ngrok.io) que você pode usar para testes. Obtive o seguinte:

Etapa 6: configurar a Twilio

Estamos quase lá, não é mesmo?

Acesse o Console da Twilio e selecione o número habilitado para voz.

Em Voice & Fax (Voz e fax), defina o webhook A CALL COMES IN como seu URL do ngrok (na linha Forwarding (Encaminhamento), https://ad745c4093d9.ngrok.app, como no exemplo da captura de tela), acrescentando /incoming-call. Por exemplo, https://ad745c4093d9.ngrok.app/incoming-call.

Salve suas alterações. Você chegou à última etapa!

Teste a configuração

Verifique se a sessão do ngrok ainda está em execução e se o servidor está ativo. Se estiver tudo certo, você poderá fazer uma chamada para seu número Twilio usando um telefone celular ou telefone fixo.

O servidor deverá processar a chamada (fornecendo seu TwiML à Twilio) e, em seguida, fazer o proxy entre a Realtime API da OpenAI e os WebSockets da Twilio. Comece a falar. Agora você deverá ouvir a mensagem do sistema baseada em IA e poderá interagir com ela!

Problemas comuns e resolução de problemas

Se a configuração não estiver funcionando, mas o servidor estiver em execução, verifique primeiro o seguinte:

O ngrok está em execução? O URL foi configurado corretamente na seção Voice Configuration (Configuração de voz) -> A Call Comes In (Uma chamada é recebida)?
Ocorreu algum erro com a Twilio, possivelmente no TwiML? Você pode depurar erros da Twilio de várias maneiras. Confira mais informações neste artigo.
Seu código está chamando a OpenAI corretamente? Veja mais informações em sua documentação.

Conclusão

Não é incrível? Você acaba de criar um assistente de voz de IA usando o Twilio Voice e a Realtime API da OpenAI. Essa configuração permite criar aplicações de voz dinâmicas, interativas e de baixa latência com capacidade para responder ao input do usuário quase em tempo real, além de oferecer uma voz confiável sempre que necessário.

Mal podemos esperar para falar sobre o que você vai criar.

Próxima etapa:

Confira a documentação da Twilio e as documentações da Realtime API da OpenAI para conhecer recursos mais avançados.
Consulte a documentação da OpenAI sobre conceitos.

Paul Kamp é o editor-chefe técnico do blog da Twilio. Você pode entrar em contato com ele, ou provavelmente com seu assistente de IA, pelo e-mail pkamp [arroba] twilio.com.

Dominik Kundel trabalha na experiência do desenvolvedor na OpenAI.

Publicações relacionadas

Recursos relacionados

Twilio Docs

De APIs a SDKs e aplicativos de amostra

Documentação de referência de API, SDKs, bibliotecas auxiliares, guias de início rápido e tutoriais para sua linguagem e plataforma.

Centro de Recursos

Os mais recentes e-books, relatórios do setor e webinars

Aprenda com especialistas em engajamento do cliente para melhorar sua própria comunicação.

Ahoy

Centro da comunidade de desenvolvedores da Twilio

Melhores práticas, exemplos de código e inspiração para criar comunicações e experiências de engajamento digital.