Twilio Programmable Voice and TwiML

See also

Sources

1. 1
   Twilio enforces a hard 15-second limit on all call-related HTTP requests, which takes precedence over connection overrides.

   Webhook connection overrides · Webhook connection overrides > Override webhook connection properties · Checked 2026-10-14
2. 2
   Outbound calls are created by POST to https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json.

   Call resource · Call resource > Create a Call · Checked 2026-10-14
3. 3
   The CallStatus values defined by Twilio are queued, ringing, in-progress, completed, busy, failed, no-answer and canceled.

   TwiML for Programmable Voice · Twilio's request to your application > Request parameters > CallStatus values · Checked 2026-10-14
4. 4
   A call canceled via the REST API while still queued fires no status callbacks.

   TwiML for Programmable Voice · Twilio's request to your application > CallStatus values > canceled · Checked 2026-10-14
5. 5
   TwiML element and attribute names are case-sensitive, attribute names use camelCase, and a lowercase verb such as <say> causes an error.

   TwiML for Programmable Voice · TwiML for Programmable Voice > TwiML syntax rules · Checked 2026-10-14
6. 6
   A TwiML <Conference> holds at most 250 participants, and maxParticipants defaults to 250.

   TwiML Voice: <Conference> · TwiML Voice: <Conference> > Noun Attributes > maxParticipants · Checked 2026-10-14
7. 7
   Conference room names are scoped to the Twilio account, so callers on different accounts using the same name do not meet.

   TwiML Voice: <Conference> · TwiML Voice: <Conference> > introduction · Checked 2026-10-14
8. 8
   With <Connect><Stream> the stream is bidirectional and Twilio runs no subsequent TwiML until the server closes the WebSocket.

   TwiML Voice: <Stream> · TwiML Voice: <Stream> > introduction (Connect) · Checked 2026-10-14
9. 9
   If the webhook returns an audio MIME type instead of TwiML, Twilio plays the audio to the caller and then hangs up.

   TwiML for Programmable Voice · TwiML for Programmable Voice > Your response to Twilio (MIME types) · Checked 2026-10-14
10. 10
    A text/plain webhook response is executed as TwiML if it is valid TwiML; otherwise Twilio reads the text aloud and hangs up.

    TwiML for Programmable Voice · TwiML for Programmable Voice > Your response to Twilio (MIME types) · Checked 2026-10-14
11. 11
    A webhook response with content type text/xml, application/xml or text/html is interpreted by Twilio as TwiML.

    TwiML for Programmable Voice · TwiML for Programmable Voice > Your response to Twilio (MIME types) · Checked 2026-10-14
12. 12
    Creating a call requires To and From plus exactly one source of call instructions: Url, Twiml or ApplicationSid.

    Call resource · Call resource > Create a Call > Request body parameters · Checked 2026-10-14
13. 13
    The Create Call Timeout parameter (how long Twilio lets the call ring) defaults to 60 seconds with a maximum of 600 seconds.

    Call resource · Call resource > Create a Call > Request body parameters > Timeout · Checked 2026-10-14
14. 14
    Outbound call creation via POST to /Calls is limited by default to 1 call per second per account, raisable to 5 with an approved Business Profile, and excess requests are queued.

    Call resource · Call resource > Create a Call (CPS note) · Checked 2026-10-14
15. 15
    By default Twilio retries a webhook once (rc=1), and only after a TCP connect or TLS handshake failure (rp=ct).

    Webhook connection overrides · Webhook connection overrides > Retry policy · Checked 2026-10-14
16. 16
    When <Dial> has an action URL, Twilio requests it after the dial ends and any verbs after <Dial> in the same document are unreachable.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > action · Checked 2026-10-14
17. 17
    For a <Number> dial, callerId must be the To or From of Twilio's request, a Twilio number on the account, or a verified caller ID.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > callerId · Checked 2026-10-14
18. 18
    Without an action attribute, when <Dial> finishes and the caller is still on the line Twilio continues with the next verb in the document, and ends the call if none remains.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > action · Checked 2026-10-14
19. 19
    <Dial> accepts the nouns Number, Client, Sip, Conference, Queue, Application and WhatsApp, or a plain-text phone number.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> nouns · Checked 2026-10-14
20. 20
    On inbound SIP calls, <Dial> callerId cannot reuse the request's To or From number and must be a Twilio number or verified caller ID.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > callerId · Checked 2026-10-14
21. 21
    The <Dial> timeLimit attribute defaults to 14400 seconds (4 hours).

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > timeLimit · Checked 2026-10-14
22. 22
    The <Dial> timeout attribute defaults to 30 seconds and accepts values from 5 to 600 seconds.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > timeout · Checked 2026-10-14
