How to set up the MessageBird Salesforce Sales & Service Cloud integration

In this guide, you’ll learn how to set up the MessageBird Salesforce Sales & Service Cloud application.

In this guide:

  1. How to get the MessageBird for Salesforce app

  2. Configure the MessageBird for Salesforce app

  3. Configuring business flows in Salesforce (optional)

  4. Troubleshooting

Requirements

Before you get started, take a look at what you need to set this up.

  • A MessageBird account

  • A Salesforce Enterprise (or higher) license with Lightning support

  • Access to the SMS and WhatsApp Business channels

  • Administrative access to Salesforce — as Salesforce for MessageBird is not a Salesforce license

  • MyDomain configured for Salesforce

  • The MessageBird for Salesforce application, installed on your Salesforce Environment

  • Your MessageBird Access Key and Signing Key

Step one: Get the MessageBird for Salesforce app

  1. Go to the Salesforce AppExchange and search for MessageBird.

  2. Choose Messagebird for Salesforce: Multichannel Conversations & Messaging.

  3. On the purchase page of the app, click Get Now in the bottom-right of your screen to purchase the app from AppExchange and start the installation.

  4. A pop-up will open. Choose whether you want to install the MessageBird package in the Sandbox or in the Production environment.

  5. Installation details will be prompted, where you can define access for this package. This means defining which Business Units the users in the SFSSC account are able to use in this package. You can install it for Admins Only (recommended), for All Users, or for specific profiles. Select the option you want, click Confirm, then click Install!

  6. A pop-up will open. The pop-up will ask you to confirm that you want to grant third-party access to MessageBird. Make sure all of the boxes are checked, click Continue to start the installation to start, and then click Done.

And that’s it! You will now be able to see the MessageBird Package on your Installed Packages.

Step two: Configure the MessageBird for Salesforce app

The custom setting Webhook Config has a Debug mode field. A default organization level value can be created with Debug mode true to create custom Debug logs for the webhook.

Assign permission sets

There are two permission sets in the package which need to be assigned to the respective users:

  • Messagebird_Admin

  • Messagebird_Standard_user

Before assigning users to the permission sets, you need to add the permission to read, create and edit Opt_Out custom object for both of them. To do this change, clone the permission set, edit them and add the users.

  • The Messagebird Admin permission set can only be used by admins. It allows them to create Configuration metadata, Webhooks, HSM templates, and look at the Debug logs (custom object). For more information about what admins can do, take a look at the configuration details below.

  • The Messagebird Standard user permission set can be used by standard users and allows them to create conversations and send messages.

Connect Salesforce to MessageBird

To connect Salesforce with MessageBird, you must set up their endpoint, access key, and other settings on the package configuration.

NOTE: A force.com presence is needed to expose the webhooks that are needed for conversation updates.

Follow these steps:

  1. Go to Setup.

  2. Click Installed packages.

  3. Click Configure.

OR

  1. Search for MessageBird Setup by typing MessageBird into the search bar and clicking MessageBird Setup.

  2. If there are no force.com sites in the org, then you’ll see the following screen:

  3. To create the force.com site, make sure that the site domain is already available and click Continue to Setup screen.

  4. Enter your site name and click Create site. This will create a custom force.com site and the permission set Webhook Assignment will assign the guest user of the site.

Configure your account settings

The Account Settings tab allows you as an admin to create configuration custom metadata records with the Access Key and Signing Key of your MessageBird account.

  1. Go to Settings and choose Setup in the top right corner.

  2. In the Quick Find in the left-hand corner of your screen, search for Packages. In the list of Packages, you should see MessageBirdPackage predefined.

  3. Click Configure.

  4. Now, you need to find your Access Key and Signing Key. Navigate to your MessageBird Dashboard and click the Developers icon on the toolbar on the left-hand side of your screen.

  5. To get your Access Key, click on API access, then select Show key. Click Copy, and paste this key into the relevant field on the Salesforce configuration page. Please use the live mode API Key for product instances of Salesforce.

  6. To get your Signing Key, click in API Settings, then select Show key. Click Copy and paste into the relevant field on the Salesforce configuration page.

  7. In the ReportURL field, enter the force.com site that you created in the Connect Salesforce to MessageBird step.

