# Message ## Retrieve a message `message.retrieve(strid) -> MessageRetrieveResponse` **get** `/v1/messages/{id}` Retrieves a single message by its ID. The message text is redacted based on the caller-specific channel-visibility resolution, and the response includes a read-only `accessLevel`. **[Required scope](/using-the-api/scopes/):** `messages:read` **[Rate limit category](/using-the-api/rate-limits/):** Read ### Parameters - `id: str` Unique identifier of the message to retrieve. ### Returns - `class MessageRetrieveResponse: …` - `id: str` Unique identifier for the entity. - `access_level: Literal["FULL", "METADATA"]` The caller's resolved access level for this message. - `"FULL"` - `"METADATA"` - `created_at: str` ISO 8601 timestamp of when the entity was created. - `fields: Dict[str, Fields]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: Optional[FieldsValue]` The field value, or null if unset. - `str` - `float` - `bool` - `List[str]` - `class FieldsValueAddress: …` - `city: Optional[str]` City name. - `country: Optional[str]` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: Optional[float]` Latitude coordinate. - `longitude: Optional[float]` Longitude coordinate. - `postal_code: Optional[str]` Postal or ZIP code. - `state: Optional[str]` State or province. - `street: Optional[str]` Street address line 1. - `street2: Optional[str]` Street address line 2. - `class FieldsValueFullName: …` - `first_name: Optional[str]` The contact's first name. - `last_name: Optional[str]` The contact's last name. - `value_type: Literal["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"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `object_type: Literal["message"]` Always `message`. - `"message"` - `relationships: Dict[str, Relationships]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: str` Whether the relationship is `has_one` or `has_many`. - `object_type: str` The type of the related object (e.g. `account`, `contact`). - `values: List[str]` IDs of the related entities. - `updated_at: Optional[str]` ISO 8601 timestamp of when the entity was last updated, or null. - `external_id: Optional[str]` External identifier for the entity, or null if unset. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) message_retrieve_response = client.message.retrieve( "id", ) print(message_retrieve_response.id) ``` #### Response ```json { "id": "msg_cm0abc456def789", "accessLevel": "FULL", "createdAt": "2026-05-01T09:00:00.000Z", "fields": { "$text": { "value": "Thanks — pushed the fix, should be live shortly.", "valueType": "TEXT" }, "$sentAt": { "value": "2026-05-01T08:59:30.000Z", "valueType": "DATETIME" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$providerThreadId": { "value": "1714553970.123456", "valueType": "TEXT" }, "$editedAt": { "value": "string", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "message", "relationships": { "$channel": { "cardinality": "has_one", "objectType": "channel", "values": [ "chn_cm2def456ghi789" ] } }, "updatedAt": "2026-05-01T09:00:00.000Z", "externalId": "externalId" } ``` ## List messages `message.list(MessageListParams**kwargs) -> MessageListResponse` **get** `/v1/messages` Returns a paginated list of messages. Use `offset` and `limit` to paginate through results. Each message is filtered per caller to those whose channel they may see, and includes a read-only `accessLevel`. See [List endpoints](/using-the-api/list-endpoints/) for more information about pagination. **[Required scope](/using-the-api/scopes/):** `messages:read` **[Rate limit category](/using-the-api/rate-limits/):** Search ### Parameters - `limit: Optional[int]` Maximum number of records to return. Defaults to 25, maximum 25. - `offset: Optional[int]` Number of records to skip for pagination. Defaults to 0. ### Returns - `class MessageListResponse: …` - `data: List[Data]` Array of message objects for the current page. - `id: str` Unique identifier for the entity. - `access_level: Literal["FULL", "METADATA"]` The caller's resolved access level for this message. - `"FULL"` - `"METADATA"` - `created_at: str` ISO 8601 timestamp of when the entity was created. - `fields: Dict[str, DataFields]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: Optional[DataFieldsValue]` The field value, or null if unset. - `str` - `float` - `bool` - `List[str]` - `class DataFieldsValueAddress: …` - `city: Optional[str]` City name. - `country: Optional[str]` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: Optional[float]` Latitude coordinate. - `longitude: Optional[float]` Longitude coordinate. - `postal_code: Optional[str]` Postal or ZIP code. - `state: Optional[str]` State or province. - `street: Optional[str]` Street address line 1. - `street2: Optional[str]` Street address line 2. - `class DataFieldsValueFullName: …` - `first_name: Optional[str]` The contact's first name. - `last_name: Optional[str]` The contact's last name. - `value_type: Literal["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"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `object_type: Literal["message"]` Always `message`. - `"message"` - `relationships: Dict[str, DataRelationships]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: str` Whether the relationship is `has_one` or `has_many`. - `object_type: str` The type of the related object (e.g. `account`, `contact`). - `values: List[str]` IDs of the related entities. - `updated_at: Optional[str]` ISO 8601 timestamp of when the entity was last updated, or null. - `external_id: Optional[str]` External identifier for the entity, or null if unset. - `object: str` The object type, always `"list"`. - `total_count: int` Total number of entities matching the query. ### Example ```python from lightfield import Lightfield client = Lightfield( api_key="My API Key", ) message_list_response = client.message.list() print(message_list_response.data) ``` #### Response ```json { "data": [ { "id": "msg_cm0abc456def789", "accessLevel": "FULL", "createdAt": "2026-05-01T09:00:00.000Z", "fields": { "$text": { "value": "Thanks — pushed the fix, should be live shortly.", "valueType": "TEXT" }, "$sentAt": { "value": "2026-05-01T08:59:30.000Z", "valueType": "DATETIME" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$providerThreadId": { "value": "1714553970.123456", "valueType": "TEXT" }, "$editedAt": { "value": "string", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "message", "relationships": { "$channel": { "cardinality": "has_one", "objectType": "channel", "values": [ "chn_cm2def456ghi789" ] } }, "updatedAt": "2026-05-01T09:00:00.000Z", "externalId": "externalId" }, { "id": "msg_cm1xyz123uvw456", "accessLevel": "FULL", "createdAt": "2026-04-29T15:12:00.000Z", "fields": { "$text": { "value": "Can we sync on pricing tomorrow?", "valueType": "TEXT" }, "$sentAt": { "value": "2026-04-29T15:11:30.000Z", "valueType": "DATETIME" }, "$provider": { "value": "SLACK", "valueType": "TEXT" }, "$providerThreadId": { "value": "string", "valueType": "TEXT" }, "$editedAt": { "value": "string", "valueType": "DATETIME" } }, "httpLink": null, "objectType": "message", "relationships": { "$channel": { "cardinality": "has_one", "objectType": "channel", "values": [ "chn_cm2def456ghi789" ] } }, "updatedAt": "2026-04-29T15:12:00.000Z", "externalId": "externalId" } ], "object": "list", "totalCount": 2 } ``` ## Domain Types ### Message List Response - `class MessageListResponse: …` - `data: List[Data]` Array of message objects for the current page. - `id: str` Unique identifier for the entity. - `access_level: Literal["FULL", "METADATA"]` The caller's resolved access level for this message. - `"FULL"` - `"METADATA"` - `created_at: str` ISO 8601 timestamp of when the entity was created. - `fields: Dict[str, DataFields]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: Optional[DataFieldsValue]` The field value, or null if unset. - `str` - `float` - `bool` - `List[str]` - `class DataFieldsValueAddress: …` - `city: Optional[str]` City name. - `country: Optional[str]` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: Optional[float]` Latitude coordinate. - `longitude: Optional[float]` Longitude coordinate. - `postal_code: Optional[str]` Postal or ZIP code. - `state: Optional[str]` State or province. - `street: Optional[str]` Street address line 1. - `street2: Optional[str]` Street address line 2. - `class DataFieldsValueFullName: …` - `first_name: Optional[str]` The contact's first name. - `last_name: Optional[str]` The contact's last name. - `value_type: Literal["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"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `object_type: Literal["message"]` Always `message`. - `"message"` - `relationships: Dict[str, DataRelationships]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: str` Whether the relationship is `has_one` or `has_many`. - `object_type: str` The type of the related object (e.g. `account`, `contact`). - `values: List[str]` IDs of the related entities. - `updated_at: Optional[str]` ISO 8601 timestamp of when the entity was last updated, or null. - `external_id: Optional[str]` External identifier for the entity, or null if unset. - `object: str` The object type, always `"list"`. - `total_count: int` Total number of entities matching the query. ### Message Retrieve Response - `class MessageRetrieveResponse: …` - `id: str` Unique identifier for the entity. - `access_level: Literal["FULL", "METADATA"]` The caller's resolved access level for this message. - `"FULL"` - `"METADATA"` - `created_at: str` ISO 8601 timestamp of when the entity was created. - `fields: Dict[str, Fields]` Map of field names to their typed values. System fields are prefixed with `$` (e.g. `$name`, `$email`); custom attributes use their bare slug. - `value: Optional[FieldsValue]` The field value, or null if unset. - `str` - `float` - `bool` - `List[str]` - `class FieldsValueAddress: …` - `city: Optional[str]` City name. - `country: Optional[str]` 2-letter ISO 3166-1 alpha-2 country code. - `latitude: Optional[float]` Latitude coordinate. - `longitude: Optional[float]` Longitude coordinate. - `postal_code: Optional[str]` Postal or ZIP code. - `state: Optional[str]` State or province. - `street: Optional[str]` Street address line 1. - `street2: Optional[str]` Street address line 2. - `class FieldsValueFullName: …` - `first_name: Optional[str]` The contact's first name. - `last_name: Optional[str]` The contact's last name. - `value_type: Literal["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"` - `http_link: Optional[str]` URL to view the entity in the Lightfield web app, or null. - `object_type: Literal["message"]` Always `message`. - `"message"` - `relationships: Dict[str, Relationships]` Map of relationship names to their associated entities. System relationships are prefixed with `$` (e.g. `$owner`, `$contact`). - `cardinality: str` Whether the relationship is `has_one` or `has_many`. - `object_type: str` The type of the related object (e.g. `account`, `contact`). - `values: List[str]` IDs of the related entities. - `updated_at: Optional[str]` ISO 8601 timestamp of when the entity was last updated, or null. - `external_id: Optional[str]` External identifier for the entity, or null if unset.