Skip to contentSkip to navigationSkip to topbar
On this page

TwiML™ Voice: <Prompt>


The <Prompt> noun allows you to customize the default prompts used by <Pay>.

By default, when Twilio executes <Pay> TwiML instructions (without <Prompt>), the caller will hear default prompts for each step of the payment process. You can modify what the caller hears for a given payment step by nesting <Prompt> within <Pay>'s opening and closing tags.

You can customize prompts with text-to-speech or a pre-recorded audio file. For text-to-speech, you must nest <Say> TwiML within <Prompt>'s opening and closing tags. In order to play a pre-recorded audio file, you must nest <Play> TwiML within <Prompt>'s opening and closing tags.

There are seven payment steps in the <Pay> process, which are listed below in the for attribute section. You need separate <Prompt>s for each payment step prompt that you wish to customize.

The TwiML example below shows how to use <Pay>, <Prompt>, and <Say> to customize the prompt for the payment-card-number step (i.e. when the caller is prompted to enter their payment card number) with text-to-speech.

Prompt for card numberLink to code sample: Prompt for card number
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const pay = response.pay();
6
const prompt = pay.prompt({
7
for: 'payment-card-number'
8
});
9
prompt.say('Please enter your 16 digit Visa or Mastercard number.');
10
11
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay>
4
<Prompt for="payment-card-number">
5
<Say>Please enter your 16 digit Visa or Mastercard number.</Say>
6
</Prompt>
7
</Pay>
8
</Response>

The following TwiML example causes the caller to hear a pre-recorded audio file during the payment-card-number payment step.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const pay = response.pay();
6
const prompt = pay.prompt({
7
for: 'payment-card-number'
8
});
9
prompt.play('https://myurl.com/twilio/twiml/audio/card_number.mp3');
10
11
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay>
4
<Prompt for="payment-card-number">
5
<Play>https://myurl.com/twilio/twiml/audio/card_number.mp3</Play>
6
</Prompt>
7
</Pay>
8
</Response>

Attributes

attributes page anchor

The table below lists <Prompt>'s attributes. Click on an attribute name to learn more about that attribute.

Attribute NameAllowed ValuesDefault Values
for

required
  • payment-card-number
  • expiration-date
  • security-code
  • postal-code
  • bank-routing-number
  • bank-account-number
  • payment-processing
none
cardType

optional
  • visa
  • mastercard
  • amex
  • maestro
  • discover
  • optima
  • jcb
  • diners-club
  • enroute

Multiple values are allowed and must be space delimited.

Example:
visa amex mastercard
none
attempt

optional
An integer from 1-10none
requireMatchingInputs

optional
  • true
  • false
false
errorType

optional
  • timeout
  • invalid-card-number
  • invalid-card-type
  • invalid-date
  • invalid-security-code
  • invalid-bank-routing-number
  • invalid-bank-account-number
  • input-matching-failed

Multiple values are allowed and must be space delimited.

Example:
timeout invalid-bank-account-number invalid-date
none

for

for page anchor

<Prompt>'s for attribute specifies which payment step's prompt you wish to customize.

The following table lists the possible values of the for attribute, along with a description of each payment step.

Possible Value / Payment StepDescription
payment-card-numberThe customer is asked for credit or debit card information
expiration-dateThe customer is asked for the expiration date for their payment card
security-codeThe customer is asked for the security code (CVV) for their payment card
postal-codeThe customer is asked for the postal code associated with the payment card
bank-routing-numberThe customer is asked for their bank's routing number
bank-account-numberThe customer is asked for their bank account number
payment-processingThe payment is processing

The cardType attribute allows you to customize a payment step's prompt for specific payment card types.

This is useful to customize the prompt when asking for a security code, as different card types have security codes of different lengths.

The following TwiML example customizes the prompt for the security-code payment step if the credit card number provided by the caller was a Visa card.

Prompt for a Visa security code (3 digits)Link to code sample: Prompt for a Visa security code (3 digits)
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const pay = response.pay();
6
const prompt = pay.prompt({
7
for: 'security-code',
8
cardType: 'visa'
9
});
10
prompt.say('Please enter security code for your Visa card. It’s the 3 digits located on the back of your card');
11
12
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay>
4
<Prompt for="security-code" cardType="visa">
5
<Say> Please enter security code for your Visa card. It’s the 3 digits located on the back of your card </Say>
6
</Prompt>
7
</Pay>
8
</Response>