Take a look at the configuration details

Now that you’ve set this up, take a look at what your admin permissions allow you to do. To access the configuration variables, click the arrow to the right of Configuration Details.

You’ll now be able to perform the following actions:

  • Update: Updates configurations.

  • Show keys: Displays the Access and Signing keys in a human-readable format.

  • Hide keys: Obfuscates the Access and Signing keys.

  • Sync channels: Synchronizes channel information from MessageBird to the Salesforce plugin. This is a required action when you first set up the connection, and you must repeat it every time a new channel is configured on the MessageBird side.

  • Sync templates: Synchronizes WhatsApp templates from MessageBird to the Salesforce plugin. This is a required action every time new templates are created.

  • Get WhatsApp Namespace: Get the namespace for the WhatsApp channel from MessageBird. This is a required action when you first set up the connection, and you must repeat it every time the namespace information is changed on the MessageBird side.

Set up webhooks

Webhook settings

The Webhook Settings tab allows admins to create webhooks for each configuration record. To do this, follow these steps:

  1. Select the configuration record that you want to change from the drop-down menu in the Webhook Settings tab.

  2. In the Webhook URL field, enter the force.com site that you created in the Connect Salesforce to Messagebird step.

  3. The channels displayed in the drop-down menu will be those that are synced for each configuration. When you’re done, click Create Webhook.

NOTE: For a well-functioning system, you’ll need to create a webhook for each channel that you have in your MessageBird account that you want to use in your Salesforce environment.

List of webhooks

A list of webhooks is displayed in the Configurations drop-down menu. If you want to delete a webhook, you can click on the arrow next to the status of the webhook and click Delete.

Advanced configurations

The Advanced Configuration tab allows admins to choose the Browser Synchronisation Method for the conversations/messages. You can choose between Platform events or Query every X seconds.

By default, we’re using the Salesforce platform events mechanism to receive updates for messages and conversations. However, if you’re reaching the limits of your events quota, you can switch to using the query method for conversation updates.

Read more about Salesforce events limits.

NOTE: For the best user experience, with a low latency of receiving messages, use the events mechanism.

Contact phone fields

The fields in the Selected column are used to search to link the contact with the conversation when you receive incoming messages. In the following example, the Business Phone is the field that will be used to link the contact to the conversations. You can add other fields such as Business Fax, Mobile Number, Home Phone, Other Phone, and Asst. Phone. When you send outgoing messages, the application will automatically pick up the phone number from the Phone (Business Phone) field, under the Contact object.

Don’t forget to click Save when you’re finished configuring your settings!

Note about numbers

To match a contact with their respective number, we need their number to be in international format (country code included). Otherwise, the system might not be able to infer the corresponding country.

For example:

Correct US number

14088001500

Incorrect US number

4088001500

Correct Singapore number

6567355020

Incorrect Singapore number

67355020

  • For a US number: correct 14088001500, incorrect: 4088001500

  • For a Singapore number correct 6567355020, incorrect: 67355020

Set up a flow in Salesforce

To enable the application to send messages to the MessageBird conversations API, you’ll need to set up a flow.

  1. In Salesforce, go to Settings and click Setup in the top right-hand corner of your screen.

  2. In the Quick Find in the left-hand corner, search for Flows.

  3. From the list of pre-defined flows, click the Message-Send flow. The flow template will be cloned.

  4. Click Save As and enter a recognizable name for the flow.

  5. Inside your newly created flow, open the toolbox and click on the Manager tab.

  6. Under the Variables menu, click on Configuration name.

  7. In the Default Value field, change the ‘ConfigurationName’ to the one that is configured in the MessageBird Setup tab.

  8. Click Done to activate your flow!

Adding a Lightning component to the Conversation detail page

  1. In Salesforce, open any Conversation Record Detail page.

  2. Go to Settings.

  3. Click Edit page.

  4. Scroll down to find the Custom tab.

  5. Select the Send Messages component and drag it to your page.

