---
title: Channel Settings
description: Storing recipient-specific data for channels like device tokens and chat connections
---

## Channel Settings

Channel settings store recipient-specific data required by certain channels to deliver notifications. While channels define the provider configuration at the project level, channel settings hold the per-user data that connects a user to that channel — such as device tokens for mobile push or Slack connection details for chat.

### Why Channel Settings?

Not all channels need user-specific data. Email and SMS channels use contact information already on the user record (email address, phone number). But some channels require additional, provider-specific data to deliver messages:

- **Mobile push channels** need device tokens registered by the user's device
- **Chat channels** need identifiers that link the user to a workspace or conversation

Channel settings bridge this gap. They are set once (typically during device registration or OAuth connection) and used automatically whenever a notiflow delivers a notification through that channel.

<Callout type="info">
  Web push subscriptions are managed through a separate [Channel Subscriptions](/docs/concepts/channel-subscriptions) API, not channel settings.
</Callout>

### How Channel Settings Work

Channel settings are stored as a mapping between a user and a channel. Each entry includes provider-specific data that Notiflows uses at delivery time.

When a notiflow reaches a channel step, Notiflows:

1. Looks up the recipient's channel settings for the target channel
2. Extracts the provider-specific data (tokens, connection IDs)
3. Uses that data to deliver the notification through the provider

If no channel settings exist for a user on a given channel, delivery through that channel is skipped for that user.

### Provider Data Requirements

Each provider type requires specific data in channel settings.

#### Mobile Push (APNs, FCM)

Mobile push channels store an array of device tokens. A user can have multiple tokens if they use your app on several devices.

```json
{
  "settings": {
    "device_tokens": ["token_for_iphone", "token_for_ipad"]
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `device_tokens` | `string[]` | Array of device tokens registered by the user's devices |

When delivering a push notification, Notiflows sends to all registered device tokens. This ensures the user receives the notification regardless of which device they're currently using.

**When to set push tokens:**
- After the user grants push permission in your app
- On each app launch (tokens can rotate)
- When migrating from another push provider

**When to remove tokens:**
- When the user logs out of your app on a device
- When a token is rejected by the push provider (expired or invalid)

#### Chat Channels (Slack)

Slack channel settings identify where to deliver messages for a user within a Slack workspace.

```json
{
  "settings": {
    "slack_channel_id": "C01ABCDEF",
    "slack_user_id": "U01ABCDEF"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `slack_channel_id` | `string` | The Slack channel to post notifications to |
| `slack_user_id` | `string` | The Slack user to send direct messages to |

At least one of these fields must be provided. If both are set, Notiflows uses the `slack_user_id` for direct messages.

**When to set Slack data:**
- After the user completes Slack OAuth and connects their account
- When an admin maps a user to a Slack identity

### Managing Channel Settings

Channel settings are managed through the API, typically from your backend when a user connects a device or links an account. Channel settings use upsert semantics — if settings already exist for the user-channel pair, they are replaced.

You can set, retrieve, and remove channel settings through both the Admin API (server-to-server) and the User API (client-side). Channel settings are also visible in the Notiflows dashboard under each user's **Channel Settings** tab.

<Cards>
  <Card title="Set channel settings (Admin API)" href="/docs/api/admin/users/update_channel_settings">
    Set or update channel settings for a user from your backend.
  </Card>
  <Card title="Get channel settings (Admin API)" href="/docs/api/admin/users/get_channel_settings">
    Retrieve a user's current channel settings.
  </Card>
  <Card title="Delete channel settings (Admin API)" href="/docs/api/admin/users/delete_channel_settings">
    Remove channel settings when a user disconnects a device or unlinks an account.
  </Card>
  <Card title="Channel settings (User API)" href="/docs/api/user/channel_settings/update">
    Set channel settings from the client side.
  </Card>
</Cards>

### Channel Settings vs. Preferences

Channel settings and preferences serve different purposes:

| | Channel Settings | Preferences |
| --- | --- | --- |
| **Purpose** | Store data needed to deliver through a channel | Control whether a user wants to receive notifications |
| **Set by** | Your application (programmatically) | The user (through a preference center) |
| **Example** | Device tokens, Slack user IDs | "Disable all SMS notifications" |
| **Effect when missing** | Delivery is skipped (can't reach user) | Delivery proceeds (user hasn't opted out) |

Both work together at delivery time. Notiflows first checks preferences to see if the user wants the notification, then checks channel settings to see if delivery is possible.

### Best Practices

- **Set tokens early**: Register device tokens as soon as push permission is granted, and refresh them on each app launch
- **Clean up stale tokens**: Remove tokens that are no longer valid to avoid unnecessary delivery attempts and provider errors
- **Handle multiple devices**: Users may have several devices — store all active tokens so notifications reach every device
- **Secure the flow**: Always set channel settings from your backend using the Admin API, never from client-side code, as it requires your secret key
- **Verify before storing**: Validate tokens and connection IDs before saving them as channel settings to catch errors early