# Channel ## Retrieve a channel `client.channel.retrieve(stringid, RequestOptionsoptions?): ChannelRetrieveResponse` **get** `/v1/channels/{id}` Retrieves a single channel by its ID. Returns `404` if the channel is not visible to the caller — a private channel the caller is not a member of is indistinguishable from one that does not exist. **[Required scope](/using-the-api/scopes/):** `channels:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Parameters - `id: string` Unique identifier of the channel to retrieve. ### Returns - `ChannelRetrieveResponse` - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: Record` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string | number | boolean | 3 more | null` The field value, or null if unset. - `string` - `number` - `boolean` - `Array` - `Address` - `city?: string | null` City name. - `country?: string | null` 2-letter ISO 3166-1 alpha-2 country code. - `latitude?: number | null` Latitude coordinate. - `longitude?: number | null` Longitude coordinate. - `postalCode?: string | null` Postal or ZIP code. - `state?: string | null` State or province. - `street?: string | null` Street address line 1. - `street2?: string | null` Street address line 2. - `FullName` - `firstName?: string | null` The contact's first name. - `lastName?: string | null` The contact's last name. - `valueType: "ADDRESS" | "CHECKBOX" | "CURRENCY" | 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string | null` URL to view the entity in the Lightfield web app, or null. - `objectType: "channel"` Always `channel`. - `"channel"` - `relationships: Record` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: Array` IDs of the related entities. - `updatedAt: string | null` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId?: string | null` External identifier for the entity, or null if unset. ### Example ```typescript import Lightfield from 'lightfield'; const client = new Lightfield({ apiKey: 'My API Key', }); const channelRetrieveResponse = await client.channel.retrieve('id'); console.log(channelRetrieveResponse.id); ``` #### Response ```json { "id": "chn_cm2def456ghi789", "createdAt": "2026-05-01T09:00:00.000Z", "fields": { "$name": { "value": "acme-deal-room", "valueType": "TEXT" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$isPublic": { "value": false, "valueType": "CHECKBOX" }, "$providerChannelId": { "value": "C0123456789", "valueType": "TEXT" }, "$providerCreatedAt": { "value": "2026-04-20T14:30:00.000Z", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "channel", "relationships": { "account-slack-channel": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm0abc123def456" ] }, "opportunity-slack-channel": { "cardinality": "has_many", "objectType": "opportunity", "values": [ "opp_cm1xyz456uvw789" ] } }, "updatedAt": "2026-05-01T09:00:00.000Z", "externalId": "externalId" } ``` ## List channels `client.channel.list(ChannelListParamsquery?, RequestOptionsoptions?): ChannelListResponse` **get** `/v1/channels` Returns a paginated list of channels. Use `offset` and `limit` to paginate through results. Each page is filtered per caller to the channels they may see (public channels, channels they are a member of, and org-wide-visible providers). See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `channels:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Parameters - `query: ChannelListParams` - `limit?: number` Maximum number of records to return. Defaults to 25, maximum 25. - `offset?: number` Number of records to skip for pagination. Defaults to 0. ### Returns - `ChannelListResponse` - `data: Array` Array of channel objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: Record` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string | number | boolean | 3 more | null` The field value, or null if unset. - `string` - `number` - `boolean` - `Array` - `Address` - `city?: string | null` City name. - `country?: string | null` 2-letter ISO 3166-1 alpha-2 country code. - `latitude?: number | null` Latitude coordinate. - `longitude?: number | null` Longitude coordinate. - `postalCode?: string | null` Postal or ZIP code. - `state?: string | null` State or province. - `street?: string | null` Street address line 1. - `street2?: string | null` Street address line 2. - `FullName` - `firstName?: string | null` The contact's first name. - `lastName?: string | null` The contact's last name. - `valueType: "ADDRESS" | "CHECKBOX" | "CURRENCY" | 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string | null` URL to view the entity in the Lightfield web app, or null. - `objectType: "channel"` Always `channel`. - `"channel"` - `relationships: Record` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: Array` IDs of the related entities. - `updatedAt: string | null` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId?: string | null` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Example ```typescript import Lightfield from 'lightfield'; const client = new Lightfield({ apiKey: 'My API Key', }); const channelListResponse = await client.channel.list(); console.log(channelListResponse.data); ``` #### Response ```json { "data": [ { "id": "chn_cm2def456ghi789", "createdAt": "2026-05-01T09:00:00.000Z", "fields": { "$name": { "value": "acme-deal-room", "valueType": "TEXT" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$isPublic": { "value": false, "valueType": "CHECKBOX" }, "$providerChannelId": { "value": "C0123456789", "valueType": "TEXT" }, "$providerCreatedAt": { "value": "2026-04-20T14:30:00.000Z", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "channel", "relationships": { "account-slack-channel": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm0abc123def456" ] }, "opportunity-slack-channel": { "cardinality": "has_many", "objectType": "opportunity", "values": [ "opp_cm1xyz456uvw789" ] } }, "updatedAt": "2026-05-01T09:00:00.000Z", "externalId": "externalId" }, { "id": "chn_cm3ghi789jkl012", "createdAt": "2026-04-29T15:12:00.000Z", "fields": { "$name": { "value": "general", "valueType": "TEXT" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$isPublic": { "value": true, "valueType": "CHECKBOX" }, "$providerChannelId": { "value": "C9876543210", "valueType": "TEXT" }, "$providerCreatedAt": { "value": "2026-01-05T10:00:00.000Z", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "channel", "relationships": { "account-slack-channel": { "cardinality": "has_many", "objectType": "account", "values": [ "acc_cm0abc123def456" ] }, "opportunity-slack-channel": { "cardinality": "has_many", "objectType": "opportunity", "values": [ "opp_cm1xyz456uvw789" ] } }, "updatedAt": "2026-04-29T15:12:00.000Z", "externalId": "externalId" } ], "object": "list", "totalCount": 2 } ``` ## Domain Types ### Channel List Response - `ChannelListResponse` - `data: Array` Array of channel objects for the current page. - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: Record` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string | number | boolean | 3 more | null` The field value, or null if unset. - `string` - `number` - `boolean` - `Array` - `Address` - `city?: string | null` City name. - `country?: string | null` 2-letter ISO 3166-1 alpha-2 country code. - `latitude?: number | null` Latitude coordinate. - `longitude?: number | null` Longitude coordinate. - `postalCode?: string | null` Postal or ZIP code. - `state?: string | null` State or province. - `street?: string | null` Street address line 1. - `street2?: string | null` Street address line 2. - `FullName` - `firstName?: string | null` The contact's first name. - `lastName?: string | null` The contact's last name. - `valueType: "ADDRESS" | "CHECKBOX" | "CURRENCY" | 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string | null` URL to view the entity in the Lightfield web app, or null. - `objectType: "channel"` Always `channel`. - `"channel"` - `relationships: Record` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: Array` IDs of the related entities. - `updatedAt: string | null` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId?: string | null` External identifier for the entity, or null if unset. - `object: string` The object type, always `"list"`. - `totalCount: number` Total number of entities matching the query. ### Channel Retrieve Response - `ChannelRetrieveResponse` - `id: string` Unique identifier for the entity. - `createdAt: string` ISO 8601 timestamp of when the entity was created. - `fields: Record` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: string | number | boolean | 3 more | null` The field value, or null if unset. - `string` - `number` - `boolean` - `Array` - `Address` - `city?: string | null` City name. - `country?: string | null` 2-letter ISO 3166-1 alpha-2 country code. - `latitude?: number | null` Latitude coordinate. - `longitude?: number | null` Longitude coordinate. - `postalCode?: string | null` Postal or ZIP code. - `state?: string | null` State or province. - `street?: string | null` Street address line 1. - `street2?: string | null` Street address line 2. - `FullName` - `firstName?: string | null` The contact's first name. - `lastName?: string | null` The contact's last name. - `valueType: "ADDRESS" | "CHECKBOX" | "CURRENCY" | 12 more` The data type of the field. - `"ADDRESS"` - `"CHECKBOX"` - `"CURRENCY"` - `"DATETIME"` - `"EMAIL"` - `"FULL_NAME"` - `"MARKDOWN"` - `"MULTI_SELECT"` - `"NUMBER"` - `"SINGLE_SELECT"` - `"SOCIAL_HANDLE"` - `"TELEPHONE"` - `"TEXT"` - `"URL"` - `"HTML"` - `httpLink: string | null` URL to view the entity in the Lightfield web app, or null. - `objectType: "channel"` Always `channel`. - `"channel"` - `relationships: Record` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: string` Whether the relationship is `has_one` or `has_many`. - `objectType: string` The type of the related object (e.g. `account`, `contact`). - `values: Array` IDs of the related entities. - `updatedAt: string | null` ISO 8601 timestamp of when the entity was last updated, or null. - `externalId?: string | null` External identifier for the entity, or null if unset.