Adding a Lightning component to the Contact detail page

  1. In Salesforce, open any Contact Record Detail page.

  2. Go to Settings.

  3. Click Edit page.

  4. Scroll down to find the Custom tab.

  5. Select the Contact Conversation View component and drag it to your page.

Get all MessageBird conversations

To bring all of your MessageBird conversations into Salesforce, we run a batch process in the developer console. You’re required to do this operation the first time that you install the plugin (to retroactively get existing conversations).

  1. Click the gear icon on the top-right hand corner of your page.

  2. Click developer console.

  3. Copy-paste the code. It will look similar to this:

mbird.GetAllConversationsBatch c1 = new mbird.GetAllConversationsBatch();
c1.configurationName = ‘mbird__MessageBird'; //QualifiedApiName of the configuration created in the setup screen.

Database.executeBatch(c1);

Get all MessageBird conversation messages

To bring all of your MessageBird conversation messages into Salesforce, we run a batch process in the developer console.

  1. Click the gear icon on the top-right hand corner of your page.

  2. Click developer console.

  3. Before getting all the messages, run the batch to get all conversations, as we get messages for each conversation in this batch.

  4. Copy-paste the code. It will look similar to this:

mbird.GetAllMessagesBatch c2 = new mbird.GetAllMessagesBatch();
c2.configurationName = ‘mbird__MessageBird'; //QualifiedApiName of the configuration created in the setup screen.

Database.executeBatch(c2);

Out-of-office messages

To send out-of-office messages to your customers, set up business hours in the org, and connect it to your channels with an out-of-office message.

  1. In Salesforce, go to Setup.

  2. Search for and click on Business Hours.

  3. Configure your business hours as required.

  4. Go to the Channels tab and select the Channel record for which you want the out-of-office message to be sent.

  5. Enter the modified business hours record in the Business Hours field and enter your message in the Out of Office Message field.

HSM Templates Integration

To create HSM templates in Salesforce and send them for approval, follow these steps:

  1. Go to the HSM Template Headers tab and create a new record. Choose your category and language policy.

  2. Go to the related list and create new HSM Template records for the different languages with Language and Template content.

  3. Keep in mind that the accepted templates will be shown in the conversation component to send messages.

  4. Once you’ve created the HSM Template records, click on the Integrate quick action on the HSM Template Header page for approval.

  5. For each HSM Template, go to the related list and enter the Parameter Records to add them in the template message.

  6. The field Source Text is a constant text value and Source Field is the field name of the object.

  7. The Order field is the order in which the parameters in the template are replaced. For example, in the template is ‘Hi {{1}}’ with a related parameter, Source text ‘Teja’ and order ‘1’, the parameter record with order 1 will replace {{1}} in the template when the message is sent to the customer as ‘Hi Teja’.

Configuring business flows in Salesforce (optional)

These settings are not required, they’re suggestions for ways that you can connect conversations with your agents. Feel free to skip these and stick with your company’s existing processes.

Assigning conversations to queues

If your support system operates based on queues (not a must, but this is a typical way of managing support), then a process is needed to ensure that new conversations are assigned to the appropriate queue.

Defining the queue

If you are using queues, you need to define who is part of the queue.

Setting up Omnichannel - Simple, least Active routing

You could set Omnichannel up to serve your needs better, but that is beyond the scope of this document.

  1. Enable Omnichannel Setup -> Omnichannel -> Omnichannel settings and mark the checkbox Enable Omnichannel and Save.

  2. Set up your Service Channel in Setup -> Omnichannel -> Service channels Click on new

  3. Put the name and the Developer name Eg: Case Queue. Add Case as the Salesforce Object and save.

  4. Create Routing Configurations put the name and developer name, set routing priority to 1, and set Units of Capacity to 1.

  5. Create a new Queue in Users-> Queue, set the label and name and developer name, write down this developer name you will need it later, assign the routing configuration you created, and add Case to the supported objects. Add all the users you want on your queue, they should have access to the Salesforce Messagebird Package, and then save.

  6. Setup presence configurations in Omnichannel -> Presence configuration add the name and the capacity, the number of cases each agent can work on simultaneously, leave all other defaults and click save.

  7. Create Presence Statuses in Omni-channel -> Presence Statuses you will need to create at least 2. One online and assign the Case queue, and one offline.

  8. Enable the Omnichannel UI go to Setup->App Manager, select the app you use for Service Console and click on Edit. Inside click on Utility Items, add Utility Item and the Omni-channel.

