Loading post…
TwilioAmanda LangeTutorial
How to Connect Your Twilio Agent to External APIs
Summary
This tutorial shows how to connect a Twilio voice agent to an external REST API so it can retrieve live information during a conversation. It uses C# .NET 9, Twilio Conversation Relay, WebSockets, OpenAI tool calling, and the authentication-free Cat Facts API as a demonstration. An ASP.NET Core application exposes a /voice webhook, connects calls to a /ws endpoint, maintains conversation messages, streams model responses, and executes get_cat_fact by requesting and parsing JSON from the Cat Facts service. The guide also covers environment variables, NuGet dependencies, ngrok tunneling, Twilio number configuration, and troubleshooting for webhook URLs and API keys. After setup, callers can ask for a cat fact and receive one from the external service, illustrating how function tools can give voice agents real-time data and perform API-backed work.
Context
The tutorial is aimed at .NET developers and requires a Twilio account with a voice-capable phone number, the .NET 9 SDK or later, an OpenAI API key, ngrok, and an IDE or text editor.
Approach / What changed
The implementation uses an ASP.NET Core application with Twilio Conversation Relay over a WebSocket. It handles setup, voice prompts, interruptions, and errors; sends conversation history to OpenAI; accumulates tool-call arguments; and runs get_cat_fact to fetch and parse data from the Cat Facts API before returning the result through the voice conversation.
Takeaways
Twilio Conversation Relay connects the voice-capable Twilio number to an ASP.NET Core WebSocket endpoint, while TwiML supplies the initial greeting.
The get_cat_fact tool calls the Cat Facts API, parses its JSON response, and returns either the fact, a fallback message, or an error when retrieval fails.
ngrok exposes the local webhook to Twilio; the configured URL must match the running tunnel and end with /voice, using POST.
FAQ
How does the voice agent retrieve information from an external API?
OpenAI tool calling selects the get_cat_fact function during the conversation. The function requests data from the Cat Facts API, parses the JSON response, and sends the result back through the voice agent.
What authentication does the demonstration API require?
The Cat Facts API used in the tutorial requires no additional authentication. If another external API needs credentials, the tutorial says those keys can be stored in the environment configuration and must be authenticated according to that API's rules.
Why is ngrok needed when testing the application locally?
ngrok exposes the locally running webhook to the internet so Twilio can reach it. The Twilio phone-number configuration must use the current ngrok URL with /voice appended.
Source and freshness
- Source
- twilio.com
- Published
- Added to Yomu
Summaries are generated from the original by a language model. Check the original before relying on it.
Keep reading
Related 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.
The best engineering reads, once a week
One useful email. Unsubscribe anytime.