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 and WeChat, 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 the System.CommonResponse component, this means that you need to update the metadata property to include (or where applicable, exclude) Twilio or WeChat for any response item, card, or global action:
    channelTest:
      component: "System.CommonResponse"
      properties:
        processUserMessage: false
        metadata:
          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
    Description of the illustration twilio_products.png

  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:
    • Enter a name and then choose Twilio SMS from the Channel Type menu.

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

    Switch on Channel Enabled.
  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

Slack channels in Digital Assistant support the following capabilities:

  • text (both sending and receiving)
  • images (partial for sending and receiving)
  • files (partial for sending and receiving)
  • emojis (partial for sending and receiving)
  • links
  • postbacks (partial)
  • custom properties (partial)
  • carousel components (partial)
  • list components (partial)

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 System.CommonResponse components with capabilities that are specific to Twilio.

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

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

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.

WeChat

To configure a WeChat channel, you need:
  • An App ID from WeChat—You provide this to Digital Assistant. To get an App ID, you need:
    • A WeChat Official Account or an International Official Account (WeChat OA) for bots used in China.

    • The account type must be a Service Account.

  • Credentials required by both WeChat and Digital Assistant:

    • An App Secret

    • An Access Token—This token is valid for 7200 seconds.

  • Credentials Provided to WeChat from Digital Assistant:
    • The webhook URL generated by Digital Assistant.

Step 1: Configure the WeChat Channel in Digital Assistant

  1. First, get the App ID WeChat. You can find it by clicking Basic Configuration (located in the Developer section in the left navbar of the WeChat Official Account Admin Platform). Copy the App ID.

  2. In Digital Assistant, click Channels in the left menu, then choose Users.

  3. Click Add Channel.

  4. In the Create Channel dialog:
    • Enter a name and then choose WeChat from the Channel Type menu.

    • Enter the App ID from WeChat, the App Secret and the token.

    Switch on Channel Enabled.
  5. Click Create.

  6. Copy the generated Webhook URL.

Step 2: Link the Bot to the WeChat Account

  1. In the Basic Configuration section of the WeChat Official Account Admin Platform, paste in the App Secret.

  2. Go to the Server Settings section and then click Edit.

  3. Paste in the Webhook URL generated by Digital Assistant in the URL field.and then click Submit.

  4. Paste the token in the Token field.
    Note

    The values for the App Secret and token must match the ones you entered in the Digital Assistant’s WeChat configuration dialog.
  5. Click Submit and then click Enable.