Slack API¶

The Slack API allows you to convert Markdown content to Slack blocks format, which can be used to create rich messages in Slack.

Markdown to Slack Blocks Conversion¶

Convert Markdown content to Slack blocks format.

Endpoint¶

POST /api/v1/slack/convert

Authentication¶

This endpoint requires an API key to be provided in the X-API-Key header.

Rate Limiting¶

This endpoint is rate-limited to one request every 5 seconds.

Request¶

Headers¶

Name	Required	Description
`Content-Type`	Yes	Must be set to `application/json`
`X-API-Key`	Yes	Your API key

Body¶

{
  "markdown": "# Hello World\n\nThis is a test markdown.\n\n- List item 1\n- List item 2"
}

Parameter	Type	Required	Description
`markdown`	string	Yes	The Markdown content to convert to Slack blocks

Response¶

Success Response (200 OK)¶

{
  "success": true,
  "result": {
    "blocks": {
      "blocks": [
        {
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Hello World*\n\nThis is a test markdown.",
            "verbatim": true
          }
        },
        {
          "type": "divider"
        }
      ]
    },
    "blockKitUrl": "https://api.slack.com/tools/block-kit-builder?blocks=%5B%7B%22type%22%3A%22section%22%2C%22text%22%3A%7B%22type%22%3A%22mrkdwn%22%2C%22text%22%3A%22*Hello%20World*%5Cn%5CnThis%20is%20a%20test%20markdown.%22%2C%22verbatim%22%3Atrue%7D%7D%2C%7B%22type%22%3A%22divider%22%7D%5D&mode=message"
  },
  "timestamp": "2023-06-01T12:00:00Z"
}

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`result.blocks.blocks`	array	An array of Slack blocks
`result.blockKitUrl`	string	A URL to view the blocks in the Slack Block Kit Builder
`timestamp`	string	The timestamp of the response

Error Response (400 Bad Request)¶

{
  "success": false,
  "error": "markdown content is required",
  "timestamp": "2023-06-01T12:00:00Z"
}

Error Response (401 Unauthorized)¶

{
  "success": false,
  "error": "Authentication failed: Unauthorized",
  "timestamp": "2023-06-01T12:00:00Z"
}

Error Response (429 Too Many Requests)¶

{
  "success": false,
  "error": "Rate limit exceeded: please try again later (status code: 429)",
  "timestamp": "2023-06-01T12:00:00Z"
}

Example¶

cURL¶

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "markdown": "# Hello World\n\nThis is a test markdown.\n\n- List item 1\n- List item 2"
  }' \
  https://{{ extra.api_domain }}/api/v1/slack/convert

JavaScript¶

const apiKey = 'your-api-key';
const apiUrl = 'https://{{ extra.api_domain }}/api/v1/slack/convert';

const markdown = `# Hello World

This is a test markdown.

- List item 1
- List item 2`;

fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify({ markdown })
})
  .then(response => response.json())
  .then(data => {
    console.log('Slack blocks:', data.result.blocks.blocks);
    console.log('Block Kit URL:', data.result.blockKitUrl);
  })
  .catch(error => console.error('Error:', error));

Python¶

import requests
import json

api_key = 'your-api-key'
api_url = 'https://{{ extra.api_domain }}/api/v1/slack/convert'

markdown = """# Hello World

This is a test markdown.

- List item 1
- List item 2"""

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key
}

payload = {
    'markdown': markdown
}

response = requests.post(api_url, headers=headers, json=payload)
data = response.json()

print('Slack blocks:', data['result']['blocks']['blocks'])
print('Block Kit URL:', data['result']['blockKitUrl'])

Go¶

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    apiKey := "your-api-key"
    apiURL := "https://{{ extra.api_domain }}/api/v1/slack/convert"

    markdown := `# Hello World

This is a test markdown.

- List item 1
- List item 2`

    // Create request payload
    payload := map[string]string{
        "markdown": markdown,
    }
    payloadBytes, err := json.Marshal(payload)
    if err != nil {
        panic(err)
    }

    // Create request
    req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(payloadBytes))
    if err != nil {
        panic(err)
    }

    // Set headers
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    // Send request
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    // Read response
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    // Parse response
    var data map[string]interface{}
    if err := json.Unmarshal(body, &data); err != nil {
        panic(err)
    }

    fmt.Println("Slack blocks:", data["result"]["blocks"]["blocks"])
    fmt.Println("Block Kit URL:", data["result"]["blockKitUrl"])
}

Using the Block Kit URL¶

The response includes a blockKitUrl field that contains a URL to view the generated blocks in the Slack Block Kit Builder. You can use this URL to preview how your message will look in Slack and make any necessary adjustments.

Markdown Formatting Support¶

The Slack blocks format supports a subset of Markdown formatting:

Headers: Converted to bold text
Bold: Supported with **text** or __text__
Italic: Supported with *text* or _text_
Links: Supported with [text](url)
Lists: Supported with - item or * item
Code blocks: Supported with triple backticks
Inline code: Supported with single backticks
Block quotes: Supported with > text
Horizontal rules: Supported with --- or ***

Note that some Markdown features may be rendered differently in Slack compared to standard Markdown renderers.