Close popover
Piotr Kulig (Piotr Kulig)
Principal Product Architect
Pegasystems Inc.
Piotr Kulig Member since 2014 8 posts
Posted: November 17, 2018
Last activity: December 10, 2018

How to create conversational 3rd party channel integration

In order to integrate a Pega IVA with a specific 3rd party channel (ex. Facebook, Alexa) there needs to be a channel component installed on the Pega application. These components handle the integration to the third party APIs, the mapping of data in, and the configuration of the channel. There are example components for Facebook, Alexa and others available on the Pega Exchange. It is also possible to create this component, allowing Pega's customers and partners to expose their bots across a wide variety of channels. This document walks through the technical details of building the channel component.

Multichannel Case Processor (MCP) is an engine used to process data from different channels. A Channel is considered a type of communication and includes a model for the channel's configuration and processing as well as endpoints for outbound and inbound messaging. Optionally, it could contain additional actions and customized UI for configuration. It is possible to create multiple instances of one channel to interact with different endpoints (i.e. Facebook pages).

  • channel - implementation of particular type of communication - Facebook, Alexa, Tropo, etc. - shipped as ruleset (i.e. FacebookChannel),
  • channel instance (bot) - concrete bot definition of a channel - instance of configuration which contains information about endpoints, identified by bot Id (bot id is required for client to communicate with Pega 7 bot).

Data model


Base abstraction for channel's configuration. Each channel should have its own configuration class which belongs to the Data-Channel-Configuration class group.

Work-Channel-Interaction- (interaction case)

Page used as context of entire MCP processing (entire user interaction with channel instance). It can be extended by any channel's implementation to store other properties required by the channel's specific processing, once it is created it is passed to all processing stages.

MCP is responsible for processing the inbound model and generating outbound messages that are used by a particular channel's implementation as the MCP response. MCP can also produce multiple outbound messages as a result of single input processing.

How to create new channel - step by step guide

  1. Optional: Add specific ruleset to your application if required (i.e. FacebookChannel, TropoChannel).
  2. Create Data-Channel-Configuration-<channel_name> concrete class, it must belong to the Data-Channel-Configuration class group:

    When a new class is added, the new channel's name label is generated within Data-Channel-Configuration.pyDefault activity.
  3. Optional: Create additional channel’s specific properties in your concrete class:
  4. Create Work-Channel-Interaction-<channel_name> concrete class, it must belong to Work-Channel-Interaction class group.
  5. Create Data-Channel-Configuration-<channel_name>.pyDefault data transform to predefine processing page class. Set pzChannelIcon to customize the channels application view icon. The image must be in SVG format.
  6. Optional: create additional channel’s specific properties in your processing page if required (properties will be passed with transport page through entire processing).
  7. Optional: Save as extension section(s) to your Data-Channel-Configuration-<channel_name> class if you want to add customized UI to a channel’s configuration:
    • pyChannelBehaviourExtension - bottom of behavior tab
    • pyChannelConfigurationExtension - bottom of connection tab
    • pyChannelResponsesExtension - bottom of configuration tab
    • pyTileSubtitle - channel's tile subtitle
  8. Optional: Save as additional when rules to your Data-Channel-Configuration-<channel_name> class to set desired kind of channel behavior:
    • pyGenerateNlpAnalyzer - if Text Analyzer should be created for this channel,

    • pyIsConversationalChannel - if channel should be displayed in Case Designer in parallel flow generation,

    • pyShowInCreateMenu - if channel should be shown in create Application View menu.

  9. Go to Application menu > Application views - at this point you should see your newly created channel.
  10. Create channel specific end points (HTTP Service, HTTP Connector etc.).
    1. If you need to create service package - please note that it has to point to AG which is associated with application where your channel is available (for example - ruleset in stack).
    2. Please note that in CUSTOM tab of authentication service you need to set the "Source of operator credentials" to PEGA RULES. By default it is different.
  11. If you want to use default OOTB authentication: create new class Data-Channel-Authentication-<channel_name>.
  12. Map all required input properties to the authentication page and call pxChannelAuth:
    • pyBotId - unique channel instance identifier (in Facebook case - page id)
    • pyChannelUserId - identifies end user (in Facebook case - sender id)
  13. A Channel’s user ID will be mapped to a Pega 7 operator (operator will be automatically generated from template defined in configuration).
  14. If your request is authenticated, you have to create request handler activity:
    • call pxAcquireInteraction on Work-Channel-Interaction-<channel_name> page (it could be empty): pyInteractionCase page will be created (existing or new one),
    • translate input channel's data to MCP model (pyInboundMessage) - set it in pyInteractionCase,
    • call pxProcess on pyInteractionCase page, this activity is responsible for:
      • running text analyzers chain
      • running actions / processing work
      • saving history
    • if your protocol requires data in the request's response - translate the MCP model (pyOutboundMessages) to the channel's specific protocol as result.
Pega Intelligent Virtual Assistant Conversational Channels Developer Knowledge Share