Oracle Cloud Infrastructure Documentation

Text-Only Channels

Like the Facebook channel, you configure text-only channels using artifacts generated by both the messaging platform and Digital Assistant. For text-only channels like Twilio/SMS, however, you also need to update the dialog flow definition to allow your bot’s responses to render appropriately when buttons aren’t supported. There are two aspects of this:
  • Showing or hiding content for text-only channels. For Common Response components, this means that you need to update the metadata property to include (or where applicable, exclude) Twilio for any response item, card, or global action:
    responseItems:
- type: "text"
  text: "This text text displays on Twilio"
  visible:
    channels:
      include: "twilio"             
- type: "text"
  text: "This text is not shown in Twilio or Facebook!"
  visible:
    channels:
      exclude: "facebook, twilio"
  actions:
  - label: "This action is only shown on web channel."
    type: "postback"
    payload:
      action: "someAction"
    visible:
      channels:
        include: "web"

  • Configuring auto-numbering.

Twilio/SMS

You’ll need the following to run your digital assistant on Twilio/SMS:
  • Twilio Credentials (you provide these to the Digital Assistant channel configuration):

    • A Twilio phone number.

    • Account SID

    • Auth Token

  • From Digital Assistant (and provided to Twilio):

    • The webhook URL (generated when you create the Twilio channel).

Note

When you create a channel for a digital assistant in Twilio, keep in mind that "exit", which users may use to navigate away from skills in your digital assistant, is also a default keyword in Twilio. So, if a user enters "exit" in a Twilio channel, the Twilio conversation will be ended and the digital assistant will not receive that input. Users that want "exit" to work with the digital assistant would need to contact Twilio and have "exit" removed as a keyword from their acccount.

Step 1: Get an SMS-Enabled Twilo Number

To generate the Twilio Number, Account SID, Auth Token needed for the Twilio channel configuration, you first need to create a Twilio account (if you don’t have one already).After you’ve verified your identity:

  1. Click All Products and Services (This is an image of the All Products and Services icon.) in the left navbar.

  2. Pin both Programmable SMS (This is an image of the Programmable SMS icon.) and Phone Numbers (This is an image of the Phone Numbers icon.) to your dashboard.
    Description of twilio_products.png follows

  3. Click Phone Numbers (now pinned to the left navbar) and then click Get Started.

  4. Choose Get a Number or Buy a Number. In either case, be sure to select the SMS capability. . Keep this number close at hand, because you’ll use this number to configure the Twilio channel back in Digital Assistant.

  5. Click Console Dashboard (This is an image of the dashboard icon.) in the left navbar and note the Account SID and Auth Token (accessed by clicking View). Along with the Twilio number, you need these credentials to configure the Twilio Channel.

Step 2: Link Your Bot to the Twilio Number

With the Twilio credentials close at hand:

  1. Back in Digital Assistant, click Channels in the left menu and then choose Users.

  2. Click Add Channel.

  3. In the Create Channel dialog:

    1. Enter a name and then choose Twilio SMS from the Channel Type menu.

    2. Enter the Account SID, Auth Token and Twilio Number.

    3. Switch on Channel Enabled.

    4. Click icon for the Route To ... dropdown and select the digital assistant or skill that you want to associate with the channel.

  4. Click Create. Note the Webhook URL. You’ll need this for one last stop to the Twilio Console.

  5. In the Twilio Console, click Phone Numbers (This is an image of the Phone Numbers icon.) then click Active Numbers.

  6. Click the Twilio number in the Active Numbers page.

  7. In the Messaging Section of the Configure page, paste the Webhook URL into the A Message Comes In field.

  8. Click Save.

Testing Tips

You can test the Twilio Channel using your own phone by sending messages to the Digital Assistant Twilio account number.

Supported Capabilities

Twilio channels in Digital Assistant support the following capabilities:

  • text
  • images (as URL)
  • files (as URL)
  • emojis (as URL)
  • links
  • postbacks (as URL)
  • custom properties (partial)
  • carousel components (partial)
  • list components (partial)
Note

If you are targeting your skill to multiple channels with different formatting capabilities, you can use HTML markup in your messages. For text-based channels, this markup will be stripped from the message when the message is transmitted to the channel. See Rich Text Formatting in Channels.

Message Constraints

Twilio channels in Digital Assistant have the following message constraints:

  • Text Messages
    • Maximum length of text message: 1600 characters. If the length exceeds 1600, the text is split over multiple messages.
    • Types of text actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
  • Horizontal Cards
    • Supported?: No, but near equivalent functionality is achieved by converting some action types to text.
    • Types of card actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
    • Types of card list actions allowed: Postback, Call,URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
  • Vertical Cards
    • Supported: No, but near equivalent functionality is achieved by converting some action types to text.
    • Types of card actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
    • Types of card list actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
  • Attachment Messages
    • Supported?: Yes, if MMS is enabled.
    • Types of attachment actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.
  • Action Buttons
    • Supported? No, but near equivalent functionality is achieved by converting some action types to text.
    • Types of global actions allowed: Postback, Call, URL. These action types are converted to text. For postback actions, the label serves as a keyword that can be used to trigger the postback.

Twilio Channel Extensions

For Twilio channels, you can extend the functionality of Common Response components with capabilities that are specific to Twilio.

You access the extensions by using the channelCustomProperties element in the component and setting the appropriate properties. The code has the following format: 

...
            channelCustomProperties:
            - channel: "twilio"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

You can apply channelCustomProperties in the component's metadata at the level of globalActions, responseItems, and elements of responseItems, depending on the given property.

Here are the available custom properties for Twilio channels:

Name Allowed Values Applies To... Description
mmsEnabled
  • true
  • false
 Response items of type cards or attachment. Can be used to override the default MMS-enabled setting of the channel configuration. If enabled, images are shown in its own message bubble with a Tap to review button.
optimizeCardRendering
  • true
  • false
 Response items of type cards. Set to true to make the card action selection a two-step process, where the user first selects a card and then selects the card action.
cardListHeader
  • free text
 Response items of type cards. The header shown when the card list is presented. This property overrides the card message headerText property. Only applicable when optimizeCardRendering is set to true.
cardListFooter
  • free text
 Response items of type cards. The footer shown when the card list is presented. This property overrides the card message footerText property. Only applicable when optimizeCardRendering is set to true.
cardDetailHeader
  • free text
 Either of the following:
  • A card where the "url" property is specified
  • An action where "type": "url"
 The header shown when the card detail is presented. This property overrides the card message headerText property. Only applicable when optimizeCardRendering is set to true.
cardDetailFooter
  • free text
 Either of the following:
  • A card where the "url" property is specified
  • An action where "type": "url"
 The footer shown when the card detail is presented. This property overrides the card message footerText property. Only applicable when optimizeCardRendering is set to true.

For more information on using channelCustomProperties, see Channel-Specific Extensions.