The following TwiML example customizes the prompt for the security-code payment step if the credit card number provided by the caller was an American Express card.

Prompt for an American Express security code (4 digits)Link to code sample: Prompt for an American Express security code (4 digits)
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const pay = response.pay();
6
const prompt = pay.prompt({
7
for: 'security-code',
8
cardType: 'amex'
9
});
10
prompt.say('Please enter security code for your American Express card. It’s the 4 digits located on the front of your card');
11
12
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay>
4
<Prompt for="security-code" cardType="amex">
5
<Say>
6
Please enter security code for your American Express card. It’s the 4 digits located on the front of your card
7
</Say>
8
</Prompt>
9
</Pay>
10
</Response>

If a customer fails to input a payment step's information, the customer will be prompted again to enter that step's information. You can customize what the customer hears for each attempt to gather a payment step's information using the attempt attribute.

This can be used to provide more helpful prompts if a customer fails to enter their information after an initial prompt for a given payment step.

The TwiML example below would cause the customer to hear, "Please enter your expiration date, two digits for the month and two digits for the year." during the expiration-date step. If the caller fails to enter an expiration date, the next <Prompt> will execute and the caller will hear, "Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2." Since the second <Prompt>'s attempt value is 2 3, the caller would hear this longer prompt during a third attempt if necessary.

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
4
const response = new VoiceResponse();
5
const pay = response.pay();
6
const prompt = pay.prompt({
7
for: 'expiration-date',
8
attempt: '1'
9
});
10
prompt.say('Please enter your expiration date, two digits for the month and two digits for the year.');
11
const prompt2 = pay.prompt({
12
for: 'expiration-date',
13
attempt: '2 3'
14
});
15
prompt2.say('Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2');
16
17
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay>
4
<Prompt for="expiration-date" attempt="1">
5
<Say> Please enter your expiration date, two digits for the month and two digits for the year.</Say>
6
</Prompt>
7
<Prompt for="expiration-date" attempt="2 3">
8
<Say> Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2 </Say>
9
</Prompt>
10
</Pay>
11
</Response>

The requireMatchingInputs attribute allows you to prompt a customer to re-input their bank account number or bank routing number and tell Twilio to check whether or not the two inputs match.

(warning)

Warning

The requireMatchingInputs attribute is only available for use for ACH payments/tokenizations at this time.

Therefore, you can only use requireMatchingInputs with for attributes of bank-account-number or bank-routing-number.

If the two inputs do not match, Twilio will restart that payment step's prompts. The customer will once again hear the first prompt to enter their information and the second prompt to re-enter the information.

Require caller to enter bank account information twiceLink to code sample: Require caller to enter bank account information twice
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const pay = response.pay({
5
paymentMethod: 'ach-debit',
6
chargeAmount: '13.22'
7
});
8
const prompt = pay.prompt({
9
for: 'bank-account-number'
10
});
11
prompt.say('Thanks for using our service. Please enter your bank account number.');
12
const prompt2 = pay.prompt({
13
for: 'bank-account-number',
14
requireMatchingInputs: true
15
});
16
prompt2.say('Thank you. Please enter your bank account number again.');
17
18
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay paymentMethod="ach-debit" chargeAmount="13.22">
4
<Prompt for="bank-account-number">
5
<Say>Thanks for using our service. Please enter your bank account number.</Say>
6
</Prompt>
7
<Prompt for="bank-account-number" requireMatchingInputs="true">
8
<Say>Thank you. Please enter your bank account number again.</Say>
9
</Prompt>
10
</Pay>
11
</Response>

You should use two <Prompt>s with the same for attribute. The second <Prompt> should have requireMatchingInputs set to true. This will give the caller two different prompts: one to enter a piece of information once, and one that tells the caller to re-enter the information for verification purposes.

Optionally, you can use a third <Prompt> (with the same for attribute) with the errorType attribute set to input-matching-failed to customize the prompt the caller hears if their inputs did not match. The TwiML example below illustrates this behavior.

