Qualtrics Platform
Customer Journey Optimizer
XM Discover
Qualtrics Social Connect

Integrating with Qualtrics Social Connect

About Integrating with Qualtrics Social Connect

Attention: At this time, we are not onboarding new users to Qualtrics Social Connect.

Integrating with Qualtrics Social Connect enables you to consolidate and analyze all of your digital customer feedback in one place. You can then analyze your data using any Qualtrics analysis method, including Text iQ in a CX dashboard.

Attention: Custom coding features are provided as-is and require programming knowledge to implement. Qualtrics Support does not offer assistance or consultation on custom coding. You can always try asking our community of dedicated users instead. If you’d like to know more about our custom coding services, please contact your Qualtrics Account Executive.

Step 1: Creating the Authorization Header

This section covers how to create the authorization header for the integration. You’ll need this for setting up the integration with Qualtrics Social Connect.

Go to Account Settings.
Navigate to the Qualtrics IDs section of your account and copy your API token. If you already have an API token, do not generate a new one.
Make note of your Qualtrics username. Usually, this is the email address you use to log in to Qualtrics. If you do not know your Qualtrics username, contact your Brand Administrator.
Using your Qualtrics username, construct a credentials string using the following format:
<Your Qualtrics Username>:<Your Qualtrics API Token>.

Qtip: If you use SSO to log in to Qualtrics, make sure to include the # component of your username.
Example: An example credential string is:
```
barnaby@qualtrics.com:63V9BuO9wMyvgo9HOf1OpeTOrhkvYGiRx1yMGrki
```
Encode the credential string with base64 encoding. You can use any base64 encoder online to accomplish this.
Example: My base64 encoded credential string is:
```
YmFybmFieUBxdWFsdHJpY3MuY29tOjYzVjhCdU85V015dmcwOUlPZjFPcDhUT3Joa3ZZR2lSeDF5TUdaa2k=
```
Construct the authorization header in the following format: Basic <base64 encoded credentials>. Note the space between “Basic” and the credentials.
Example: My final authorization header is:
```
Basic YmFybmFieUBxdWFsdHJpY3MuY29tOjYzVjhCdU85V015dmcwOUlPZjFPcDhUT3Joa3ZZR2lSeDF5TUdaa2k=
```

You’ll need this authorization credential in the next section. Copy it down somewhere easily accessible.

Step 2: Creating an Automation in Qualtrics Social Connect

This section covers the initial setup you’ll need to complete in Qualtrics Social Connect to set up the integration. To begin the setup, you’ll first need to create a workflow in Qualtrics.

Qtip: For help with Qualtrics Social Connect, contact the team by logging into your Qualtrics Social Connect account, clicking the profile icon, and selecting Contact support.

In Qualtrics, go to Workflows.
Click Create a workflow and then Started by an event.
Choose the JSON Event.
Click Copy URL to copy the event endpoint. You’ll need this event endpoint to complete the setup in Qualtrics Social Connect. Save it somewhere you will be able to access it later.
In a new browser tab, log in to Qualtrics Social Connect.
Qtip: Qualtrics Social Connect uses separate credentials from your Qualtrics account. Contact the Social Connect support team if you have questions about accessing Qualtrics Social Connect.
Go to Account Settings.
In the Overview tab, select Automation Recipes.
In the On Case Update section, click Add Automation Recipe.
Give your automation recipe a name.
Ensure Mention is selected in the Trigger section and select Was created from the dropdown menu.
Click the plus sign ( + ) to choose one or more topics to monitor.
In the Filter section, configure the filtering rules for the mentions you want to monitor.
In the Action section, select Trigger Webhook from the dropdown menu.
In the URL field, paste the event endpoint you copied in step 4.
In the Authorization Header field, paste the authorization header you created earlier.
If you are using an API call to retrieve tags, enable the Delay option. It’s recommended to set a minimum delay of 10 minutes to ensure the tags have had the time to be attached to the mentions.
Click Add to complete the setup.

To test the connection, generate a new mention (the way to generate the mention will depend on your source, such as creating a new tweet or leaving a comment). Alternatively, you can wait for the next post when it happens naturally. Once the new mention has been generated, open up the JSON event in your Qualtrics workflow and look at the JSON properties that were captured by the event:

