TwiML™ Voice: <Prompt>
The TwiML's <Pay> Verb's <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.
Ask for a user's credit card number.
_11const VoiceResponse = require('twilio').twiml.VoiceResponse;
_11const response = new VoiceResponse();
_11const pay = response.pay();
_11const prompt = pay.prompt({
_11 for: 'payment-card-number'
_11prompt.say('Please enter your 16 digit Visa or Mastercard number.');
_11console.log(response.toString());
_10<?xml version="1.0" encoding="UTF-8"?>
_10 <Prompt for="payment-card-number">
_10 <Say>Please enter your 16 digit Visa or Mastercard number.</Say>
The following TwiML example causes the caller to hear a pre-recorded audio file during the payment-card-number
payment step.
Ask for a user's credit card number through a recorded MP3.
_11const VoiceResponse = require('twilio').twiml.VoiceResponse;
_11const response = new VoiceResponse();
_11const pay = response.pay();
_11const prompt = pay.prompt({
_11 for: 'payment-card-number'
_11prompt.play('https://myurl.com/twilio/twiml/audio/card_number.mp3');
_11console.log(response.toString());
_10<?xml version="1.0" encoding="UTF-8"?>
_10 <Prompt for="payment-card-number">
_10 <Play>https://myurl.com/twilio/twiml/audio/card_number.mp3</Play>
The table below lists <Prompt>'s attributes. Click on an attribute name to learn more about that attribute.
Attribute Name | Allowed Values | Default 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 -10 | none |
requireMatchingInputs
optional | | 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 |
<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 Step | Description |
---|
payment-card-number | The customer is asked for credit or debit card information |
expiration-date | The customer is asked for the expiration date for their payment card |
security-code | The customer is asked for the security code (CVV) for their payment card |
postal-code | The customer is asked for the postal code associated with the payment card |
bank-routing-number | The customer is asked for their bank's routing number |
bank-account-number | The customer is asked for their bank account number |
payment-processing | The 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.
_12const VoiceResponse = require('twilio').twiml.VoiceResponse;
_12const response = new VoiceResponse();
_12const pay = response.pay();
_12const prompt = pay.prompt({
_12 for: 'security-code',
_12prompt.say('Please enter security code for your Visa card. It’s the 3 digits located on the back of your card');
_12console.log(response.toString());
_10<?xml version="1.0" encoding="UTF-8"?>
_10 <Prompt for="security-code" cardType="visa">
_10 <Say> Please enter security code for your Visa card. It’s the 3 digits located on the back of your card </Say>
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.
_12const VoiceResponse = require('twilio').twiml.VoiceResponse;
_12const response = new VoiceResponse();
_12const pay = response.pay();
_12const prompt = pay.prompt({
_12 for: 'security-code',
_12prompt.say('Please enter security code for your American Express card. It’s the 4 digits located on the front of your card');
_12console.log(response.toString());
_10<?xml version="1.0" encoding="UTF-8"?>
_10 <Prompt for="security-code" cardType="amex">
_10 Please enter security code for your American Express card. It’s the 4 digits located on the front of your card
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.
_17const VoiceResponse = require('twilio').twiml.VoiceResponse;
_17const response = new VoiceResponse();
_17const pay = response.pay();
_17const prompt = pay.prompt({
_17 for: 'expiration-date',
_17prompt.say('Please enter your expiration date, two digits for the month and two digits for the year.');
_17const prompt2 = pay.prompt({
_17 for: 'expiration-date',
_17prompt2.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');
_17console.log(response.toString());
_11<?xml version="1.0" encoding="UTF-8"?>
_11 <Prompt for="expiration-date" attempt="1">
_11 <Say> Please enter your expiration date, two digits for the month and two digits for the year.</Say>
_11 <Prompt for="expiration-date" attempt="2 3">
_11 <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>
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.
errorType | Description |
---|
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-type | The 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-code | This 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-failed | The 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. |
The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting a credit card payment:
_89const VoiceResponse = require('twilio').twiml.VoiceResponse;
_89const response = new VoiceResponse();
_89const pay = response.pay({
_89 paymentMethod: 'credit-card',
_89 validCardTypes: 'visa mastercard amex'
_89const prompt = pay.prompt({
_89 for: 'payment-card-number'
_89prompt.say('Please enter your credit card number.');
_89const prompt2 = pay.prompt({
_89 for: 'payment-card-number',
_89prompt2.say('You didn\'t enter your credit card number. Please enter your credit card number.');
_89const prompt3 = pay.prompt({
_89 for: 'payment-card-number',
_89 errorType: 'invalid-card-number'
_89prompt3.say('You entered an invalid credit card number. Please try again.');
_89const prompt4 = pay.prompt({
_89 for: 'payment-card-number',
_89 errorType: 'invalid-card-type'
_89prompt4.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.');
_89const prompt5 = pay.prompt({
_89 for: 'expiration-date'
_89prompt5.say('Please enter your credit card\'s expiration date. Two digits for the month and two digits for the year.');
_89const prompt6 = pay.prompt({
_89 for: 'expiration-date',
_89prompt6.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.');
_89const prompt7 = pay.prompt({
_89 for: 'expiration-date',
_89 errorType: 'invalid-date'
_89prompt7.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.');
_89const prompt8 = pay.prompt({
_89 for: 'security-code',
_89 cardType: 'visa mastercard'
_89prompt8.say('Please enter your security code. It\'s the 3 digits located on the back of your card.');
_89const prompt9 = pay.prompt({
_89 for: 'security-code',
_89 errorType: 'timeout',
_89 cardType: 'visa mastercard'
_89prompt9.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.');
_89const prompt10 = pay.prompt({
_89 for: 'security-code',
_89 errorType: 'invalid-security-code',
_89 cardType: 'visa mastercard'
_89prompt10.say('That was an invalid security code. The security code must be 3 digits. Please try again.');
_89const prompt11 = pay.prompt({
_89 for: 'security-code',
_89prompt11.say('Please enter your security code. It\'s the 4 digits located on the front of your card.');
_89const prompt12 = pay.prompt({
_89 for: 'security-code',
_89 errorType: 'timeout',
_89prompt12.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.');
_89const prompt13 = pay.prompt({
_89 for: 'security-code',
_89 errorType: 'invalid-security-code',
_89prompt13.say('That was an invalid security code. The security code must be 4 digits. Please try again.');
_89const prompt14 = pay.prompt({
_89prompt14.say('Please enter your 5 digit billing zip code.');
_89const prompt15 = pay.prompt({
_89prompt15.say('You didn\'t enter your billing zip code. Please enter your 5 digit billing zip code.');
_89const prompt16 = pay.prompt({
_89 for: 'payment-processing'
_89prompt16.say('Thank you. Please wait while we process your payment.');
_89console.log(response.toString());
_59<?xml version="1.0" encoding="UTF-8"?>
_59 <Pay paymentMethod="credit-card" validCardTypes="visa mastercard amex">
_59 <!-- Prompts for credit card number -->
_59 <Prompt for="payment-card-number">
_59 <Say>Please enter your credit card number.</Say>
_59 <Prompt for="payment-card-number" errorType="timeout">
_59 <Say>You didn't enter your credit card number. Please enter your credit card number.</Say>
_59 <Prompt for="payment-card-number" errorType="invalid-card-number">
_59 <Say>You entered an invalid credit card number. Please try again.</Say>
_59 <Prompt for="payment-card-number" errorType="invalid-card-type">
_59 <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>
_59 <!-- Prompts for expiration date -->
_59 <Prompt for="expiration-date">
_59 <Say>Please enter your credit card's expiration date. Two digits for the month and two digits for the year.</Say>
_59 <Prompt for="expiration-date" errorType="timeout">
_59 <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>
_59 <Prompt for="expiration-date" errorType="invalid-date">
_59 <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>
_59 <!-- Prompts for three-digit security code -->
_59 <Prompt for="security-code" cardType="visa mastercard">
_59 <Say>Please enter your security code. It's the 3 digits located on the back of your card.</Say>
_59 <Prompt for="security-code" errorType="timeout" cardType="visa mastercard">
_59 <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>
_59 <Prompt for="security-code" errorType="invalid-security-code" cardType="visa mastercard">
_59 <Say>That was an invalid security code. The security code must be 3 digits. Please try again.</Say>
_59 <!-- Prompts for four-digit security code (American Express) -->
_59 <Prompt for="security-code" cardType="amex">
_59 <Say>Please enter your security code. It's the 4 digits located on the front of your card.</Say>
_59 <Prompt for="security-code" errorType="timeout" cardType="amex">
_59 <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>
_59 <Prompt for="security-code" errorType="invalid-security-code" cardType="amex">
_59 <Say>That was an invalid security code. The security code must be 4 digits. Please try again.</Say>
_59 <!-- Prompts for postal/zip code -->
_59 <Prompt for="postal-code">
_59 <Say>Please enter your 5 digit billing zip code.</Say>
_59 <Prompt for="postal-code" errorType="timeout">
_59 <Say>You didn't enter your billing zip code. Please enter your 5 digit billing zip code.</Say>
_59 <!-- Prompt after customer has entered all payment information -->
_59 <Prompt for="payment-processing">
_59 <Say>Thank you. Please wait while we process your payment.</Say>
The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting an ACH payment:
_38const VoiceResponse = require('twilio').twiml.VoiceResponse;
_38const response = new VoiceResponse();
_38const pay = response.pay({
_38 paymentMethod: 'ach-debit',
_38const prompt = pay.prompt({
_38 for: 'bank-routing-number'
_38prompt.say('Please enter your bank routing number.');
_38const prompt2 = pay.prompt({
_38 for: 'bank-routing-number',
_38prompt2.say('You didn\'t enter your routing number. Please enter your bank routing number.');
_38const prompt3 = pay.prompt({
_38 for: 'bank-routing-number',
_38 errorType: 'invalid-bank-routing-number'
_38prompt3.say('That was an invalid bank routing number. Please try again.');
_38const prompt4 = pay.prompt({
_38 for: 'bank-account-number'
_38prompt4.say('Please enter your bank account number.');
_38const prompt5 = pay.prompt({
_38 for: 'bank-account-number',
_38prompt5.say('You didn\'t enter your bank account number. Please enter your bank account number.');
_38const prompt6 = pay.prompt({
_38 for: 'payment-processing'
_38prompt6.say('Thank you. Please wait while we process your payment.');
_38console.log(response.toString());
_23<?xml version="1.0" encoding="UTF-8"?>
_23 <Pay timeout="5" maxAttempts="3" paymentMethod="ach-debit" language="en-US">
_23 <Prompt for="bank-routing-number">
_23 <Say>Please enter your bank routing number.</Say>
_23 <Prompt for="bank-routing-number" errorType="timeout">
_23 <Say>You didn't enter your routing number. Please enter your bank routing number.</Say>
_23 <Prompt for="bank-routing-number" errorType="invalid-bank-routing-number">
_23 <Say>That was an invalid bank routing number. Please try again.</Say>
_23 <Prompt for="bank-account-number">
_23 <Say>Please enter your bank account number.</Say>
_23 <Prompt for="bank-account-number" errorType="timeout">
_23 <Say>You didn't enter your bank account number. Please enter your bank account number.</Say>
_23 <Prompt for="payment-processing">
_23 <Say>Thank you. Please wait while we process your payment.</Say>