Skip to main content

Salesforce Messaging

Salesforce Messaging Integration Guide

Overview

This guide explains how to connect Bridged with Salesforce Messaging (including Messaging for In-App and Web, and Digital Engagement) to enable chat, messaging, and conversational experiences across your digital properties. The integration supports embedding chat sessions into your website or application, syncing conversation transcripts, and enabling seamless handoff between automated agents and human agents .

Salesforce Messaging provides API-first digital engagement capabilities that allow you to build fully customized chat experiences while leveraging Salesforce Service Cloud's routing, queuing, and agent tools .

Prerequisites

Before starting, ensure you have:

  • A Salesforce account with Service Cloud and Digital Engagement licenses

  • Messaging User permission set license assigned to the integration user

  • A Salesforce user with API Enabled permission

  • Access to create Connected Apps in Salesforce (System Administrator permissions)

  • A Messaging Channel configured in Salesforce (for In-App and Web messaging)

Connection Methods

Bridged supports two authentication methods for Salesforce Messaging:

Method

Best for

Setup complexity

API Key (OAuth 2.0 JWT - Preferred)

Server-to-server, automated messaging, production

Medium

OAuth 2.0 Authorization Code

Interactive setup, testing

Medium

Recommendation: OAuth 2.0 JWT Bearer flow is preferred for production integrations as it enables secure server-to-server authentication without user interaction .

Step 1: Create a Connected App in Salesforce

  1. Log in to your Salesforce account as a System Administrator.

  2. Navigate to Setup → App Manager.

  3. Click New Connected App.

  4. Fill in the basic information:

    • Connected App Name: Bridged Messaging Integration

    • API Name: Bridged_Messaging_Integration

    • Contact Email: your email address

  5. Under API (Enable OAuth Settings):

    • Check Enable OAuth Settings

    • Callback URL: https://gateway.bridged.media/auth/salesforcemessaging/callback

  6. Under Selected OAuth Scopes, add:

    • Access and manage your data (api)

    • Perform requests on your behalf at any time (refresh_token, offline_access)

    • Full access (full) (if needed for messaging operations)

  7. Click Save.

  8. After saving, click Manage Consumer Details to view and copy:

    • Consumer Key (Client ID)

    • Consumer Secret (Client Secret)

Step 2: Configure OAuth Policies for Messaging

  1. From the Connected App detail page, click Manage.

  2. Click Edit Policies.

  3. Configure the following:

    • Permitted Users: Select "Admin approved users are pre-authorized"

    • IP Relaxation: Set as appropriate for your network security

    • Refresh Token Policy: "Refresh token is valid until revoked"

  4. Click Save.

Step 3: Set Up a Messaging-Enabled Integration User

For messaging integrations, create a dedicated user with messaging permissions:

  1. Go to Setup → Users → New User.

  2. Create a user: Bridged Messaging User.

  3. Assign a profile with API Only permission.

  4. Assign the Messaging User permission set license .

  5. Ensure the user has read and modify access to:

    • MessagingSession object

    • MessagingEndUser object

    • Conversation object

    • Message object

Step 4: Configure a Messaging Channel (In-App and Web)

Salesforce Messaging requires a configured channel for each messaging surface.

Step 4.1: Create a Messaging Channel

  1. In Salesforce Setup, search for Messaging Channels.

  2. Click New.

  3. Fill in the channel details:

    • Name: Bridged Web Chat

    • Developer Name: Bridged_Web_Chat

    • Channel Type: In-App and Web

  4. Configure routing settings (queue assignment, skill-based routing).

  5. Click Save.

  6. Copy the Messaging Platform Key - you will need this for API calls .

Step 4.2: Configure Pre-Chat Data Collection (Optional)

Pre-chat details allow you to collect customer information before routing to an agent :

  1. In the Messaging Channel configuration, scroll to Pre-chat Configuration.

  2. Add pre-chat fields (e.g., Email, Order Number, Issue Type).

  3. Map each field to:

    • Transcript Field: Where the data is stored on the Messaging Session record

    • Display to Agent: Whether the agent sees this information

Step 5: Configure Bridged to Connect to Salesforce Messaging

  1. Log in to your Bridged dashboard.

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media.

  3. Click Salesforce Messaging → Connect Account.

  4. Choose your authentication method:

Option A: OAuth 2.0 JWT (Preferred for Production)

For JWT authentication, you need a certificate:

  1. Generate a certificate or use an existing one from your Salesforce org.

  2. In the Connected App, upload the certificate under Digital Signature.

  3. In Bridged, enter:

    • Client ID (Consumer Key)

    • Client Secret (Consumer Secret)

    • Username (integration user email)

    • Certificate (private key content)

Option B: OAuth 2.0 Authorization Code

  1. Enter your Client ID and Client Secret from Step 1.

  2. Enter your Messaging Platform Key from Step 4.

  3. Click Connect with Salesforce.

  4. You will be redirected to Salesforce to log in and authorize the Bridged app.

  5. After authorization, you will be redirected back to Bridged.

Step 6: Configure Webhook for Inbound Messages

Salesforce Messaging uses a long-polling pattern rather than traditional webhooks for receiving messages . Bridged handles this automatically.