23. 23
    DialCallStatus sent to the <Dial> action URL takes the values completed, answered, busy, no-answer, failed or canceled, with answered used for conferences.

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > action > DialCallStatus · Checked 2026-10-14
24. 24
    The Direction request parameter is inbound for inbound calls, outbound-api for calls created via the REST API, and outbound-dial for calls created by <Dial>.

    TwiML for Programmable Voice · Twilio's request to your application > Request parameters > Direction · Checked 2026-10-14
25. 25
    When a TwiML document runs out of verbs and control has not passed elsewhere, the call is ended.inferred

    TwiML Voice: <Dial> · TwiML Voice: <Dial> > <Dial> attributes > action (behaviour without action) · Checked 2026-10-14
26. 26
    <Enqueue> creates the named queue on demand if it does not exist, and a queue's default maximum size is 1000 calls.

    TwiML Voice: <Enqueue> · TwiML Voice: <Enqueue> > Nouns; Hints and Advanced Uses · Checked 2026-10-14
27. 27
    The <Enqueue> action URL receives a QueueResult such as bridged, hangup, leave, redirected, queue-full or error describing how the call left the queue.

    TwiML Voice: <Enqueue> · TwiML Voice: <Enqueue> > action > Request Parameters > QueueResult values · Checked 2026-10-14
28. 28
    TwiML returned by an <Enqueue> waitUrl may use only Play, Say, Pause, Hangup, Redirect, Leave and Gather, and is re-requested when it runs out.

    TwiML Voice: <Enqueue> · TwiML Voice: <Enqueue> > Verb Attributes > waitUrl · Checked 2026-10-14
29. 29
    Twilio error 11200 (HTTP retrieval failure) means Twilio could not get a successful response from the webhook URL, such as a non-2xx status, connection failure or timeout.

    11200: HTTP retrieval failure · 11200: HTTP retrieval failure > Description; Likely causes · Checked 2026-10-14
30. 30
    Twilio error 12100 (Document parse failure) is raised for invalid TwiML XML, such as whitespace before the XML declaration, a missing <Response> root, unclosed elements or unescaped &, < or >.

    12100: Document parse failure · 12100: Document parse failure > Likely causes; Possible solutions · Checked 2026-10-14
31. 31
    Twilio sends Digits for DTMF input and SpeechResult plus an optional Confidence score (0.0 to 1.0) for speech input to the <Gather> action URL; Confidence is not guaranteed to be present.

    TwiML Voice: <Gather> · TwiML Voice: <Gather> > action (request parameters) · Checked 2026-10-14
32. 32
    <Gather> defaults to input dtmf, a 5-second timeout, finishOnKey # and unlimited numDigits.

    TwiML Voice: <Gather> · TwiML Voice: <Gather> > <Gather> attributes (table) · Checked 2026-10-14
33. 33
    Only <Say>, <Play> and <Pause> may be nested inside <Gather>.

    TwiML Voice: <Gather> · TwiML Voice: <Gather> > Nest other verbs · Checked 2026-10-14
34. 34
    If the caller gives no digits or speech, Twilio continues with the next verb after <Gather> instead of requesting the action URL, unless actionOnEmptyResult is true.

    TwiML Voice: <Gather> · TwiML Voice: <Gather> > actionOnEmptyResult; Manage timeouts · Checked 2026-10-14
35. 35
    Inbound calls and calls placed with <Dial> are not subject to the Calls API CPS limit.

    Call resource · Call resource > Create a Call (CPS note) · Checked 2026-10-14
36. 36
    Connection overrides are appended to the webhook URL as a # fragment, and the fragment must be omitted when validating the Twilio signature.

    Webhook connection overrides · Webhook connection overrides > introduction · Checked 2026-10-14
37. 37
    Twilio's default webhook connect timeout is 5000 ms and default read timeout is 15000 ms, adjustable with the ct and rt connection overrides.

    Webhook connection overrides · Webhook connection overrides > Override webhook connection properties (table) · Checked 2026-10-14
38. 38
    Twilio cannot cache TwiML fetched by POST; static TwiML must be served via GET for Twilio to cache it.

    TwiML for Programmable Voice · TwiML for Programmable Voice > Twilio's request to your application (caching note) · Checked 2026-10-14
39. 39
    <Record> defaults to maxLength 3600 seconds, a 5-second silence timeout, playBeep true, trim-silence, and any key ending the recording.

    TwiML Voice: <Record> · TwiML Voice: <Record> > Verb Attributes (table) · Checked 2026-10-14
40. 40
    Without an action URL, <Record> re-requests the current document URL after recording, which can loop the call if not handled.

    TwiML Voice: <Record> · TwiML Voice: <Record> > Verb Attributes > action · Checked 2026-10-14
41. 41
    <Record> transcription supports only American English and only recordings longer than 2 seconds and shorter than 120 seconds.

    TwiML Voice: <Record> · TwiML Voice: <Record> > Verb Attributes > transcribe · Checked 2026-10-14