Use with requireMatchingInputs and errorTypeLink to code sample: Use with requireMatchingInputs and errorType
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const pay = response.pay({
5
paymentMethod: 'ach-debit',
6
chargeAmount: '13.22'
7
});
8
const prompt = pay.prompt({
9
for: 'bank-account-number'
10
});
11
prompt.say('Thanks for using our service. Please enter your bank account number.');
12
const prompt2 = pay.prompt({
13
for: 'bank-account-number',
14
requireMatchingInputs: true
15
});
16
prompt2.say('Thank you. Please enter your bank account number again.');
17
const prompt3 = pay.prompt({
18
for: 'bank-account-number',
19
errorType: 'input-matching-failed'
20
});
21
prompt3.say('Sorry, your two bank account number inputs did not match. Please enter your bank account number again. We will then ask a second time again.');
22
23
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay paymentMethod="ach-debit" chargeAmount="13.22">
4
<Prompt for="bank-account-number">
5
<Say>Thanks for using our service. Please enter your bank account number.</Say>
6
</Prompt>
7
<Prompt for="bank-account-number" requireMatchingInputs="true">
8
<Say>Thank you. Please enter your bank account number again.</Say>
9
</Prompt>
10
<Prompt for="bank-account-number" errorType="input-matching-failed">
11
<Say>Sorry, your two bank account number inputs did not match. Please enter your bank account number again. We will then ask a second time again.</Say>
12
</Prompt>
13
</Pay>
14
</Response>

The errorType attribute allows you to customize the prompt that the caller hears if their input for a given payment step was invalid.

The following are possible values of errorType and descriptions of the cause of the error.

errorTypeDescription
timeout<Pay> received a timeout when executing a payment step
invalid-card-number<Pay> didn't receive the appropriate number of digits for either credit card number, expiration date, security code or zip code. Or card number entered didn't pass the validation. This reason can be used to apply further customization on the message to play such as informing payee/caller that the incorrect number of digits were entered.
invalid-card-typeThe card number entered didn't match the accepted card types. For example, if only visa or mastercard are accepted and payee enters amex, InvalidReason parameter will contain this value.
invalid-date<Pay> didn't receive the correct number of digits for the date.
invalid-security-codeThis reason is generated when the payee entered an invalid security code. For example, if credit card number is amex and user entered 3 digits for the security code.
invalid-postal-code<Pay> didn't receive the correct number of digits for the postal/zip code.
invalid-bank-routing-number<Pay> either didn't receive the appropriate number of digits for the routing number or the routing number provided failed the validation performed by <Pay>.
invalid-bank-account-number<Pay> didn't receive the minimum number of digits required for the bank account number.
input-matching-failedThe first and second inputs by the customer did not match. Only will be returned when requireMatchingInputs is set to true. Only available for ACH payments/tokenizations at this time.

Customize prompts for credit card payments

customize-prompts-for-credit-card-payments page anchor

The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting a credit card payment:

