Superchat

​

Overview

Superchat is a customer messaging platform that brings WhatsApp, Instagram, SMS, email, and live chat into one shared inbox. With the Superchat destination, you can sync contacts and their custom attributes from your warehouse, and keep Superchat contact lists matched to your audiences so broadcasts and automations reach the right people.

​

Supported syncing

For more information about sync modes, refer to the sync modes docs.

​

Connect to Superchat

Hightouch connects to Superchat with a workspace API key. You must be signed in to Superchat as an administrator to view it. In Superchat, go to Settings > Integrations > API and copy the API key. Enter it as the API key when you set up the destination in Hightouch. The key has read and write access to the whole Superchat workspace. When you test the connection, Hightouch reads your custom attributes and contact lists to confirm the key works. If the test reports that Superchat rejected the API key, check the key and confirm that API access is included in your Superchat plan.

​

Sync configuration

​

Contacts

Use Upsert when Hightouch should create missing contacts and update existing ones. Use Update when Hightouch should only change contacts that already exist in Superchat. Hightouch rejects rows without a matching contact. Use Insert to create a new contact for every row without looking for an existing one. Superchat rejects a new contact whose email or phone number already belongs to another contact, so use Insert only when your rows are new to Superchat.

​

Add contacts to a contact list

Select Create a new contact list or Use an existing contact list to add every synced contact to a Superchat contact list, for example to target an audience with a broadcast. Select Don’t add to contact list to only create and update contacts. When you create a new list, Hightouch creates it on the first sync run with the name you enter, or your model’s name if you leave it blank. If a list with exactly that name already exists, the sync fails with an error instead of reusing it. Select the list with Use an existing contact list, or enter a different name. Hightouch adds each contact to the list every time it syncs the contact, and adding a contact that’s already on the list has no effect. To remove contacts when they leave your model, see Configure delete behavior.

​

Record matching

In Upsert and Update modes, Hightouch matches rows to Superchat contacts by Email or Phone. Superchat matches these values exactly, so Hightouch formats them the way Superchat stores them before searching:

• Emails are trimmed and lowercased.
• Phone numbers are converted to E.164 format, such as +447700900123. Numbers without a country code use the default country you select.

Superchat requires every email and phone number to be unique across the workspace, so each value matches at most one contact.

​

Map fields

Map Email, Phone, or both. A new contact needs at least one of them, and Hightouch rejects rows that have neither. You can also map First name, Last name, and Gender. Gender accepts male, female, diverse, or unknown. Superchat stores a contact’s emails and phone numbers as a list. When a synced email or phone number differs from what the contact already has, Hightouch adds it to the contact and keeps the existing ones. Hightouch doesn’t remove an email or phone number from a contact. Under Which custom attributes do you want to sync?, select from your Superchat contact attributes. Create an attribute in Superchat before syncing to it. Read-only attributes, which only a Superchat integration can set, aren’t listed. Hightouch converts each value to the attribute’s type and rejects rows whose value doesn’t fit: Superchat clears an attribute that receives a value of the wrong type instead of returning an error, so Hightouch checks values before sending them. A NULL custom attribute value clears that attribute on the contact. Superchat ignores empty names and genders, so a NULL First name, Last name, or Gender leaves the existing value unchanged.

​

Configure phone number formatting

Hightouch asks for a default country when Phone is your match key or a mapped field. Superchat only accepts phone numbers in E.164 format, so Hightouch converts every phone number before syncing and uses the default country for numbers that don’t include a country code. You can select one country for all rows or a column that holds each row’s country. A number Hightouch can’t parse is sent as it is, and Superchat rejects the row.

​

Configure delete behavior

Select what happens to contacts that leave your model. Hightouch never deletes Superchat contacts. Delete behavior isn’t available in Insert mode.

• Remove the Superchat record from the specified audience — Removes the contact from the sync’s contact list. The contact, its attributes, and its other list memberships stay in Superchat. This is the default when the sync adds contacts to a list.
• Clear fields that are being synced to in Superchat record, but do not delete — Clears the mapped custom attributes on the contact. Names, gender, emails, and phone numbers aren’t cleared, and the contact stays on the contact list.
• Do nothing — Leaves the contact unchanged. This is the default when the sync doesn’t use a contact list.

​

Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the live debugger. To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up sync alerts. If you run into an issue this page doesn’t cover, .

​

Behavior and limitations

• Large syncs are slow because of Superchat’s rate limit. Superchat allows 2,500 API requests per 5 minutes for each workspace, shared by every API key and integration in that workspace. Superchat has no batch endpoints, so each contact takes two to three requests: a search, a create or update, and a list addition when the sync uses a list. Hightouch paces its requests to stay under the limit, which puts a first sync of 100,000 contacts at roughly eight hours. Later runs only send rows that changed in your model, and Hightouch skips the update when a contact already has the synced values.
• Contacts collect emails and phone numbers. Because Hightouch adds new emails and phone numbers without removing old ones, a contact whose email changes in your warehouse keeps both addresses in Superchat.
• An email or phone number can belong to only one contact. If a synced email or phone number already belongs to a different contact, Superchat rejects the row.

​

Validate your setup

After your first sync completes, search for a synced contact in Superchat by email or phone number, and confirm its name and custom attributes match your model. If the sync uses a contact list, open the list in Superchat and confirm the synced contacts appear on it.