42. 42
    <Redirect> hands control to the TwiML at another URL (POST by default), and all verbs after it in the document are ignored.

    TwiML Voice: <Redirect> · TwiML Voice: <Redirect> > introduction; Verb Attributes > method · Checked 2026-10-14
43. 43
    Twilio always sends CallSid, AccountSid, From, To, CallStatus, ApiVersion and Direction in its voice request to the application.

    TwiML for Programmable Voice · Twilio's request to your application > Request parameters · Checked 2026-10-14
44. 44
    Every TwiML verb must be nested inside the root <Response> element; any other document structure is invalid.

    TwiML for Programmable Voice · TwiML for Programmable Voice > TwiML elements (Response) · Checked 2026-10-14
45. 45
    The voice used by <Say> without a voice attribute comes from the account-level Text-to-Speech settings in the Console; a voice attribute overrides it.

    TwiML Voice: <Say> · TwiML Voice: <Say> > <Say> attributes > voice · Checked 2026-10-14
46. 46
    Twilio will not connect to an HTTPS webhook URL that presents a self-signed certificate.

    Secure webhooks · Secure webhooks > Encrypt traffic with HTTPS and TLS · Checked 2026-10-14
47. 47
    Twilio signs each webhook request with an HMAC-SHA1 signature keyed by the account auth token and sends it in the X-Twilio-Signature header.

    Secure webhooks · Secure webhooks > Authenticate with signatures · Checked 2026-10-14
48. 48
    For form-encoded POST webhooks, the signed string is the full configured URL (including query string) followed by the POST parameters sorted alphabetically by name.

    Secure webhooks · Secure webhooks > Understand parameters in signature validation > Query parameters; Form parameters · Checked 2026-10-14
49. 49
    <Start><Stream> forks call audio one way to a WebSocket and Twilio continues with the next TwiML instruction while the stream runs.

    TwiML Voice: <Stream> · TwiML Voice: <Stream> > introduction · Checked 2026-10-14
50. 50
    Twilio expects a status callback endpoint to answer with 204 No Content or with 200 OK and an empty <Response/> as text/xml; other responses raise Debugger warnings.

    TwiML for Programmable Voice · TwiML for Programmable Voice > Your response to Twilio (status callbacks) · Checked 2026-10-14
51. 51
    If a StatusCallback URL is set without StatusCallbackEvent, Twilio sends only the completed event.

    Call resource · Call resource > Update a Call > Request body parameters > StatusCallback · Checked 2026-10-14
52. 52
    The call StatusCallbackEvent values are initiated, ringing, answered and completed.

    Call resource · Call resource > StatusCallbackEvent · Checked 2026-10-14
53. 53
    The <Stream> url must use wss and may not carry query-string parameters; custom values go in <Parameter> elements instead.

    TwiML Voice: <Stream> · TwiML Voice: <Stream> > Attributes > url; Custom parameters · Checked 2026-10-14
54. 54
    Twilio executes TwiML instructions from top to bottom in order, and only one TwiML document runs at a time for a call.

    TwiML for Programmable Voice · TwiML for Programmable Voice > How TwiML works (execution order) · Checked 2026-10-14
55. 55
    The Twiml parameter on the Call resource accepts at most 4000 characters.

    Call resource · Call resource > Create a Call > Request body parameters > Twiml · Checked 2026-10-14
56. 56
    TwiML is an XML document made of Twilio-defined tags that tells Twilio how to handle an incoming call.

    TwiML for Programmable Voice · TwiML for Programmable Voice > introduction · Checked 2026-10-14
57. 57
    An in-progress call can be redirected by POSTing a new Url or inline Twiml to the Update a Call endpoint; Url and Twiml are mutually exclusive.

    Call resource · Call resource > Update a Call > Request body parameters · Checked 2026-10-14
58. 58
    The Update a Call Status parameter accepts canceled or completed to end a call.

    Call resource · Call resource > Update a Call > Request body parameters > Status · Checked 2026-10-14
59. 59
    The TwiML voice verbs listed by Twilio are Say, Play, Dial, Record, Gather, Hangup, Enqueue, Leave, Pause, Redirect, Refer and Reject.

    TwiML for Programmable Voice · TwiML for Programmable Voice > TwiML verbs · Checked 2026-10-14
60. 60
    When a call reaches a Twilio number, Twilio requests the URL configured for that number using either HTTP GET or POST.

    TwiML for Programmable Voice · TwiML for Programmable Voice > How TwiML works (request on incoming call) · Checked 2026-10-14

Documents

Cite this page

WarmTransfer. (2026, October 14). Twilio Programmable Voice and TwiML. WarmTransfer. https://warmtransfer.net/knowledge/twilio-programmable-voice

@misc{warmtransfer-twilio-programmable-voice,
  title  = {Twilio Programmable Voice and TwiML},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/twilio-programmable-voice},
  note   = {Verified 2026-10-14}
}