diff --git a/README.md b/README.md index 5bc1cbb..e05264c 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,7 @@ API endpoints - [Message Boards](https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards) - [Message Types](https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#message-types) - [Messages](https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages) +- [My notifications](https://github.com/basecamp/bc3-api/blob/master/sections/my_notifications.md#my-notifications) - [People](https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people) - [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) - [Question answers](https://github.com/basecamp/bc3-api/blob/master/sections/question_answers.md#question-answers) diff --git a/sections/my_notifications.md b/sections/my_notifications.md new file mode 100644 index 0000000..f30fc7d --- /dev/null +++ b/sections/my_notifications.md @@ -0,0 +1,260 @@ +My notifications +================= + +The notifications endpoint returns the current user's notification inbox — the same data that powers the "Hey!" menu in Basecamp. Notifications are grouped into three categories: unread items, recently read items, and memorized items. + +Each notification represents activity on a recording (message, to-do, comment, etc.) that the current user has been notified about. Notifications track unread state, unread counts, and timestamps for when items were read or received. + +Endpoints: + +- [Get notifications](#get-notifications) +- [Mark as read](#mark-as-read) + + +Get notifications +----------------- + +* `GET /my/readings.json` will return the current user's notifications grouped into `unreads`, `reads`, and `memories`. + +Reads are a [paginated list][pagination] with 50 items per page. Unreads are not paginated but are capped at 100 items. Memories are not paginated. + +_Optional parameters_: + +* `page` - page number for paginating through read items. Defaults to `1`. + +Each notification in the response includes: + +* `id` - the notification ID. +* `created_at` - when the notification was first created. +* `updated_at` - when the notification was last updated. +* `section` - the category: `inbox`, `chats`, `pings`, `remembered`, or `mentions`. +* `unread_count` - the number of unread updates on this item. +* `unread_at` - timestamp when the item was last marked unread, or `null` if read. +* `read_at` - timestamp when the item was last read, or `null` if unread. +* `readable_sgid` - signed global ID for the readable, used when marking items as read. +* `readable_identifier` - a human-readable identifier for the readable. +* `title` - the title of the readable item. +* `type` - the type of readable (e.g. `Recording`, `Event`). +* `bucket_name` - the name of the project this notification belongs to. +* `creator` - the person who created or last updated the readable (see [People][1] for the full person object). +* `content_excerpt` - a text excerpt of the content, when available. +* `app_url` - the URL to view this item in Basecamp. +* `unread_url` - a URL related to this item's unread state (mark items as read using the "Mark as read" endpoint described below). +* `bookmark_url` - the URL to bookmark this item. +* `memory_url` - the URL to memorize or forget this item (only present when the item is memorizable). +* `subscribed` - `true` if the current user is subscribed to the item's container. +* `subscription_url` - the URL to manage the subscription for this item's container. +* `previewable_attachments` - an array of previewable attachments, up to 10. + +Pings additionally include: + +* `participants` - an array of other people in the ping. +* `named` - whether the ping has a custom name. +* `image_url` - the ping's custom image, if one is set. + +###### Example JSON Response + +```json +{ + "unreads": [ + { + "id": 1069479012, + "created_at": "2026-02-15T14:22:10.000Z", + "updated_at": "2026-02-15T14:22:10.000Z", + "section": "inbox", + "unread_count": 3, + "unread_at": "2026-02-15T14:22:10.000Z", + "read_at": null, + "readable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "readable_identifier": "message_1069479012", + "title": "Kickoff meeting notes", + "type": "Recording", + "bucket_name": "Honcho Design Newsroom", + "creator": { + "id": 1049715913, + "attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "name": "Victor Cooper", + "email_address": "victor@honchodesign.com", + "personable_type": "User", + "title": "Chief Strategist", + "bio": "Don't let your dreams be dreams", + "location": "Chicago, IL", + "created_at": "2026-02-12T06:08:49.342Z", + "updated_at": "2026-02-12T06:08:50.871Z", + "admin": true, + "owner": true, + "client": false, + "employee": true, + "time_zone": "America/Chicago", + "avatar_url": "https://3.basecampapi.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar", + "company": { + "id": 1033447817, + "name": "Honcho Design" + }, + "can_ping": true, + "can_manage_projects": true, + "can_manage_people": true, + "can_access_timesheet": true, + "can_access_hill_charts": true + }, + "content_excerpt": "Here are the notes from today's kickoff...", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958502/messages/1069479012", + "unread_url": "https://3.basecampapi.com/195539477/my/readings/1069479012.json", + "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVU...json", + "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958502/recordings/1069479012/subscription.json", + "previewable_attachments": [], + "subscribed": true + } + ], + "reads": [ + { + "id": 1069479005, + "created_at": "2026-02-14T10:05:30.000Z", + "updated_at": "2026-02-14T16:30:00.000Z", + "section": "inbox", + "unread_count": 0, + "unread_at": "2026-02-14T10:05:30.000Z", + "read_at": "2026-02-14T16:30:00.000Z", + "readable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "readable_identifier": "todo_1069479005", + "title": "Update the homepage copy", + "type": "Recording", + "bucket_name": "Honcho Design Newsroom", + "creator": { + "id": 1049715914, + "attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "name": "Annie Bryan", + "email_address": "annie@honchodesign.com", + "personable_type": "User", + "title": "Central Markets Manager", + "bio": null, + "location": null, + "created_at": "2026-02-12T06:08:49.352Z", + "updated_at": "2026-02-12T06:08:50.882Z", + "admin": false, + "owner": false, + "client": false, + "employee": true, + "time_zone": "America/Chicago", + "avatar_url": "https://3.basecampapi.com/195539477/people/BAhpBMpkkT4=--2bcbab2d5c2a2d5e2e1e19df7579e5d880c753d/avatar", + "company": { + "id": 1033447817, + "name": "Honcho Design" + }, + "can_ping": true, + "can_manage_projects": false, + "can_manage_people": false, + "can_access_timesheet": true, + "can_access_hill_charts": true + }, + "content_excerpt": "Please review and update the copy on...", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958502/todos/1069479005", + "unread_url": "https://3.basecampapi.com/195539477/my/readings/1069479005.json", + "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVU...json", + "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958502/recordings/1069479005/subscription.json", + "previewable_attachments": [], + "subscribed": true + } + ], + "memories": [ + { + "id": 1069479001, + "created_at": "2026-02-10T09:00:00.000Z", + "updated_at": "2026-02-13T11:00:00.000Z", + "section": "remembered", + "unread_count": 0, + "unread_at": "2026-02-10T09:00:00.000Z", + "read_at": "2026-02-13T11:00:00.000Z", + "readable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "readable_identifier": "message_1069479001", + "title": "Brand guidelines v2", + "type": "Recording", + "bucket_name": "Honcho Design Newsroom", + "creator": { + "id": 1049715913, + "attachable_sgid": "BAh7BkkiC19yYWlscwY6BkVU...", + "name": "Victor Cooper", + "email_address": "victor@honchodesign.com", + "personable_type": "User", + "title": "Chief Strategist", + "bio": "Don't let your dreams be dreams", + "location": "Chicago, IL", + "created_at": "2026-02-12T06:08:49.342Z", + "updated_at": "2026-02-12T06:08:50.871Z", + "admin": true, + "owner": true, + "client": false, + "employee": true, + "time_zone": "America/Chicago", + "avatar_url": "https://3.basecampapi.com/195539477/people/BAhpBMlkkT4=--5fe7b70fbee7a7f0e2e1e19df7579e5d880c753d/avatar", + "company": { + "id": 1033447817, + "name": "Honcho Design" + }, + "can_ping": true, + "can_manage_projects": true, + "can_manage_people": true, + "can_access_timesheet": true, + "can_access_hill_charts": true + }, + "content_excerpt": "Attached are the updated brand guidelines...", + "app_url": "https://3.basecamp.com/195539477/buckets/2085958502/messages/1069479001", + "unread_url": "https://3.basecampapi.com/195539477/my/readings/1069479001.json", + "bookmark_url": "https://3.basecampapi.com/195539477/my/bookmarks/BAh7BkkiC19yYWlscwY6BkVU...json", + "memory_url": "https://3.basecampapi.com/195539477/my/readings/1069479001/memory.json", + "subscription_url": "https://3.basecampapi.com/195539477/buckets/2085958502/recordings/1069479001/subscription.json", + "previewable_attachments": [], + "subscribed": true + } + ] +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/readings.json +``` + +To paginate through read items: + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/readings.json?page=2 +``` + + +Mark as read +------------ + +* `PUT /my/unreads.json` will mark the specified items as read. + +**Required parameters**: + +* `readables` - an array of `readable_sgid` values from the notifications response. These identify the items to mark as read. + +Returns `200 OK` on success with no body. + +###### Example JSON Request + +```json +{ + "readables": [ + "BAh7BkkiC19yYWlscwY6BkVU...", + "BAh7BkkiC19yYWlscwY6BkVU..." + ] +} +``` + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{ "readables": ["BAh7BkkiC19yYWlscwY6BkVU..."] }' \ + https://3.basecampapi.com/$ACCOUNT_ID/my/unreads.json +``` + +[1]: https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people +[pagination]: https://github.com/basecamp/bc3-api/blob/master/README.md#pagination