Response types reference

Integration channel support

• Some channel integrations do not display audio titles or descriptions.

Fields

The URL specified by the source property can be one of the following types:

• The URL of an audio file in any standard format such as MP3 or WAV. In the web chat, the linked audio clip renders as an embedded audio player.

• The URL of an audio clip on a supported streaming service. In the web chat, the linked audio clip renders by using the embeddable player for the hosting service.

Specify the URL that you use to access the audio file in your browser (for example, https://soundcloud.com/ibmresearchfallen-star-amped). The web chat automatically converts the URL to an embeddable form.

You can embed audio hosted on a supported service:

• SoundCloud

• Mixcloud

For the phone integration, the URL must specify an audio file that is single-channel (mono) and PCM-encoded, and is sampled at 8,000 Hz with 16 bits per sample.

Example

This example plays an audio clip with a title and descriptive text.

{
  "generic":[
    {
      "response_type": "audio",
      "source": "https://example.com/audio/example-file.mp3",
      "title": "Example audio file",
      "description": "An example audio clip returned as part of a multimedia response."
    }
  ]
}

Integration channel support

Fields

post_back button type

The post_back button sends a response to the AI assistant when the user clicks the button. You can use both the value and label properties to set up the response to send.

{
  "response_type": "button",
  "button_type": "post_back",
  "label": "Send message",
  "value": {
    "input": {
      "text": "[Message to send]"
    }
  }
}

custom_event button type

When the user clicks the custom_event button, a custom event, which you configured along with the user-defined data, is triggered. You must create the event to achieve the desired behavior by using custom codes. In web chat, you can use the messageItemCustom event to apply the desired behavior when the user clicks the button.

{
  "response_type": "button",
  "button_type": "custom_event",
  "label": "Alert",
  "kind": "danger",
  "custom_event_name": "trigger_alert",
  "user_defined": {
    "message": "[Alert message]"
  }
}

show_panel button type

When a user clicks the show_panel button, the AI assistant opens a panel that the users can use to get additional information or complete a task.

{
  "response_type": "button",
  "button_type": "show_panel",
  "label": "See details",
  "kind": "secondary",
  "panel": {
    "title": "[Product name]",
    "show_animations": true,
    "body": [
      {
        "response_type": "image",
        "source": "https://example.com/image.jpg"
      },
      {
        "response_type": "text",
        "text": "[Product details]"
      }
    ]
  }
}

url button type

When a user clicks the url button, the user goes to the url field to add the destination url.

{
  "response_type": "button",
  "button_type": "url",
  "label": "Visit ibm.com",
  "url": "https://www.ibm.com"
}

Integration channel support

Fields

A card can be rendered in a panel, but it is not allowed to have buttons.

Example

The following example shows the basic structure for building a card response type:

{
  "response_type": "card",
  "body": [
    {
      "response_type": "text",
      "text": "# Heading"
    },
    {
      "response_type": "text",
      "text": "body"
    }
  ]
}

Integration channel support

Fields

Example

The following example shows the basic structure for building a carousel response type:

{
  "response_type": "carousel",
  "items": [
    {
      "response_type": "card",
      "body": [
        {
          "response_type": "text",
          "text": "# Heading"
        },
        {
          "response_type": "text",
          "text": "body"
        }
      ]
    },
    {
      "response_type": "card",
      "body": [
        {
          "response_type": "text",
          "text": "# Heading"
        },
        {
          "response_type": "text",
          "text": "body"
        }
      ]
    }
  ]
}

Integration channel support

• The indicated channel integrations support _initiating_ a channel transfer (currently, the web chat integration is the only supported transfer target).

• Initiating a channel transfer from the phone integration requires that the SMS integration is also configured.

Fields

Example

This example requests a transfer from WhatsApp to the web chat. In addition to the channel_transfer response, the output also includes a text response to be displayed by the web chat integration after the transfer. The use of the channels array ensures that the channel_transfer response is handled only by the WhatsApp integration (before the transfer), and the connect_to_agent response only by the web chat integration (after the transfer).

{
  "generic": [
    {
      "response_type": "channel_transfer",
      "channels": [
        {
          "channel": "whatsapp"
        }
      ],
      "message_to_user": "Click the link to connect with an agent using our website.",
      "transfer_info": {
        "target": {
          "chat": {
            "url": "https://example.com/webchat"
          }
        }
      }
    },
    {
      "response_type": "connect_to_agent",
      "channels": [
        {
          "channel": "chat"
        }
      ],
      "message_to_human_agent": "User asked to speak to an agent.",
      "agent_available": {
        "message": "Please wait while I connect you to an agent."
      },
      "agent_unavailable": {
        "message": "I'm sorry, but no agents are online at the moment. Please try again later."
      },
      "transfer_info": {
        "target": {
          "zendesk": {
            "department": "Payments department"
          }
        }
      }
    }
  ]
}

Integration channel support

For information about adding service desk support to the phone integration, see Configuring backup call center support.

Fields

Example

This example requests a transfer to a live agent and specifies messages to be displayed both to the user and to the agent at the time of transfer.

{
  "generic": [
    {
      "response_type": "connect_to_agent",
      "message_to_human_agent": "User asked to speak to an agent.",
      "agent_available": {
        "message": "Please wait while I connect you to an agent."
      },
      "agent_unavailable": {
        "message": "I'm sorry, but no agents are online at the moment. Please try again later."
      }
    }
  ]
}

Integration channel support

• In the web chat, the customer can specify a date value either by clicking the interactive date picker or typing a date value in the input field.

Fields

Example

This example sends a text response that asks the user to specify a date, and then shows an interactive date picker.

{
  "generic": [
    {
      "response_type": "text",
      "text": "What day will you be checking in?"
    },
    {
      "response_type": "date"
    }
  ]
}

Integration channel support

Fields

The command_info.type field can specify any of the following supported commands:

• collect: Collects DTMF keypad input.

• disable_barge_in: Disables DTMF barge-in so that playback from the phone integration is not interrupted when the customer presses a key.

• enable_barge_in: Enables DTMF barge-in so that the customer can interrupt playback from the phone integration by pressing a key.

• send: Sends DTMF signals.

For detailed information about how to use each of these commands, see Handling phone interactions.

Example

This example shows the dtmf response type with the collect command, used to collect DTMF input. For more information, see Handling phone interactions.

{
  "generic": [
    {
      "response_type": "dtmf",
      "command_info": {
        "type": "collect",
        "parameters": {
          "termination_key": "#",
          "count": 16,
          "ignore_speech": true
        }
      },
      "channels": [
        {
          "channel": "voice_telephony"
        }
      ]
    }
  ]
}

Integration channel support

• The SMS integration supports ending a session by using the terminateSession action command.

Fields

For the phone integration, you can use the channel_options object to include custom headers with the SIP BYE request that is generated. For more information, see End the call.

Example

This example uses the end_session response type to end a conversation.

{
  "generic": [
    {
      "response_type": "end_session"
    }
  ]
}

Integration channel support

Fields

Example

The following example shows the basic structure for building a grid response type:

{
  "response_type": "grid",
  "columns": [
    {
      "width": "1"
    },
    {
      "width": "1"
    }
  ],
  "rows": [
    {
      "cells": [
        {
          "items": [
            {
              "response_type": "text",
              "text": "row 1 cell 1"
            }
          ]
        },
        {
          "items": [
            {
              "response_type": "text",
              "text": "row 1 cell 2"
            }
          ]
        }
      ]
    },
    {
      "cells": [
        {
          "items": [
            {
              "response_type": "text",
              "text": "row 2 cell 1"
            }
          ]
        },
        {
          "items": [
            {
              "response_type": "text",
              "text": "row 2 cell 2"
            }
          ]
        }
      ]
    }
  ]
}

Integration channel support

• Currently, the web chat integration ignores the description and image_url properties. Instead, the description and preview image are dynamically retrieved from the source at run time.

Fields

Different sites have varying restrictions for embedding content, and different processes for generating embeddable URLs. An embeddable URL is one that can be specified as the value of the src attribute of the iframe element.

For example, to embed an interactive map with Google Maps, you can use the Google Maps Embed API. (For more information, see The Maps Embed API overview.) Other sites have different processes for creating embeddable content.

For technical details about using Content-Security-Policy: frame-src to allow embedding of your website content, see CSP: frame-src.

Example

The following example embeds an iframe with a title and description.

{
  "generic":[
    {
      "response_type": "iframe",
      "source": "https://example.com/embeddable/example",
      "title": "Example iframe",
      "description": "An example of embeddable content returned as an iframe response.",
      "channel_options": {
        "chat": {
          "display": "inline",
          "base_height": 180
        }
      }
    }
  ]
}

Integration channel support

• Some channel integrations do not display image titles or descriptions.

Fields

Example

This example displays an image with a title and descriptive text.

{
  "generic":[
    {
      "response_type": "image",
      "source": "https://example.com/image.jpg",
      "title": "Example image",
      "description": "An example image returned as part of a multimedia response."
    }
  ]
}

Integration channel support

• How options are presented varies by channel integration. The preference field is supported when possible, but not all channels support drop-down lists or buttons.

Fields

Example

This example presents two options (Buy something and Exit).

{
  "generic":[
    {
      "response_type": "option",
      "title": "Choose from the following options:",
      "preference": "button",
      "options": [
        {
          "label": "Buy something",
          "value": {
            "input": {
              "text": "Place order"
            }
          }
        },
        {
          "label": "Exit",
          "value": {
            "input": {
              "text": "Exit"
            }
          }
        }
      ]
    }
  ]
}

Integration channel support

• With the phone integration, you can add a pause by including the SSML break element in the AI assistant output. For more information, see the Text to Speech documentation.

Fields

Example

This example sends the "user is typing" event and pauses for 5 seconds.

{
    "generic":[
      {
        "response_type": "pause",
        "time": 5000,
        "typing": true
      }
    ]
}

Integration channel support

Fields

The command_info.type field can specify any of the following supported commands:

• configure: Dynamically updates the Speech to Text configuration. Configuration changes can be applied only to the next conversation turn, or for the rest of the session.

For information about how to use this command, see Applying advanced settings to the Speech to Text service.

Example

This example uses the speech_to_text response type with the configure command to change the language model from the Speech to Text service to Spanish, and to enable smart formatting.

{
  "generic": [
    {
      "response_type": "speech_to_text",
      "command_info": {
        "type": "configure",
        "parameters": {
          "narrowband_recognize": {
            "model": "es-ES_NarrowbandModel",
            "smart_formatting": true
          }
        }
      },
      "channels":[
        {
          "channel": "voice_telephony"
        }
      ]
    }
  ]
}

Integration channel support

Fields

Currently, the following activities for the phone integration can be started:

• speech_to_text_recognition: Recognizes speech. Streaming audio to the Speech to Text service is resumed.

• dtmf_collection: Processes inbound DTMF signals.

Example

This example uses the start_activities response type to restart recognizing speech. Because this command is specific to the phone integration, the channels property specifies voice_telephony only.

{
  "generic": [
    {
      "response_type": "start_activities",
      "activities": [
        {
          "type": "speech_to_text_recognition"
        }
      ],
      "channels":[
        {
          "channel": "voice_telephony"
        }
      ]
    }
  ]
}

Integration channel support

Fields

Currently, the following activities for the phone integration can be stopped:

• speech_to_text_recognition: Stops recognizing speech. All streaming audio to the Speech to Text service is stopped.

• dtmf_collection: Stops processing of inbound DTMF signals.

Example

This example uses the stop_activities response type to stop recognizing speech. Because this command is specific to the phone integration, the channels property specifies voice_telephony only.

{
  "generic": [
    {
      "response_type": "stop_activities",
      "activities": [
        {
          "type": "speech_to_text_recognition"
        }
      ],
      "channels":[
        {
          "channel":"voice_telephony"
        }
      ]
    }
  ]
}

Integration channel support

Properties and Definitions

Each row must have the same number of cells as the headers. A mismatch between cells and headers will cause the web chat to throw an error when it attempts to render the table.

Example

This example displays structured data in a table.

{
    "generic": [
      {
        "response_type": "table",
        "title": "Data Table",
        "description": "A table with data",
        "headers": ["Column 1", "Column 2"],
        "rows": [
          {
            "cells": ["Row 1, Column 1", "Row 1, Column 2"]
          },
          {
            "cells": ["Row 2, Column 1", "22"]
          }
        ]
      }
    ]
}

Integration channel support

Fields

Example

This example displays a greeting message to the user.

{
  "generic": [
    {
      "response_type": "text",
      "values": [
        {
          "text_expression": {
            "concat": [
              {
                "scalar": "Hi, "
              },
              {
                "variable": "step_472"
              },
              {
                "scalar": ". How can I help you?"
              }
            ]
          }
        }
      ],
      "selection_policy": "sequential"
    }
  ]
}  

Integration channel support

Fields

The command_info.type field can specify any of the following supported commands:

• configure: Dynamically updates the Text to Speech configuration. Configuration changes can be applied only to the next conversation turn, or for the rest of the session.

• disable_barge_in: Disables speech barge-in so that playback from the phone integration is not interrupted when the customer speaks.

• enable_barge_in: Enables speech barge-in so that the customer can interrupt playback from the phone integration by speaking.

For detailed information about how to use each of these commands, see Applying advanced settings to the Text to Speech service.

Example

This example uses the text_to_speech response type with the configure command to change the voice used by the Text to Speech service.

{
  "generic": [
    {
      "response_type": "text_to_speech",
      "command_info": {
        "type": "configure",
        "parameters" : {
          "synthesize": {
            "voice": "en-US_LisaVoice"
          }          
        }
      },
      "channels":[
        {
          "channel": "voice_telephony"
        }
      ]
    }
  ]
}

Integration channel support

• With the phone integration, the user_defined response type is used to send legacy commands (for example, vgwActForceNoInputTurn or vgwActSendSMS). For more information, see Handling phone interactions.

• With the SMS integration, the user_defined response type is used to send action commands (for example, terminateSession or smsActSendMedia).

Fields

Example

This example shows a generic example of a user-defined response. The user_defined object can contain any valid JSON data.

{
  "generic":[
    {
      "response_type": "user_defined",
      "user_defined": {
        "field_1": "String value",
        "array_1": [
          1,
          2
        ],
        "object_1": {
          "property_1": "Another string value"
        }
      }
    }
  ]
}

Integration channel support

• Some channel integrations do not display video titles or descriptions.

Fields

The URL specified with the source property can be one of the following types:

• The URL of a video file in a standard format such as MPEG or AVI. In the web chat, the linked video renders as an embedded video player.

HLS (.m3u8) and DASH (MPD) streaming videos are not supported.

• The URL of a video from a supported service. In the web chat, the linked video renders with the embeddable player for the hosting service.

Specify the URL of the video that you want to view in your browser (for example, https://www.youtube.com/watch?v=52bpMKVigGU). The web chat automatically converts the URL to an embeddable form.

You can embed videos from the following services:

• YouTube

• Facebook

• Vimeo

• Twitch

• Streamable

• Wistia

• Vidyard

Example

This example displays a video with a title and descriptive text.

{
  "generic":[
    {
      "response_type": "video",
      "source": "https://example.com/videos/example-video.mp4",
      "title": "Example video",
      "description": "An example video returned as part of a multimedia response."
    }
  ]
}