Custom code (TwiML)

Overview

A custom code extension hands the call to a web address of your own. We fetch that address, and whatever TwiML it returns is what the caller hears next. When your code is finished the call comes back and continues where you tell it to.

This is the escape hatch for developers. Everything a normal hotline needs is already a building block, so reach for this only when you need behavior the built-in extensions do not cover, such as answers that depend on live data from your own system.

In the sidebar it lives under Advanced, listed as Twimls. Everywhere a destination is picked, and on My Hotline, it is called Custom code.

How It Works

1. The caller reaches the custom code extension.
2. We send the call to your TwiML URL with a GET request. The call really moves there; we do not proxy it.
3. Your server answers with TwiML, and the caller hears whatever it says.
4. When your TwiML sends the call back to us, the Afterwards route decides where the caller goes next.

Your code is responsible for the caller from the moment we hand the call over. If your address is unreachable or returns something that is not valid TwiML, the call stops there.

Settings

• TwiML Name (required) — For your reference. On My Hotline it is just the extension's name.
• TwiML URL — The address we fetch. It must return TwiML: XML instructions such as <Play>, <Say> or <Dial>. On My Hotline this field is called Code URL. Use https://. The form does not force you to fill it in, but an extension with no URL has nothing to run.
• HTTP Method — GET. It is the only option.
• Active — Turn the extension off without deleting it. Callers routed to an extension that is off do not run your code.
• Phone System Reference → Extension ID — Only shown when your account has phone-system references turned on. See Settings.

Routing

Set it on the form, or from the extension's ⚙ settings on My Hotline. Point it at your main menu so callers land somewhere sensible when your code is done. Leave it empty and the call ends there.

What it costs

A custom code extension is a $20 a month add-on, one per extension, bought under Advanced options on the Plans & Add-ons page. The base plans include no advanced options, so buy one for each custom code extension you need. See Billing.

Writing the TwiML

Most standard Twilio TwiML verbs work. The platform also understands a handful of non-standard attributes, mainly for conferences and for interactive playback. They are all listed in Custom TwiML.

If you are building something that reads or changes the hotline itself rather than handling a single call, the Hotline API is usually the better tool.

Tips

• Keep it short. Hand the call back to the hotline as soon as your part is done, and let the built-in extensions do the rest.
• Test the URL in a browser first. If it does not return XML when you open it, it will not work on a call either.
• Use the test line while you develop, so real callers never hit a half-finished handler.
• Watch the call trace on Reports to see exactly where a call left the hotline and whether it came back.