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.
The following TwiML example causes the caller to hear a pre-recorded audio file during the payment-card-number payment step.
<Prompt> Attributes
The table below lists <Prompt>'s attributes. Click on an attribute name to learn more about that attribute.
| Attribute Name | Allowed Values | Default Values |
|---|---|---|
|
required |
|
none |
|
optional |
Multiple values are allowed and must be space delimited. Example: |
none |
|
optional |
An integer from 1-10 |
none |
|
optional |
|
false |
|
optional |
Multiple values are allowed and must be space delimited. Example: |
none |
for
<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 |
cardType
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.
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.
attempt
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.
requireMatchingInputs
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.
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.
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.
errorType
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. |
Example <Prompt> usage
Use <Prompt>s to customize prompts for credit card payments
The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting a credit card payment:
Use <Prompt>s to customize prompts for ACH payments
The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting an ACH payment:
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