A full example for a credit card transactionLink to code sample: A full example for a credit card transaction
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const pay = response.pay({
5
paymentMethod: 'credit-card',
6
validCardTypes: 'visa mastercard amex'
7
});
8
const prompt = pay.prompt({
9
for: 'payment-card-number'
10
});
11
prompt.say('Please enter your credit card number.');
12
const prompt2 = pay.prompt({
13
for: 'payment-card-number',
14
errorType: 'timeout'
15
});
16
prompt2.say('You didn\'t enter your credit card number. Please enter your credit card number.');
17
const prompt3 = pay.prompt({
18
for: 'payment-card-number',
19
errorType: 'invalid-card-number'
20
});
21
prompt3.say('You entered an invalid credit card number. Please try again.');
22
const prompt4 = pay.prompt({
23
for: 'payment-card-number',
24
errorType: 'invalid-card-type'
25
});
26
prompt4.say('The card number you entered isn\'t from one of our accepted credit card issuers. Please enter a Visa, MasterCard, or American Express credit card number.');
27
const prompt5 = pay.prompt({
28
for: 'expiration-date'
29
});
30
prompt5.say('Please enter your credit card\'s expiration date. Two digits for the month and two digits for the year.');
31
const prompt6 = pay.prompt({
32
for: 'expiration-date',
33
errorType: 'timeout'
34
});
35
prompt6.say('Sorry. You didn\'t enter an expiration date. Please enter your card\'s expiration date. Two digits for the month and two digits for the year.');
36
const prompt7 = pay.prompt({
37
for: 'expiration-date',
38
errorType: 'invalid-date'
39
});
40
prompt7.say('The date you entered was incorrect or is in the past. Please enter the expiration date. Two digits for the month and two digits for the year. For example, to enter July twenty twenty two, enter 0 7 2 2.');
41
const prompt8 = pay.prompt({
42
for: 'security-code',
43
cardType: 'visa mastercard'
44
});
45
prompt8.say('Please enter your security code. It\'s the 3 digits located on the back of your card.');
46
const prompt9 = pay.prompt({
47
for: 'security-code',
48
errorType: 'timeout',
49
cardType: 'visa mastercard'
50
});
51
prompt9.say('You didn\'t enter your credit card security code. Please enter your security code. It\'s the 3 digits located on the back of your card.');
52
const prompt10 = pay.prompt({
53
for: 'security-code',
54
errorType: 'invalid-security-code',
55
cardType: 'visa mastercard'
56
});
57
prompt10.say('That was an invalid security code. The security code must be 3 digits. Please try again.');
58
const prompt11 = pay.prompt({
59
for: 'security-code',
60
cardType: 'amex'
61
});
62
prompt11.say('Please enter your security code. It\'s the 4 digits located on the front of your card.');
63
const prompt12 = pay.prompt({
64
for: 'security-code',
65
errorType: 'timeout',
66
cardType: 'amex'
67
});
68
prompt12.say('You didn\'t enter your credit card security code. Please enter your security code. It\'s the 4 digits located on the front of your card.');
69
const prompt13 = pay.prompt({
70
for: 'security-code',
71
errorType: 'invalid-security-code',
72
cardType: 'amex'
73
});
74
prompt13.say('That was an invalid security code. The security code must be 4 digits. Please try again.');
75
const prompt14 = pay.prompt({
76
for: 'postal-code'
77
});
78
prompt14.say('Please enter your 5 digit billing zip code.');
79
const prompt15 = pay.prompt({
80
for: 'postal-code',
81
errorType: 'timeout'
82
});
83
prompt15.say('You didn\'t enter your billing zip code. Please enter your 5 digit billing zip code.');
84
const prompt16 = pay.prompt({
85
for: 'payment-processing'
86
});
87
prompt16.say('Thank you. Please wait while we process your payment.');
88
89
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay paymentMethod="credit-card" validCardTypes="visa mastercard amex">
4
<!-- Prompts for credit card number -->
5
<Prompt for="payment-card-number">
6
<Say>Please enter your credit card number.</Say>
7
</Prompt>
8
<Prompt for="payment-card-number" errorType="timeout">
9
<Say>You didn't enter your credit card number. Please enter your credit card number.</Say>
10
</Prompt>
11
<Prompt for="payment-card-number" errorType="invalid-card-number">
12
<Say>You entered an invalid credit card number. Please try again.</Say>
13
</Prompt>
14
<Prompt for="payment-card-number" errorType="invalid-card-type">
15
<Say>The card number you entered isn't from one of our accepted credit card issuers. Please enter a Visa, MasterCard, or American Express credit card number.</Say>
16
</Prompt>
17
<!-- Prompts for expiration date -->
18
<Prompt for="expiration-date">
19
<Say>Please enter your credit card's expiration date. Two digits for the month and two digits for the year.</Say>
20
</Prompt>
21
<Prompt for="expiration-date" errorType="timeout">
22
<Say>Sorry. You didn't enter an expiration date. Please enter your card's expiration date. Two digits for the month and two digits for the year.</Say>
23
</Prompt>
24
<Prompt for="expiration-date" errorType="invalid-date">
25
<Say>The date you entered was incorrect or is in the past. Please enter the expiration date. Two digits for the month and two digits for the year. For example, to enter July twenty twenty two, enter 0 7 2 2.</Say>
26
</Prompt>
27
<!-- Prompts for three-digit security code -->
28
<Prompt for="security-code" cardType="visa mastercard">
29
<Say>Please enter your security code. It's the 3 digits located on the back of your card.</Say>
30
</Prompt>
31
<Prompt for="security-code" errorType="timeout" cardType="visa mastercard">
32
<Say>You didn't enter your credit card security code. Please enter your security code. It's the 3 digits located on the back of your card.</Say>
33
</Prompt>
34
<Prompt for="security-code" errorType="invalid-security-code" cardType="visa mastercard">
35
<Say>That was an invalid security code. The security code must be 3 digits. Please try again.</Say>
36
</Prompt>
37
<!-- Prompts for four-digit security code (American Express) -->
38
<Prompt for="security-code" cardType="amex">
39
<Say>Please enter your security code. It's the 4 digits located on the front of your card.</Say>
40
</Prompt>
41
<Prompt for="security-code" errorType="timeout" cardType="amex">
42
<Say>You didn't enter your credit card security code. Please enter your security code. It's the 4 digits located on the front of your card.</Say>
43
</Prompt>
44
<Prompt for="security-code" errorType="invalid-security-code" cardType="amex">
45
<Say>That was an invalid security code. The security code must be 4 digits. Please try again.</Say>
46
</Prompt>
47
<!-- Prompts for postal/zip code -->
48
<Prompt for="postal-code">
49
<Say>Please enter your 5 digit billing zip code.</Say>
50
</Prompt>
51
<Prompt for="postal-code" errorType="timeout">
52
<Say>You didn't enter your billing zip code. Please enter your 5 digit billing zip code.</Say>
53
</Prompt>
54
<!-- Prompt after customer has entered all payment information -->
55
<Prompt for="payment-processing">
56
<Say>Thank you. Please wait while we process your payment.</Say>
57
</Prompt>
58
</Pay>
59
</Response>

