---
title: "How to Connect Your Twilio Agent to External APIs in Node.js"
description: "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."
---

# How to Connect Your Twilio Agent to External APIs in Node.js

[Twilio](https://yomu.fyi/company/twilio) · Dhruv Patel, Amanda Lange · Sep 14, 2026

**Type:** Tutorial

## Summary

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.

## Context

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.

## Approach / What changed

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.

## Takeaways

- 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.

## FAQ

### How does the agent decide when to call the Cat Facts API?

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.

### Why does the example require Node.js 18 or later?

The application uses fetch to call the external API. The tutorial notes that fetch is built in starting with Node.js version 18.

### Does the Cat Facts API need its own authentication key?

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.

**Tags:** [Node.js](https://yomu.fyi/topic/node-js), [OpenAI API](https://yomu.fyi/topic/openai-api), [REST APIs](https://yomu.fyi/topic/rest-api), [Twilio](https://yomu.fyi/topic/twilio), [WebSockets](https://yomu.fyi/topic/websockets)

- Source: [Twilio](https://www.twilio.com/en-us/blog/developers/tutorials/product/how-to-connect-twilio-agent-to-external-apis-nodejs)
- Source URL: https://www.twilio.com/en-us/blog/developers/tutorials/product/how-to-connect-twilio-agent-to-external-apis-nodejs
- Ingested by Yomu: 2026-09-15T12:01:57.863Z

[Read original post](https://www.twilio.com/en-us/blog/developers/tutorials/product/how-to-connect-twilio-agent-to-external-apis-nodejs)