DOCSEARCHbyAlgolia
Submit Docs

blinkbean/dingtalk

repository·master·Indexed 43 days ago

https://github.com/blinkbean/dingtalk

A Golang wrapper for the DingTalk robot API. It supports sending Text, Link, Markdown, ActionCard, and FeedCard message types, and provides tools for handling OutGoing webhook events via command registration and the OutGoingHandler.

Tokens
1.9K
Snippets
8
Records
8
Agent score
5%

What's inside blinkbean/dingtalk

  1. Implement OutGoing robot functionality

    master

    DingTalk OutGoing allows you to bind an HTTP POST endpoint to your robot. When a user @mentions the robot in a group, DingTalk sends a JSON payload to your endpoint, and your service can respond with a message.

    1. Enable Outgoing mechanism in DingTalk robot settings.
    2. Configure a public POST URL.
    3. Use RegisterCommand to map commands to logic and OutGoingHandler to serve the requests.

    Command Registration:

    • RegisterCommand(name string, execFunc ExecFunc, arity int, isAdmin bool)
      • name: The command trigger.
      • execFunc: A function func(args []string) []byte that processes the command and returns the response bytes.
      • arity: Number of arguments expected.
      • isAdmin: Whether the command is restricted to admins.
    // Define the command logic
outgoingFunc := func(args []string) []byte {
    // Return a message using the library's marshaler
    return NewTextMsg("hello").Marshaler()
}

// Register the command
RegisterCommand("hello", outgoingFunc, 2, true)

// Start the HTTP server to handle incoming DingTalk requests
http.Handle("/outgoing", &OutGoingHandler{})
_ = http.ListenAndServe(":8000", nil)

  3. Send Markdown messages

    master

    Send rich Markdown formatted messages.

    Advanced Markdown usage:

    • SendMarkDownMessageBySlice(title, text string, opts ...atOption): Allows passing a slice of strings for better readability.
    • DingMap(): A helper to create structured color/style maps for Markdown. Supported styles include RED, GREEN, BLUE, GOLD, H2, and N (normal).
    • SendDTMDMessage(title string, dtmdMap DingMap) error: Sends a DTMD (DingTalk Markdown) link message that allows users to click a link to trigger a specific command/value.
    // Using a slice for readability
msg := []string{
    "### Link test",
    "---",
    "- <font color=#00ff00 size=6>Red Text</font>",
    "- content2",
}
cli.SendMarkDownMessageBySlice("Markdown title", msg)

// Using DingMap for colors
dm := DingMap()
dm.Set("Success", GREEN)
dm.Set("Warning", BLUE)
cli.SendMarkDownMessageBySlice("color test", dm.Slice())

// Sending DTMD links
dtmdOrderMap := DingMap().
    Set("cmd1", "val1").
    Set("cmd2", "val2")
cli.SendDTMDMessage("DTMD title", dtmdOrderMap)

  4. Send Link messages

    master

    Send a message containing a title, description, image, and a clickable URL.

    • SendLinkMessage(title, text, picUrl, msgUrl string) error
    cli.SendLinkMessage("Title", "Description text", "https://example.com/pic.png", "https://example.com/link")

  5. Initialize the DingTalk client

    master

    You can initialize the client using either a list of tokens (for keyword-based robots) or a secret (for signature-based robots).

    • InitDingTalk(tokens []string, key string): Use this when your robot is configured with a custom keyword. The key is the keyword set in DingTalk. Defaults to . if not specified.
    • InitDingTalkWithSecret(tokens string, secret string): Use this for robots configured with a signature (secret). The tokens parameter is the access_token and secret is the signature secret.
    import "github.com/blinkbean/dingtalk"

func main() {
    // Using tokens and a keyword
    var dingToken = []string{"YOUR_TOKEN"}
    cli := dingtalk.InitDingTalk(dingToken, ".")
    
    // Using access token and secret (signature mode)
    // cli := dingtalk.InitDingTalkWithSecret("YOUR_TOKEN", "YOUR_SECRET")

    cli.SendTextMessage("content")
}

  6. Send Text messages

    master

    Send simple text messages to a group. You can optionally mention all members or specific users via mobile numbers.

    • SendTextMessage(content string, opt ...atOption) error
    • WithAtAll(): Mentions everyone in the group.
    • WithAtMobiles(mobiles []string): Mentions specific users by their mobile numbers.
    // Mention everyone
cli.SendTextMessage("content", WithAtAll())

// Mention specific users
mobiles := []string{"131********"}
cli.SendTextMessage("content", WithAtMobiles(mobiles))

  7. Send FeedCard messages

    master

    Send a list of feed cards, each containing a title, a message URL, and an image URL.

    • SendFeedCardMessage(feedCard []FeedCardLinkModel) error
    • FeedCardLinkModel fields: Title, MessageURL, PicURL.
    links := []FeedCardLinkModel{
    {
        Title:      "Feed 1",
        MessageURL: "https://example.com/1",
        PicURL:     "https://example.com/img1.png",
    },
    {
        Title:      "Feed 2",
        MessageURL: "https://example.com/2",
        PicURL:     "https://example.com/img2.png",
    },
}
cli.SendFeedCardMessage(links)

  8. Send ActionCard messages

    master

    ActionCards provide interactive cards with buttons. There are two types:

    1. Single Jump (整体跳转): The entire card acts as a single link.

      • SendActionSingleMessage(title, text string, opts ...actionCardOption)
      • WithCardSingleTitle(title string)
      • WithCardSingleURL(url string)

    2. Multi-Button (独立跳转): The card contains specific buttons that trigger different actions.

      • WithCardBtns(btns []ActionCardMultiBtnModel)
      • ActionCardMultiBtnModel fields: Title and ActionURL.
    // Single Jump
cli.SendActionSingleMessage("Title", "Text", WithCardSingleTitle("Click Me"), WithCardSingleURL("https://example.com"))

// Multi-Button
btns := []ActionCardMultiBtnModel{
    {Title: "Button 1", ActionURL: "https://url1.com"},
    {Title: "Button 2", ActionURL: "https://url2.com"},
}
cli.SendActionSingleMessage("Title", "Text", WithCardBtns(btns))