Qtip: Some of the fields that are returned from Qualtrics Social connect may need to be cleaned up to be usable in Qualtrics. You can use the stripped_content field of the Mention object to import the field without HTML formatting.

Step 3: Creating the Qualtrics Dataset

To save the data in Qualtrics, you must create a Qualtrics dataset. You can create a Qualtrics dataset by calling Dataset API directly from the command line.

Open a text editor and construct the API command. The general format is below:

curl -X POST https://brandID.qualtrics.com/API/v3/datasets -H "Content-Type: application/json" -H "X-API-TOKEN: Your Qualtrics API Token"  -d '{

"name": "Choose a name for your dataset",

"primaryKey": "Choose ID column name",

"createProject": true,

"fields": [

{

"name": "Same ID column name as above",

"type": "string"

}

]

}'

In the above API command, you need to replace the following values:
- brandID: Your Qualtrics organization ID.
- Your Qualtrics API Token: Your API token.
- Choose a name for your dataset: Enter a name to give the dataset.
- Choose ID column name: Specify the field name that will contain your project’s identification key. We recommend using “uniqueId.”
Open Terminal on your computer and paste the command. Press Enter to run the command.

Copy the dataset ID from the result. You will need this later. The result from the API call will be in the following format:

{"result":{"name":"<Name of your dataset>","primaryKey":"<id field that you defined>","datasetId":"dataset ID, this is what you need to copy","fields":[<list of fields that you defined>]},"meta":{"requestId":"<internal request ID>","httpStatus":"200 - OK"}}

Once you’ve created your dataset, it will be available in the Qualtrics Projects page as an imported data project. Click on your project to open it.
After opening your imported data project, you can then use the field editor in the Data & Analysis tab to add the fields that you want to import from Social Connect. See Common Social Connect Fields for more information about the fields available to you. When adding your fields, we recommend you save them as an open text type in your dataset.

Step 4: Completing the Workflow

Now that you’ve established a connection with Qualtrics Social Connect and created your dataset, it’s time to map data from Qualtrics Social Connect to your dataset.

Open the workflow you created earlier.
Click the plus sign (+) and select Task.
Choose the WebService task.
Select Authenticated web service.
Click Next.
Click Add a user account.
Give your account a Name. This is for your own organizational purposes.
Choose OAuth for the connection type.
Choose Client credentials for the grant type.
Enter your Client ID and Client secret. See API OAuth for more information on how to create these.
Paste the following URL into the Token endpoint: https://BrandID.DatacenterID.qualtrics.com/oauth2/token
- Replace the bolded text above with the corresponding IDs:
- BrandID: Your Qualtrics organization ID.
- DatacenterID: Your Qualtrics datacenter ID.
Click Connect account.
Choose your newly added account.
Click Next.
Select POST for the request type.
Enter the URL in the following format:
```
https://brandID.qualtrics.com/API/v3/datasets/DatasetID/data
```
Where brandID is your Qualtrics brand ID and DatasetID is the dataset ID you copied earlier.
In the Headers section, add Authorization as a Key.
For the Value, enter Bearer and add a trailing space.
Click the piped text icon, {a}, and choose your QSC account.
In the Body section, select JSON Key-value pairs and begin mapping your fields. For the Key, enter the field name. For the value, use piped text to select the field coming directly from the JSON event. The Common Social Connect Fields section has the piped text code for untransformed data from Social Connect.
When finished, click Save.

Step 5: Analyzing Qualtrics Social Connect Data

This section covers how to analyze your Qualtrics Social Connect data in CX dashboards and Text iQ.

Displaying Social Connect Data in CX Dashboards

Create a new dashboard in a CX dashboard project.
Click Add Source, hover over External data sources, and then select the project containing your social connect data.
Adjust the field types for your imported fields. See Common Social Connect Fields for more information about the suggested field type for each dataset field.
Save your changes when done.

Editing your dashboard is the same as editing any CX dashboard. Check out the following support pages to learn more:

Using Text iQ

We recommend you use the Text iQ in your CX dashboard. This will ensure that all of your data is in one place, and your Text iQ fields will be automatically mapped to your dashboard if you analyze them via the dashboard. When you’re ready to get started, click the Analyze in Text iQ button on your dashboard.

Most mention fields won’t be useful for text analysis (e.g., author, source, id, etc). When choosing the data to import into Text iQ, make sure to select the message content field.

