TwilioDhruv Patel, Amanda LangeTutorial
Voice agents can converse, but they need external APIs to retrieve live information or take actions such as checking inventory or booking appointments. This tutorial builds a Node.js voice agent with Twilio Conversation Relay, Express, WebSockets, and the OpenAI Node.js SDK. A Conversation Relay WebSocket handler collects voice prompts, maintains conversation messages, streams model output back to the call, and defines a get_cat_fact tool that fetches JSON from the unauthenticated Cat Facts REST API. The service returns the fetched fact or an error message, while TwiML connects Twilio's voice-capable number to the WebSocket endpoint. Testing uses Node.js 18+, an OpenAI API key, ngrok, and a POST /voice webhook; the stated result is that callers can ask for a cat fact and hear the API response.
The example demonstrates how a Twilio voice agent can use an LLM tool call to access live data from an external REST API. It uses the Cat Facts API because it requires no additional authentication.
The application uses index.js to expose a POST /voice webhook and a /ws WebSocket endpoint, with TwiML connecting Conversation Relay to the agent. conversationRelayHandler.js parses setup, prompt, interrupt, and error messages while tracking conversation history. openAiService.js defines the system prompt and tool schema, streams OpenAI output, and executes get_cat_fact with Node.js fetch against Cat Facts. The local server is exposed with ngrok and configured as the Twilio number's POST webhook.
Conversation Relay connects the Twilio voice call to a WebSocket, where prompts are parsed and assistant text is streamed back in real time.
The get_cat_fact tool calls https://catfact.ninja/fact with fetch, parses the JSON response, and returns either the fact or an error message.
Node.js 18 or higher is required because the example relies on fetch being built in; ngrok exposes the local webhook to Twilio.
The OpenAI service defines a tool schema and a system prompt that instructs the model when to make external API calls based on voice prompts. When the model requests the tool, executeTool performs the Cat Facts request and supplies the result for the response.
The application uses fetch to call the external API. The tutorial notes that fetch is built in starting with Node.js version 18.
No. The sample Cat Facts API requires no additional authentication. Other APIs may require keys, which the tutorial says can be stored in the .env file and used according to each API's rules.
Summaries are generated from the original by a language model. Check the original before relying on it.
See the idea
Axum is a Rust web framework for composing routes, middleware, and extractors. This explainer shows how different login flows become verified identity before a handler responds.
Keep reading
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
One useful email. Unsubscribe anytime.