Customize prompts for ACH payments

customize-prompts-for-ach-payments page anchor

The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting an ACH payment:

A full example for an ACH/debit transactionLink to code sample: A full example for an ACH/debit transaction
1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2
3
const response = new VoiceResponse();
4
const pay = response.pay({
5
timeout: '5',
6
maxAttempts: '3',
7
paymentMethod: 'ach-debit',
8
language: 'en-US'
9
});
10
const prompt = pay.prompt({
11
for: 'bank-routing-number'
12
});
13
prompt.say('Please enter your bank routing number.');
14
const prompt2 = pay.prompt({
15
for: 'bank-routing-number',
16
errorType: 'timeout'
17
});
18
prompt2.say('You didn\'t enter your routing number. Please enter your bank routing number.');
19
const prompt3 = pay.prompt({
20
for: 'bank-routing-number',
21
errorType: 'invalid-bank-routing-number'
22
});
23
prompt3.say('That was an invalid bank routing number. Please try again.');
24
const prompt4 = pay.prompt({
25
for: 'bank-account-number'
26
});
27
prompt4.say('Please enter your bank account number.');
28
const prompt5 = pay.prompt({
29
for: 'bank-account-number',
30
errorType: 'timeout'
31
});
32
prompt5.say('You didn\'t enter your bank account number. Please enter your bank account number.');
33
const prompt6 = pay.prompt({
34
for: 'payment-processing'
35
});
36
prompt6.say('Thank you. Please wait while we process your payment.');
37
38
console.log(response.toString());

Output

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Pay timeout="5" maxAttempts="3" paymentMethod="ach-debit" language="en-US">
4
<Prompt for="bank-routing-number">
5
<Say>Please enter your bank routing number.</Say>
6
</Prompt>
7
<Prompt for="bank-routing-number" errorType="timeout">
8
<Say>You didn't enter your routing number. Please enter your bank routing number.</Say>
9
</Prompt>
10
<Prompt for="bank-routing-number" errorType="invalid-bank-routing-number">
11
<Say>That was an invalid bank routing number. Please try again.</Say>
12
</Prompt>
13
<Prompt for="bank-account-number">
14
<Say>Please enter your bank account number.</Say>
15
</Prompt>
16
<Prompt for="bank-account-number" errorType="timeout">
17
<Say>You didn't enter your bank account number. Please enter your bank account number.</Say>
18
</Prompt>
19
<Prompt for="payment-processing">
20
<Say>Thank you. Please wait while we process your payment.</Say>
21
</Prompt>
22
</Pay>
23
</Response>

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.