# Working with customers communication

## Intro

Use case description of how to use the customers communication collection to manage customer communication preferences and create communication messages via the Open API.

This collection supports two core scenarios:

- Consent and preference management (read and update)
- Outbound communication creation (existing or new communication thread)


## Relevant Endpoints

- [GET communication preferences](../openapi/openapi/customers-communication/getCommunicationPreferences)
- [PUT update communication preferences](../openapi/openapi/customers-communication/updateCommunicationPreferences)
- [POST create communication in existing communication thread](../openapi/openapi/customers-communication/createCommunicationInExistingCommunicationThread)
- [POST create communication in new communication thread](../openapi/openapi/customers-communication/createCommunicationInNewCommunicationThread)


## Customers communication in our platforms

The customers communication collection is designed to help partners integrate communication flows while keeping consent handling aligned with studio-side settings.

Core behavior:

- Communication preferences define whether and how communication can be sent.
- Communication messages can be posted into existing threads or started as new threads.
- Integrations should treat preferences as an authoritative constraint for outbound communication behavior.


Typical partner scenarios:

- Preference center in member app or portal
- Marketing and service communication orchestration
- Customer support follow-ups linked to existing thread history


## Preferences and communication flow

### 1. Retrieve communication preferences

Use GET communication preferences before rendering communication settings or triggering campaigns.

Use this to:

- show current channel/category choices
- determine whether a channel is currently active
- prefill preference settings in your UI


### 2. Update communication preferences

When a customer changes consent or channel settings, call PUT update communication preferences.

Best practice:

- submit only intended changes
- show explicit confirmation before save
- refresh preferences after update


### 3. Create communication in an existing thread

If communication belongs to an already established context (for example support follow-up), use POST create communication in existing communication thread.

Use this to:

- preserve conversation continuity
- keep context attached to one thread lifecycle
- avoid duplicate parallel threads for the same issue


### 4. Create communication in a new thread

If no prior thread exists for the topic, use POST create communication in new communication thread.

Use this to:

- start a new structured communication context
- separate unrelated topics cleanly


## Complete workflow examples

Note: Payloads below are illustrative integration examples. Validate exact field names and structures against the latest OpenAPI schema before publication or implementation.

### Example 1: Preference center update

Scenario: Customer disables promotional SMS and keeps transactional email enabled.

1. GET communication preferences
2. Render settings UI
3. PUT update communication preferences
4. Re-fetch GET communication preferences


Example update payload (illustrative):


```json
{
  "preferences": [
    {
      "category": "MARKETING",
      "channels": [
        { "channel": "SMS", "active": false },
        { "channel": "EMAIL", "active": true }
      ]
    },
    {
      "category": "SERVICE",
      "channels": [
        { "channel": "EMAIL", "active": true }
      ]
    }
  ],
  "requestId": "7e5dfce2-5475-4f23-b2d8-7718d5d19ce6"
}
```

### Example 2: Send communication in existing thread

Scenario: Partner sends a follow-up message for an already open support conversation.

1. Resolve thread identifier from your context
2. POST create communication in existing communication thread
3. Update timeline in UI


Example payload (illustrative):


```json
{
  "threadId": "comm-thread-123",
  "message": {
    "subject": "Update on your request",
    "body": "We have completed the requested change.",
    "channel": "EMAIL"
  },
  "requestId": "765c6977-c91b-4a58-a1f0-5efe90ff84ca"
}
```

### Example 3: Create new thread communication

Scenario: Partner starts a new communication thread for a campaign confirmation.

1. POST create communication in new communication thread
2. Store returned thread reference
3. Use existing-thread endpoint for follow-up messages


Example payload (illustrative):


```json
{
  "topic": "Campaign registration",
  "message": {
    "subject": "Your registration was successful",
    "body": "Thanks for registering. We will keep you updated.",
    "channel": "EMAIL"
  },
  "requestId": "4f67db16-f75f-4cc8-9b95-75dc32b7f977"
}
```

## Common integration challenges

- Sending without preference check: Always read current communication preferences before outbound communication.
- Channel/category mismatch: Keep your UI model aligned to category-channel structures returned by the API.
- Missing refresh after update: Re-fetch preferences after PUT to avoid stale state.
- Thread fragmentation: Reuse existing threads where possible instead of always creating new ones.
- Weak auditability: Persist request IDs and thread IDs to support troubleshooting and compliance checks.


## Webhook and event considerations

For event-driven synchronization, use relevant webhook events from the event catalog and map them to your communication state model.

Event reference:

- [Event types](../webhooks/event-types/)