Using Text iQ for social connect data works the same way as analyzing survey response text in Qualtrics. Check out the following support pages to learn more:

Importing XM Discover Enrichments

Qtip: If you do not already have Discover category models set up, the default category models are used. See this Discover support page for more information about the default category models.

This section covers how to import XM Discover enrichments into your dataset. While not mandatory to integrate with Qualtrics Social Connect, XM Discover enrichments help you analyze your mentions in real time by tagging them based on the mention’s content.

In Social Connect, go to Tags.
Click Add XM Discover Enrichment.
Choose the topic(s) you’d like to add enrichments for.
Click Next.
Choose the category models you’d like to use.
Qtip: There is a limit of 2 categories per topic. If you need more than that, contact the Social Connect team by logging into your Qualtrics Social Connect account, clicking the profile icon, and selecting Contact support.
.
For Real-time Enrichment, select Yes.
Attention: If you do not enable real-time enrichment, the XM Discover enrichments will be processed with a delay of 7 or more minutes after the mention is created in Social Connect and therefore the corresponding tags won’t be available in your Qualtrics workflow.
Click Save.

Return to your workflow in Qualtrics. Make sure to map your fields in your Qualtrics workflow to save the XM Discover enrichments to your Qualtrics dataset. These are saved as the tags field.

Since XM Discover Enrichments are exported as a comma separated list, you will need to specify the field delimiter in your dashboard by using the recode editor. Make sure to select Comma as your delimiter. You can also rename your fields using the recode editor to make them more friendly for viewing in the dashboard.

Common Social Connect Fields

This section contains a table of commonly used fields from Social Connect, their piped text code for building your mapping, the field type you should save them as in Qualtrics, and any special notes about the field.