You are finished with the omni channel, but now you have to set up the flow that assigns the case to the correct queue.

Setup Flow

  1. If you are not familiar with Queue based routing, please watch this video, Set up the template flow: Create a Case from the new MB Conversation:

  2. You should add a Get Record element add the name Find Queue and add the object [Group Group]

  3. Select the Developer Name field and set it equal to the developer name setup in step 5 in the previous section of this guide.

  4. Once there, you will have two paths to follow to configure the trigger.

    1. If you want to use Messagebird Flow Builder to mark conversations as managed by Salesforce, your trigger should be configured like this

    2. If you don’t use Messagebird Flow Builder, it should be configured like this:

  5. In both cases, the case creation should be configured like this, the owner id is the previously retrieved Queue by developer name, and the contact should be the one associated with the conversation

  6. Finally, you save and Enable the flow.

Finally, go to your Cases Layout and add the Case Conversation View component.

Now, every new conversation should create a case that gets routed to your agents with a notification, and you should be able to continue the conversation from there.

Connecting SFSC to Flow Builder

Connecting SFSC to Flow Builder will allow for the definition of more complex scenarios like:

  1. A contact reaches out.

  2. The message is received inside Flow Builder, where automatic qualification and deflection happens.

  3. Once no further deflection is possible, it is signaled to SFSC that an agent needs to be involved.

  4. The conversation is handed over to SFSC and the agent receives a notification inside the Omnichannel widget.

  5. The agent engages with the contact.

  6. Once the conversation is over and the agent marks the conversation as closed (archives it), control is returned to Flow Builder.

  7. Further automation can then be performed (e.g. send an NPS survey to the contact).

To achieve this a couple of steps are needed both on the Salesforce side and on the Flow Builder side.

Set it up in Flow Builder

  1. Log in to your MessageBird Dashboard and navigate to Flow Builder.

  2. Click Import flow and import the template flow (see article attachment).

  3. For the Fetch variables steps, replace the salesforceInstanceBaseLink with the proper link to your Salesforce instance, which is the same root as your Salesforce report URL (e.g. https://messagebird-tso-1783cbe360c.secure.force.com).

  4. Select the Await webhook and copy the webhook address.

  5. Ensure that this link is passed as a parameter to the second Fetch variable step.

  6. Connect the Flow as a listener to the channels for which you want to enable Flow Builder deflection by selecting the proper channels in the flow’s trigger. NOTE: You should select any of the SMS or WhatsApp channels.

  7. On the last HTTP Request step, update the Access Key used to authorize the request with your sandbox’s live API key.

Set it up in Salesforce

  1. Inside the MessageBird’s package settings, under the advanced settings tab, ensure that the Use Flow Builder checkbox is enabled.

  2. In the Salesforce flows or process you have defined to assign conversations to queues and agents add an additional condition, “conversations is in Salesforce”, based on the with_Salesforce__c conversation parameter. By adding this extra condition, we will ensure that the Salesforce agents only get notified once the Flow Builder signaled to Salesforce that conversation automation has ended and an agent must now be notified.

Troubleshooting

Error message when archiving

When attempting to Archive a conversation I am getting a “There was an error when trying to archive the conversation. Contact your administrator.” error message.

Cause and solution

This will happen if the Salesforce agent attempts to Archive a conversation that is currently not in Salesforce (but is in Flow Builder). The Archiving action will work only once the conversation has been passed to Salesforce.

No action is required regarding this message.

PrevioussalesforceNextsending-sms

Last updated