Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Configuring on-premises or internal access only environments for Digital Messaging access

Updated on December 21, 2023

Configure your on-premises or internal access only Pega Platform environment to enable communication with publicly accessible endpoints required by Digital Messaging Service. This includes enabling communication through a virtual private network (VPN). This configuration enables the implementation of a Digital Messaging channel for customer interaction with your chatbot and application on platforms such as Web Messaging.

Follow these guidelines when creating your Digital Messaging channel interface:

  • The system generates endpoint URLs based on the value entered in the Base URL field. For example, if you enter https://instanceID-stg1.pegacloud.net/prweb in the Base URL field, the system appends the necessary URL elements and forms the following messaging endpoint:

    https://instanceID-stg1.pegacloud.net/prweb/PRRestService/botAgent/v1/messaging

  • Pegasystems determines the Digital Messaging Service region during the provisioning of your Digital Messaging Manager ID and Manager Key, as described in the region-specific settings below. Ensure that you use the appropriate region for your Manager ID.
  • For Pega Cloud instances, submit a Cloud Change (CC) request, specifying the inbound endpoints and the IP addresses to give permission to. For more information, go to Pega Support Center.

The following are the endpoint definitions for step 2:

api
Establishes the connection with Digital Messaging Service and enables message delivery.
accounts
Displays Digital Messaging Manager when you click Manage connections in the Digital Messaging channel interface. You do not need to enable access for this endpoint if the operator's access is not restricted.
cdn (content delivery network)
Displays icons for each connection in the Digital Messaging channel interface. The icons are fixed assets. The system uses the same endpoint for every region. You can access this endpoint from either the operator's web browser or the Pega Platform application.
attachments
Handles CSR attachment uploads from Interaction Portal and provides the URL through Digital Messaging Service for file attachment retrieval by customers. This one-way communication occurs from your Pega Platform application to Amazon S3 storage service. Unlike other endpoints which you can configure for reverse proxy and gateway, you cannot customize, change, or map this attachment endpoint in your Pega Platform instance.
widget-logo, widget-avatars, and widget-fonts
Used for file uploads in the Digital Messaging Manager Web Messaging settings.
  1. Allow inbound message delivery from the customer to your chatbot and CSR, by opening access for the following items:
    • Requests originating from the dedicated Digital Messaging Service IP addresses. Pegasystems provides these IP addresses in the instructions included with your Digital Messaging credentials when they are provisioned.
    • Requests directed to the endpoints shown below, which are used in your instance to handle the various Digital Messaging Service requests. You can find these endpoints in your Pega Platform application by going to RecordsIntegration-ServicesService RESTbotAgent Service REST package Rule, as shown in the example below:
    Endpoint URLDescription
    https://{instanceID}/prweb/PRRestService/botAgent/v1/messaging and

    https://{instanceID}/prweb/PRRestService/botAgentListener/v1/accounts

    Required for message delivery and connection management.
    https://{instanceID}/prweb/PRRestService/botAgent/v1/messaging/{consumerId}/history/{customerId}/{interactionId} and

    https://{instanceID}/prweb/PRRestService/botAgent/v1/messaging/{consumerId}/conversation/{customerId}

    Required for asynchronous messaging and conversation history requests (if enabled in Web Messaging or Mobile Messaging SDK connection settings).
    https://{instanceID}/prweb/PRRestService/botAgent/v1/messaging/form/submit and

    https://{instanceID}/prweb/PRRestService/botAgent/v1/messaging/form/refresh

    Required for Forms requests in Web Messaging (if forms-type replies are configured).
    https://{instanceID}/prweb/PRRestService/botAgentAuthentication/v1/authUsed for customer authentication during chat (if authentication is configured).

    Perform this step for firewall configuration to ensure that your application can receive messages from Digital Messaging Service (HTTPS/443). The system rejects calls to these endpoints if you have not properly configured your firewall, proxy, and load balancers, or the Manager ID and Manager Key for your instance.

    Note:
    • Replace the {instanceID} string in the above endpoints with your instance identifier, for example: abc-stg1-domain.com.
    • Enabling requests to *PRRestService/botAgent* covers all of the above required endpoints.
    • You can replace the prweb/ string with your own custom servlets, if needed.
    For example:

    The following figure shows a list of botAgent Service REST package Rules where the endpoints are already specified:

    botAgent Service REST package Rules
    botAgent Service REST package Rules in Pega Platform.
  2. If access is restricted, enable outbound communication and message delivery from your chatbot or CSR to the customer, by providing access for the following endpoints for your Digital Messaging Service region.
    Note: For outbound requests, dedicated Digital Messaging Service IP addresses or ranges are not available. Use only the endpoint URLs listed for one of the regions in the following table.
    RegionEndpoints
    United States (US East, N. Virginia): us-east-1https://api.artemis.pega.digitalhttps://outgoing.artemis.pega.digitalhttps://accounts.artemis.pega.digital https://cdn.artemis.pega.digitalhttps://prod-artemis-attachments.s3.amazonaws.comhttps://s3.us-east-1.amazonaws.com/prod-um-widget-logo and https://prod-um-widget-logo.s3.amazonaws.comhttps://s3.us-east-1.amazonaws.com/prod-dm-widget-avatars and https://prod-dm-widget-avatars.s3.amazonaws.comhttps://s3.us-east-1.amazonaws.com/prod-dm-widget-fonts
    Canada (Central): ca-central-1https://api.ca.um.pega.digitalhttps://outgoing.ca.um.pega.digitalhttps://accounts.ca.um.pega.digitalhttps://cdn.artemis.pega.digitalhttps://canprod-artemis-attachments.s3.ca-central-1.amazonaws.como https://s3.ca-central-1.amazonaws.com/canprod-um-widget-logo and https://canprod-um-widget-logo.s3.ca-central-1.amazonaws.comhttps://s3.ca-central-1.amazonaws.com/canprod-dm-widget-avatars and https://canprod-dm-widget-avatars.s3.ca-central-1.amazonaws.comhttps://s3.ca-central-1.amazonaws.com/canprod-dm-widget-fonts
    Europe (Ireland): eu-west-1https://api.euw1.um.pega.digitalhttps://outgoing.euw1.um.pega.digitalhttps://accounts.euw1.um.pega.digitalhttps://cdn.artemis.pega.digitalhttps://euw1prod-artemis-attachments.s3.eu-west-1.amazonaws.comhttps://s3.eu-west-1.amazonaws.com/euw1prod-um-widget-logo and https://euw1prod-um-widget-logo.s3.eu-west-1.amazonaws.comhttps://s3.eu-west-1.amazonaws.com/euw1prod-dm-widget-avatars and https://euw1prod-dm-widget-avatars.s3.eu-west-1.amazonaws.comhttps://s3.eu-west-1.amazonaws.com/euw1prod-dm-widget-fonts
    Europe (London/UK): eu-west-2https://api.uk.um.pega.digitalhttps://outgoing.uk.um.pega.digitalhttps://accounts.uk.um.pega.digitalhttps://cdn.artemis.pega.digitalhttps://euw2prod-artemis-attachments.s3.eu-west-2.amazonaws.comhttps://s3.eu-west-2.amazonaws.com/euw2prod-um-widget-logo and https://euw2prod-um-widget-logo.s3.eu-west-2.amazonaws.comhttps://s3.eu-west-2.amazonaws.com/euw2prod-dm-widget-avatars and https://euw2prod-dm-widget-avatars.s3.eu-west-2.amazonaws.comhttps://s3.eu-west-2.amazonaws.com/euw2prod-dm-widget-fonts
    Europe (Frankfurt): eu-central-1https://api.euc1.um.pega.digitalhttps://outgoing.euc1.um.pega.digitalhttps://accounts.euc1.um.pega.digitalhttps://cdn.artemis.pega.digitalhttps://euc1prod-artemis-attachments.s3.eu-central-1.amazonaws.comhttps://s3.eu-central-1.amazonaws.com/euc1prod-um-widget-logo and https://euc1prod-um-widget-logo.s3.eu-central-1.amazonaws.comhttps://s3.eu-central-1.amazonaws.com/euc1prod-dm-widget-avatars and https://euc1prod-dm-widget-avatars.s3.eu-central-1.amazonaws.comhttps://s3.eu-central-1.amazonaws.com/euc1prod-dm-widget-fonts
    For example: If Pegasystems provisioned your Digital Messaging credentials for the eu-west-1 region, open access for the endpoints specified in the Europe (Ireland) eu-west-1 row in the table.
  3. If you set up your Pega Platform environment behind a proxy or an API Gateway, use the proxy or gateway URL as the publicly accessible URL for your instance.
    1. In your Digital Messaging channel interface, on the Connection tab, in the Base URL field, enter the publicly accessible URL for your Pega Platform instance.
    2. Ensure that you use a secure connection (HTTPS) for the URL.
    For example: Specify https://proxyURL/prweb
    Your proxy or API Gateway is responsible for receiving messages and forwarding them externally to your application.
  4. If Pega provisioned your Digital Messaging credentials for a Digital Messaging Service region other than the us-east-1 default setting in your application (equivalent to 'artemis' endpoints), update the URL API settings in data transform rules for the Data-Channel-Configuration-BotAgent class:
    1. Switch to Dev Studio.
    2. In the navigation pane of Dev Studio, click App, and then search for the Data-Channel-Configuration-BotAgent class.
    3. Expand the Data ModelData Transform section for the Data-Channel-Configuration-BotAgent class, and then click pyDefault.
    4. In the data transform rule, in the row for the .pyManagementAPIUrl target, in the field in the Source column, update the URL API endpoint for your region with the value in the first row in the table in step 2.
      Enter the value in the field in the Source column in double quotation marks.
      For example:

      The following figure shows the correct updated value in the Source column for Europe (Ireland) region configuration, "https://api.euw1.um.pega.digital":

      Updated settings for the pyDefault data transform rule for the Europe region.
      Updated settings for the pyDefault data transform rule for an environment in the eu-west-1 region.
    5. Save the rule to a ruleset by clicking Save as.
    6. In the navigation pane of Dev Studio, click App, and then search for the Data-Channel-Configuration-BotAgent class.
    7. Expand the Data ModelData Transform section for the Data-Channel-Configuration-BotAgent class, and then click pySetBaseURL.
    8. In the data transform rule, in the row for the .pyManagementAPIUrl target, in the field in the Source column, update the URL API endpoint for your region with the value in the first row in the table in step 2.
      Enter the value in the field in the Source column in double quotation marks.
      For example:

      The following figure shows the correct updated value in the Source column for the Europe (Ireland) region configuration, "https://api.euw1.um.pega.digital":

      Updated settings for the pySetBaseURL data transform rule for the Europe region.
      Updated settings for the pySetBaseURL data transform rule for an environment in the eu-west-1 region.
    9. Save the rule to a ruleset by clicking Save as.
    10. Switch back to App Studio.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us