Long-Polling Mechanism

Instead of configuring a webhook URL in Salesforce, Bridged maintains persistent HTTP connections to receive messages in real time :

text

GET /v58.0/conversations/{conversationId}/messages?ack=-1&timeout=30

  • ack=-1 activates long polling mode (waits for new messages)

  • timeout=30 sets the maximum wait time in seconds

  • When a message arrives, Salesforce returns it immediately

  • Bridged then re-establishes the long-poll connection

This pattern provides near-real-time message delivery without requiring a publicly exposed webhook endpoint.

Step 7: Configure Sync Settings

Once connected, configure the following:

Setting

Options

Description

Conversation direction

Inbound only, Outbound only, Both

Define which messages to sync

Message types

Text, Media, System events

Choose which message types to process

Transcript storage

Enabled, Disabled

Store conversation transcripts in Bridged

Pre-chat mapping

Custom

Map pre-chat fields to Bridged profile attributes

Bulk sync limit: Each bulk operation is limited to 50 records per request. For high-volume messaging, messages are processed in real-time rather than bulk.

Step 8: Test the Integration

  1. In Bridged, go to Integrations → Salesforce Messaging → Test Connection.

  2. Start a test conversation using the Salesforce Messaging API.

  3. Send a message from the simulated customer to verify inbound delivery.

  4. Send a message from Bridged to verify outbound delivery.

Testing the Conversation Flow

To start a test conversation, Bridged uses the Salesforce Messaging REST API :

bash

POST /v58.0/conversations/
Host: yourDomain.my.salesforce.com
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "messagingPlatformKey": "YOUR_MESSAGING_PLATFORM_KEY",
  "contactId": "003XXXXXXXXXXXXXXX",
  "prechatDetails": [
    {
      "label": "Email",
      "value": "test@example.com",
      "transcriptFields": ["Email__c"],
      "displayToAgent": true
    }
  ]
}

A successful response returns:

  • conversationId - Unique identifier for the session

  • token - Session-specific JWT for subsequent API calls

Common Use Cases

Playbook

Direction

Description

Activation

Outbound

Proactively engage website visitors with chat invitations

Qualification Agent

Inbound + Outbound

Automated lead qualification through conversational AI

Nurture & Conversion

Both

Sales conversations with seamless handoff to human agents

Customer Support

Both

Embed support chat in web/mobile apps with transcript sync

Conversation Lifecycle

Salesforce Messaging conversations follow a defined lifecycle :

Stage

Description

API Action

Start

Customer initiates chat

POST /conversations/

Queue

Customer waits for agent assignment

Automatic (Omni-Channel routing)

Active

Agent actively messaging

POST /messages/ and long-poll GET

Ended

Customer or agent ends session

Session status updates to "Ended"

Transcript

Conversation record available

Read from MessagingSession object

When a session ends, Salesforce triggers a record update event. Bridged can use this to capture the full transcript for storage or analysis .

Rate Limiting & Performance

  • Rate limits depend on your Salesforce edition, not on Bridged

  • Long-poll connections: Each active conversation maintains one long-poll connection

  • API calls: Messaging API calls count toward your Salesforce API daily limit

  • Concurrent conversations: Limited by your Salesforce Digital Engagement license

  • For high-volume deployments, work with your Salesforce account representative to increase limits

Security & Permissions

  • Bridged supports OAuth 2.0 JWT (preferred) and OAuth 2.0 Authorization Code

  • Session-specific tokens are used for message exchange, not long-lived access tokens

  • All API calls are made over TLS 1.2+

  • Pre-chat data can be mapped to transcript fields for compliance tracking

  • You can revoke access at any time from Salesforce Connected Apps → Bridged Messaging Integration → Revoke

Required Object Permissions

The integration user requires the following object permissions:

Object

Read

Create

Update

MessagingSession

✓

✓

✓

MessagingEndUser

✓

✓

-

Conversation

✓

-

-

Message

✓

✓

-

Troubleshooting

Issue

Likely cause

Solution

Connection fails

Invalid callback URL or OAuth config

Verify callback URL: https://gateway.bridged.media/auth/salesforcemessaging/callback

No messages received

Long-poll not established

Check that ack=-1 parameter is included in GET requests

Conversation creation fails

Missing Messaging User permission

Assign Messaging User permission set license to integration user

Transcript not available

Transcript not mapped to object

Configure transcript field mapping using Apex or Flow

Authentication error (401)

Expired session token

Session tokens are short-lived; restart conversation

Long-poll timeout

Network interruption

Bridged automatically reconnects; check network stability

Pre-chat data missing

Field mapping incorrect

Verify prechatDetails mapping in conversation start request

Transcript Mapping

Salesforce does not automatically store chat transcripts in the Messaging Session object. To enable transcript capture:

  1. Add a custom Long Text Area field to the Messaging Session object (e.g., Transcript__c)

  2. Create a Record-Triggered Flow that runs when a Messaging Session status = "Ended"

  3. Use an Apex class to retrieve and format the transcript chronologically

  4. Map the formatted transcript to your custom field

Support

For integration support, contact your Bridged account manager or email support@bridged.media.