{"id":15578390,"url":"https://github.com/atomist/slack-messages","last_synced_at":"2025-04-24T02:08:33.809Z","repository":{"id":45217582,"uuid":"90671205","full_name":"atomist/slack-messages","owner":"atomist","description":"Helper library for rendering Slack messages in Atomist automations","archived":false,"fork":false,"pushed_at":"2021-12-30T20:01:08.000Z","size":729,"stargazers_count":11,"open_issues_count":0,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-24T02:08:27.442Z","etag":null,"topics":["node"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atomist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2017-05-08T20:49:21.000Z","updated_at":"2025-01-21T20:35:31.000Z","dependencies_parsed_at":"2022-08-29T08:42:10.154Z","dependency_job_id":null,"html_url":"https://github.com/atomist/slack-messages","commit_stats":null,"previous_names":[],"tags_count":153,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fslack-messages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fslack-messages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fslack-messages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fslack-messages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomist","download_url":"https://codeload.github.com/atomist/slack-messages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250546081,"owners_count":21448260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node"],"created_at":"2024-10-02T19:10:07.846Z","updated_at":"2025-04-24T02:08:33.791Z","avatar_url":"https://github.com/atomist.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @atomist/slack-messages\n\n[![atomist sdm goals](http://badge.atomist.com/T29E48P34/atomist/slack-messages/9e7d7699-14a8-4273-945b-9e5ca08aa38f)](https://app.atomist.com/workspace/T29E48P34)\n[![npm version](https://img.shields.io/npm/v/@atomist/slack-messages.svg)](https://www.npmjs.com/package/@atomist/slack-messages)\n\n[Node.js][node] module that helps to create well-formatted\n[Slack][slackhq] messages sent through the `@atomist` bot from your\nsoftware delivery machine (SDM).  This module also facilitates adding\nactions to your Slack messages that execute SDM commands.\n\nSupport for sending Slack Block messages is also supported.\n\nSee the [Atomist documentation][atomist-doc] for more information on\nwhat SDMs are and what they can do for you using the Atomist API for\nsoftware.\n\n[atomist-doc]: https://docs.atomist.com/ (Atomist Documentation)\n[slackhq]: https://slack.com/ (Slack)\n\n## Using\n\nConstruct a message as a plain map following the [Slack message\nformatting API][slack-api].\n\n[slack-api]: https://api.slack.com/docs/message-formatting (Slack message formatting API)\n\n```typescript\nimport { SlackMessage } from \"@atomist/slack-messages\";\n// A very simple message\nconst msg: SlackMessage = { text: \"Simple message\" };\n```\n\n```typescript\nimport {\n    escape,\n    SlackMessage,\n    url,\n} from \"@atomist/slack-messages\";\n// Here is an example of a message with a Slack action (button).\nconst msg: SlackMessage = {\n    text: `${url(user.url, \"@\" + user.name)} opened issue: ${url(issue.url, issue.title)}`,\n    attachments: [\n        {\n            text: escape(issue.body),\n            fallback: escape(issue.title),\n            mrkdwn_in: [\"text\"],\n            actions: [\n                {\n                    text: \"Close issue\",\n                    type: \"button\",\n                    name: \"closeissue\",\n                    value: \"somebuttonid\",\n                },\n            ],\n            callback_id: \"cllbck1\",\n        },\n    ],\n};\n```\n\nAnd then render the message with `render(msg)`.  This will construct a\nJSON string representation of the message:\n\n```typescript\nimport { render } from \"@atomist/slack-messages\"\n\nconst renderedMsg = render(msg);\n```\n\nor to produce a pretty JSON string:\n\n```typescript\nconst renderedMsg = render(msg, true);\n```\n\nThis will produce the following JSON string (pretty version):\n\n```json\n{\n  \"text\": \"\u003chttps://github.com/anna|@anna\u003e opened issue: \u003chttps://github.com/someorg/somerepo/issues/484|This issue title contains \u0026lt;unsafe\u0026gt; characters and \u0026amp;\u003e\",\n  \"attachments\": [\n    {\n      \"text\": \"This is a very important issue with body containing \u0026lt;unsafe\u0026gt; characters and even \u0026amp;\",\n      \"fallback\": \"This issue title contains \u0026lt;unsafe\u0026gt; characters and \u0026amp;\",\n      \"mrkdwn_in\": [\n        \"text\"\n      ],\n      \"callback_id\": \"cllbck1\",\n      \"actions\": [\n        {\n          \"text\": \"Close issue\",\n          \"type\": \"button\",\n          \"name\": \"rug\",\n          \"value\": \"somebuttonid\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nNote that the `render` function will automatically assign a unique\n`callback_id` to each attachments that has actions.  But, if you\nprovide your custom `callback_id` it will be preserved as is.\n\n### Additional helper functions\n\n#### Special characters\n\n```typescript\nescape(\"Slack requires you to escape \u003c, \u003e and \u0026\");\n// =\u003e \"Slack requires you to escape \u0026lt;, \u0026gt; and \u0026amp;\"\n```\n\n#### Links\n\n```typescript\n// Simple link\nurl(\"https://www.atomist.com\");\n// =\u003e \"\u003chttps://www.atomist.com\u003e\"\n\n// Link with label\nurl(\"https://www.atomist.com\", \"atomist\");\n// =\u003e \"\u003chttps://www.atomist.com|atomist\u003e\"\n```\n\n#### User \u0026 channel links\n\n```typescript\n// @some-user (Slack will display user name for provided user ID)\nuser(\"U123\");\n// =\u003e \"\u003c@U123\u003e\"\n\n// #some-channel (Slack will display channel name for provided channel ID)\nchannel(\"C123\");\n// =\u003e \"\u003c#C123\u003e\"\n```\n\n#### Special variables\n\n```typescript\n// @channel\natChannel();\n// =\u003e \"\u003c!channel\u003e\"\n\n// @here\natHere();\n// =\u003e \"\u003c!here\u003e\"\n\n// @everyone\natEveryone();\n// =\u003e \"\u003c!everyone\u003e\"\n```\n\n#### Emoji\n\n```typescript\nemoji(\"smile\");\n// =\u003e \":smile:\";\n```\n\n#### Markdown\n\nSlack will render markdown if field where markdown is present is\nincluded in `mrkdwn_in` array.\n\n```typescript\nbold(\"This text will appear bold\");\n// =\u003e \"*This text will appear bold*\"\n\nitalic(\"This text will appear italic\");\n// =\u003e \"_This text will appear italic_\"\n\nstrikethrough(\"This text will appear strike-through\");\n// =\u003e \"~This text will appear strike-through~\"\n\n// Single line code block\ncodeLine(\"var a = new A();\");\n// =\u003e  \"`var a = new A();`\"\n\n// Multi line code block\ncodeBlock(\"var a = new A();\\nvar b = new B();\");\n// =\u003e \"```var a = new A();\\nvar b = new B();```\"\n\n// List\nlistItem(\"Item 1\");\n// =\u003e \"• Item 1\"\n```\n\n### GitHub to Slack markdown conversion\n\nGitHub and Slack markdown are different enough to make your GitHub\nissues or GitHub PRs look quite bad in Slack by default.  You can use\nthe `githubToSlack` function from `Markdown` to convert text that uses\nGitHub markdown to text that will look good in Slack:\n\n```typescript\nimport { githubToSlack } from \"@atomist/slack-messages\"\n\ngithubToSlack(\"* list item 1\\n* list item 2\\n\\**some bold text** and *some italic text* with a link [click here](http://someplace.com)\");\n// =\u003e \"• list item 1\\n• list item 2\\n*some bold text* and _some italic text_ with a link \u003chttp://someplace.com|click here\u003e\"\n```\n\n## Support\n\nGeneral support questions should be discussed in the `#help`\nchannel in the [Atomist community Slack workspace][slack].\n\nIf you find a problem, please create an [issue][].\n\n[issue]: https://github.com/atomist/slack-messages/issues\n\n## Development\n\nYou will need to install [Node.js][node] to build and test this\nproject.\n\n[node]: https://nodejs.org/ (Node.js)\n\n### Build and test\n\nInstall dependencies.\n\n```\n$ npm install\n```\n\nUse the `build` package script to compile, test, lint, and build the\ndocumentation.\n\n```\n$ npm run build\n```\n\n### Release\n\nReleases are handled via the [Atomist SDM][atomist-sdm].  Just press\nthe 'Approve' button in the Atomist dashboard or Slack.\n\n[atomist-sdm]: https://github.com/atomist/atomist-sdm (Atomist Software Delivery Machine)\n\n---\n\nCreated by [Atomist][atomist].\nNeed Help?  [Join our Slack workspace][slack].\n\n[atomist]: https://atomist.com/ (Atomist - How Teams Deliver Software)\n[slack]: https://join.atomist.com/ (Atomist Community Slack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomist%2Fslack-messages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomist%2Fslack-messages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomist%2Fslack-messages/lists"}