> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sinch MessageMedia

> Activate your full customer dataset for SMS and WhatsApp campaigns. Keep contacts and audience lists in Sinch MessageMedia in sync with the data your marketing team relies on, so every send is targeted at the right people with the right context.

## Supported syncing

| Sync type | Description | Supported sync modes | API reference |
| - | - | - | - |
| [**Contacts**](#sync-contacts) | Upsert contact records (phone numbers and attributes) into Sinch's contact directory. | Upsert | [Contacts API](https://developers.messagemedia.com/) |
| [**Contact lists**](#sync-contact-lists) | Sync Hightouch audiences into long-lived Sinch contact lists. | Add, Remove | [Contact lists API](https://developers.messagemedia.com/) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Sinch MessageMedia

To connect Sinch MessageMedia to Hightouch you need an API key and API secret from your Sinch HUB account. Hightouch authenticates each request with HTTP Basic auth.

1. Go to the [Destinations overview](https://app.hightouch.com/destinations) page and select **Add destination**.
2. Select **Sinch MessageMedia** from the destination catalog.
3. Enter the following credentials, then select **Continue**:

   * **API key**: the API key from your Sinch HUB account.
   * **API secret**: the API secret from your Sinch HUB account.

> [!NOTE]
>
> The destination targets the Sinch MessageMedia HUB Contacts API
> (`api.messagemedia.com`). It does not currently authenticate against the Sinch
> CEP Campaigns API hosts.

## Sync configuration

### Sync contacts

Upsert contact records into your Sinch contact directory. Each row in your model becomes a contact identified by phone number.

#### Sync mode

Contacts syncs run in **Upsert** mode. Hightouch creates new contacts that aren't already in Sinch and updates existing contacts when fields change.

> [!NOTE]
>
> Sinch's HUB API returns a 409 conflict if a contact's phone number or alias is
> already in use by a different record. Hightouch surfaces these conflicts as
> rejected rows in the [Live debugger](https://docs.hightouch.com/syncs/debugger.md) rather than aborting the
> sync.

#### Record matching

Map a model column to **Phone number (msisdn)**. Sinch matches contacts by phone number, in international format (`+E.164`).

#### Channel configuration

Sinch contacts each have one or more channels. Hightouch sends the mapped phone number on every row's primary channel using the type and subscription state configured here:

| Field | Description |
| - | - |
| **Channel type** | The channel to associate with the phone number. Choose **SMS** (default) or **WHATSAPP**. Sinch's account-level validator rejects other values. |
| **Default subscription state** | The subscription state applied when a row has no subscription-state column, or its value isn't recognized. Choose **SUBSCRIBED** (default) or **UNSUBSCRIBED**. |
| **Subscription state column** | Optional. Map a column to set each contact's subscription state from source data — for example, to drive a preference-management workflow. |

For preference management, map the **Subscription state column** so subscribe and unsubscribe come from your warehouse per contact instead of a single sync-wide default. The column value is matched case-insensitively and accepts `SUBSCRIBED`/`UNSUBSCRIBED`, `true`/`false`, `t`/`f`, `yes`/`no`, and `1`/`0`. Any unmapped, empty, or unrecognized value falls back to the default subscription state.

#### Field mapping

Map source columns to Sinch's standard contact fields:

| Destination field | Type | Notes |
| - | - | - |
| **First name** | string | |
| **Last name** | string | |
| **Alias** | string | Must be unique across your Sinch account. Duplicate aliases return 409. |
| **Date of birth** | date | |
| **Country** | string | |
| **State** | string | |
| **Location** | string | |
| **Note** | string | |

To send fields that aren't in this list, configure them as **Custom fields** below.

#### Custom fields

Map model columns to custom fields configured in your Sinch HUB account. Hightouch fetches your account's custom field definitions and shows them in the dropdown — you map a source column to a specific Sinch custom field UUID.

> [!TIP]
>
> Create the custom fields in Sinch HUB before configuring the mapping.
> Hightouch only lists custom fields that already exist in your account.

### Sync contact lists

Sync a Hightouch audience into a long-lived Sinch contact list. Best for reusable, consented populations that drive recurring campaigns.

> [!WARNING]
>
> Contact list syncs require contacts to **already exist in Sinch**. Sinch's
> membership endpoint accepts contact UUIDs only, so run the
> [Contacts](#sync-contacts) sync first to create the contacts you want to add.
> A phone number that Sinch has no contact for is rejected rather than created.

#### Choose a contact list

Select an existing Sinch contact list, or create a new one from the sync configuration form. Hightouch fetches your account's contact lists and lets you pick one.

#### Record matching

Match each row to a Sinch contact in one of two ways:

* **Phone number (msisdn)** — Map a column of phone numbers in international format (`+E.164`). Hightouch looks each number up on the selected channel type and uses the matched contact. This is the simplest option when your warehouse doesn't store Sinch UUIDs.
* **Contact UUID (contact\_id)** — Map a column of Sinch contact UUIDs. Use this when you already have the UUIDs, typically written back from the [Contacts](#sync-contacts) sync.

When matching by phone number, set **Channel type** to the channel the numbers belong to (**SMS** by default). Rows whose phone number has no matching Sinch contact are surfaced as rejected rows in the [Live debugger](https://docs.hightouch.com/syncs/debugger.md).

#### Delete behavior

Choose how Hightouch treats rows that leave your audience query results:

| Behavior | Description |
| - | - |
| **Do nothing** (default) | Leave the contact's list membership unchanged. |
| **Remove from list** | Remove the contact from the Sinch contact list. The contact itself is not deleted from Sinch's contact directory. |

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

### Validate your setup

After your first sync completes:

* Open your Sinch HUB account and search the contact directory for one of the phone numbers you synced. Confirm that the contact appears with the expected channel type, subscription state, and mapped fields.
* For contact list syncs, open the target list in Sinch HUB and confirm the expected contacts are members.
* Check the [Live debugger](https://docs.hightouch.com/syncs/debugger.md) for rejected rows. The most common rejections on contact syncs are 409 conflicts caused by duplicate aliases or phone numbers already attached to a different contact.

### Recommended workflow

1. Build a Contacts sync that upserts phone numbers and attributes into Sinch. For preference management, map a subscription-state column so each contact's subscribe or unsubscribe state comes from your warehouse.
2. Build a Contact lists sync that drives list membership from your audiences. Match on the phone number to reuse the same identifier as the Contacts sync, or on the Sinch UUID if you write those back to your warehouse.