# 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](#h_01F4SB1NR07MHSTA38R6WEPFSY) 2. [Configure the MessageBird for Salesforce app](#h_01F4SB331TCRPNGS57P90HH99Z) * [Assign permission sets](#h_01F4SCAYEARRCX9ZW1G36TA057) * [Connect Salesforce to MessageBird](#h_01F4SCC2E6P6SE3BH2S74MZXPE) * [Configure your account settings](#h_01F4SCE4YAKGS9E4JAHC9VYQ01) * [Set up webhooks](#h_01F4SCFJ79WXGARKNMG52HFH7T) * [Advanced configurations](#h_01F4SCJWAVCBNBF1BQWA9T4XBZ) * [Set up a flow in Salesforce](#h_01F4SCPCWS10X4GDXFVN6R0NNP) * [Get all MessageBird conversations](#h_01F4SCSHK9XPENAED4ZNB46VBN) * [Get all MessageBird conversation messages](#h_01F4SCTTNTCN1WYG5T4YABJDQG) * [Out-of-office messages](#h_01F4SCVQ76P72P0SDBRKKMY1K1) * [HSM Templates Integration](#h_01F4SCWG9PK40A9DDNJGZ44KED) 3. [Configuring business flows in Salesforce (optional)](#h_01F4SB49GANJK669PJKWWQSMW8) * [Assigning conversations to queues](#h_01F4SCXFZPV12HGSHK4MG1WYJG) * [Salesforce Omnichannel widget configuration](#h_01F4SCYRDT4H1GW82HFTJ9MHAR) * [Connecting SFSC to Flow Builder](#h_01F4SCZWKXVZWJVY4QWKZPTPRH) 4. [Troubleshooting](#h_01F4SD0WFEEA2PC4Z2FZF5E897) ### Requirements Before you get started, take a look at what you need to set this up. * A [MessageBird account](https://dashboard.messagebird.com/en-us/sign-up) * 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](https://help.salesforce.com/articleView?id=domain_name_overview.htm\&type=5) 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](https://appexchange.salesforce.com/mktcollections/cloud-collections/MarketingCloud) 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](#h_01F4SD868TN4TXPJZ325ZMXZN9) 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](https://dashboard.messagebird.com/) and click the [Developers](https://dashboard.messagebird.com/en/developers/settings) 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](#h_01F4SCC2E6P6SE3BH2S74MZXPE) 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](#h_01F4SCC2E6P6SE3BH2S74MZXPE) 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](https://developer.salesforce.com/docs/atlas.en-us.platform_events.meta/platform_events/platform_event_limits.htm). **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](https://www.youtube.com/watch?v=Ipdm_VD2V0E\&ab_channel=SFDCLearn%26Share),\ 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 ](https://docs.bird.com/connectivity-platform/basics/flowbuilder-steps-glossary#id-01g1jen5k3hqacptnejekwb75t)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](https://dashboard.messagebird.com/en/flow-builder). 2. Click **Import flow** and import the [template flow](https://support.messagebird.com/hc/en-us/article_attachments/360019700697/SFSC_Flowbuilder_Connector_template.json) (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. .
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.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/connectivity-platform/salesforce/how-to-set-up-the-messagebird-salesforce-sales-and-service-cloud-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.