Dataset Field Name	Piped Text Path (for workflow mapping)	Dashboard Field Type	Description & Special Notes
id	~{aed://id}	Text Value	Qualtrics Social Connect specific Identifier for this mention (unique per topic).
uniqueId	~{aed://unique_id}	Text Value	Qualtrics Social Connect specific Identifier for this mention.
authorName	~{aed://author.name}	Text Value	Username or handle of the author of the mention.
authorFullname	~{aed://author.fullname}	Text Value	Full name of the author of the mention.
authorId	~{aed://author.id}	Text Value	Service specific identifier of the author (eg. Twitter UID)
originalAuthorName	~{aed://original_author.name}	Text Value	Username or handle of the original author of the mention. (In case this is a retweet, repin, …)
originalAuthorFullname	~{aed://original_author.fullname}	Text Value	Full name of the original author of the mention.
originalAuthorId	~{aed://original_author.id}	Text Value	Service specific identifier of the original author (eg. Twitter UID).
messageTitle	~{aed://message.title}	Open Text
messageContent	~{aed://message.content}	Open Text	The content is in HTML format. You may want to use a code task to remove any HTML or emojis.
messageLanguage	~{aed://message.language}	Text Set	ISO 639-1 language code of the language this message is in.
messageSentiment	~{aed://message.sentiment}	Text Set	Any of positive, negative, neutral or unset.
messageType	~{aed://message.type}	Text Set	Type of message. Possible values: “post”, “privatemessage”, “video”, “checkin”, “photo”, “text”, “quote”, “link”, “chat”, “audio”, “email”, “review”, “applause”, “like”, “retweet”, “shared”, “repin”, “user_favorite”, “reblog”, “engagement”, “comment”, “reply”, “tips”, “question”, “answer”, “postcard”, “listed”, “case”, “live_chat”, “document”, “user_tweet”, “user_mention”, “normal”, “other”.
sourceCategory	~{aed://source.category}	Text Set	Category this mention can be classified under. Possible values: “social”, “social_videos”, “social_photos”, “microblogs”, “forums”, “blogs”, “podcasts”, “comments”, “news”, “news_academic”, “news_consumer”, “news_corporate”, “news_government”, “news_journal”, “news_local”, “news_national”, “news_organisation”, “news_presswire”, “news_trade”, “wikis”, “reviews”, “qa”, “locations”, “apps”, “products”, “shops”, “classifieds”, “email”, “case”.
sourceService	~{aed://source.service}	Text Set	What “connected service” source the mention is coming from. Possible values: “twitter”, “facebook”, “facebook_ads”, “foursquare_venue”, “googleplus”, “instagram”, “instagram_hashtag”, “instagram_ads”, “linkedin_group”, “pinterest”, “rss”, “youtube”, “mixcloud”, “telegram_bot”, “tripadvisor”, “tumblr_blog”, “soundcloud”, “vimeo”, “linkedin_company”, “lithium”, “yelp_business”, “keywordsearch”, “mailservice”, “telligent_forum”, “instagram_business_profile”, “instagram_business_profile_hashtag”, “wechat”, “twilio”, “web”, “whatsapp”, “viber”, “linkedin_company_v2”, “apple_business_chat”, “gominga_locations”, “gominga_apps”, “gominga_products”, “gominga_shops”, “email_mailbox”, “ditto_brand”, “social_case”, “social_document”, “ios”, “android”, “custom”.
sourceType	~{aed://source.type}	Text Set	What source the mention is coming from. (Internal name for filtering.) Possible values: “SearchProviderFacebook”, “SearchProviderFacebookAds”, “SearchProviderTwitter”, “SearchProviderGoogle”, “SearchProviderGooglePlus”, “SearchProviderFoursquare”, “SearchProviderInstagram”, “SearchProviderInstagramBusinessProfile”, “SearchProviderInstagramAds”, “SearchProviderInstagramHashtags”, “SearchProviderLinkedInGroups”, “SearchProviderLinkedInCompanies”, “SearchProviderLinkedInCompaniesV2”, “SearchProviderRss”, “SearchProviderOmgili”, “SearchProviderMoreOver”, “SearchProviderTrendiction”, “SearchProviderYahoo”, “SearchProviderWordpress”, “SearchProviderBing”, “SearchProviderYoutube”, “SearchProviderCustom”, “SearchProviderApi”, “SearchProviderPinterest”, “SearchProviderMixCloud”, “SearchProviderTripadvisor”, “SearchProviderTumblr”, “SearchProviderVimeo”, “SearchProviderSoundCloud”, “SearchProviderEmail”, “SearchProviderLithium”, “SearchProviderYelp”, “SearchProviderCase”, “SearchProviderDocument”, “SearchProviderTelegramBot”, “SearchProviderTelligent”, “SearchProviderWeChat”, “SearchProviderTwilio”, “SearchProviderWeb”, “SearchProviderWhatsApp”, “SearchProviderViber”, “SearchProviderAppleBusinessChat”, “SearchProviderGomingaLocations”, “SearchProviderGomingaApps”, “SearchProviderGomingaProducts”, “SearchProviderGomingaShops”, “SearchProviderIos”, “SearchProviderAndroid”.
sourceId	~{aed://source.id}	Text Value	Identification of this message on the service it’s from. (Eg. the tweet ID for a Twitter message.)
sourceUrl	~{aed://source.url}	Text Value	The URL of the message on the service it’s from. (E.g. the link to the comment on Facebook itself.)
locationContinent	~{aed://location.continent}	Text Set	Continent code.
locationCountry	~{aed://location.country}	Text Set	ISO 3166-1 country code.
locationCity	~{aed://location.city}	Text Value	Full name of the city.
locationRegion	~{aed://location.region}	Text Value
tags	~{aed://tags}	Multi-Answer Text Set	Array of strings; (smart) tags added to this mention.
topicId	~{aed://topic.id}	Text Value
topicName	~{aed://topic.name}	Text Value
status	~{aed://status}	Text Set	Status corresponds to the stage in the workflow a mention/case is currently in. Possible values: “done”, “pending”, “new”.
permalink	~{aed://permalink}	Text Value	Qualtrics Social Connect specific-url unique to this mention.
dateAdded	~{aed://date.added}	Text Value	UNIX Timestamp (in UTC) of when the post was indexed by Qualtrics Social Connect. If using this field, you will want to use a code task to transform the date into a more user friendly format. Alternatively, you can use the default Recorded Date that will be created when the post is imported into Qualtrics, since the datetime will be approximately the same.
datePublished	~{aed://date.published}	Text Value	UNIX Timestamp (in UTC) of when the post was published. You probably want to use Code task piped text with formatted date instead.
priority	~{aed://priority}	Text Set
tags		Multi-Answer Text Set	Array of strings; (smart) tags added to this mention. Smart tag data is not sent through webhooks. It will not be in the payload of the Mention object. They can only be retrieved via an API call.