Develop the Event Push Service

To develop a push service for event subscriptions, you can choose one of three push modes: Stream mode, HTTP mode, or SyncHTTP. Follow the steps in this document to complete the development.

Develop Stream Mode (Recommended)

Java
Golang

Prerequisites

A runtime environment with public network access.
JDK 1.8 or later.

Install the SDK

Add the dependency to your project’s pom.xml file or download the corresponding JAR package. You can view and download the latest SDK version on Maven Central.

<dependency>
  <groupId>com.dingtalk.open</groupId>
  <artifactId>app-stream-client</artifactId>
  <version>{sdk-version}</version>
</dependency>

Server-Side Integration

Parameter	Description
`${clientId}`	The unique identity of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client ID corresponds to the AppKey/SuiteKey of legacy apps.
`${clientSecret}`	The call secret of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client Secret corresponds to the AppSecret/SuiteSecret of legacy apps.

public static void main(String[] args) {
  OpenDingTalkStreamClientBuilder
    .custom()
    .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
    //Register the event listener
    .registerAllEventListener(new GenericEventListener() {
      public EventAckStatus onEvent(GenericOpenDingTalkEvent event) {
        try {
          //Unique event ID
          String eventId = event.getEventId();
          //Event type
          String eventType = event.getEventType();
          //Event creation time
          Long bornTime = event.getEventBornTime();
          //Get the event body
          JSONObject bizData = event.getData();
          //Process the event
          process(bizData);
          //Consumed successfully
          return EventAckStatus.SUCCESS;
        } catch (Exception e) {

Sample Code

The following examples use a Bot callback and an interactive Card callback for reference.Bot Callback

public static void main(String[] args) throws Exception {
  OpenDingTalkStreamClientBuilder
    .custom()
    .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
    //Register the Bot listener
    .registerCallbackListener("${topic}", robotMessage -> {
      log.info("receive robotMessage, {}", robotMessage);
      //Process the Bot callback based on your business needs
      return new JSONObject();

    })
    .build().start();
}

Parameter	Description
`clientId`	The unique identity of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client ID corresponds to the AppKey/SuiteKey of legacy apps.
`clientSecret`	The call secret of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client Secret corresponds to the AppSecret/SuiteSecret of legacy apps.
`topic`	The Bot callback name. Fixed value: `/v1.0/im/bot/messages/get`.

Card CallbackFor details, see Interactive Card - Event Callback.

public static void main(String[] args) throws Exception {
        OpenDingTalkStreamClientBuilder
                .custom()
                .credential(new AuthClientCredential("${clientId}", "${clientSecret}"))
                //Register the Card callback listener
                .registerCallbackListener("/v1.0/card/instances/callback", callbackData -> {
                    log.info("receive call back request, {}", callbackData);
                    //your code is here

                    //Change the card content and return a response based on your business needs
                    CardCallbackResponse resp = new CardCallbackResponse();
                    return resp;

                })
                .build().start();
}

Parameter	Description
`clientId`	The unique identity of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client ID corresponds to the AppKey/SuiteKey of legacy apps.
`clientSecret`	The call secret of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client Secret corresponds to the AppSecret/SuiteSecret of legacy apps.
`topic`	The registered Card callback name. Fixed value: `/v1.0/card/instances/callback`.

Prerequisites

A runtime environment with public network access.
Runtime environment 1.16 or later.

Install the SDK

go get github.com/open-dingtalk/dingtalk-stream-sdk-go/v0.0.5

Server-Side Integration

Parameter	Description
`${clientId}`	The unique identity of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client ID corresponds to the AppKey/SuiteKey of legacy apps.
`${clientSecret}`	The call secret of a DingTalk internal app or a third-party enterprise app. For details, see Client ID/Client Secret. Client Secret corresponds to the AppSecret/SuiteSecret of legacy apps.

func main() {
  e := clientV2.
    NewBuilder().
    Credential(&clientV2.AuthClientCredential{ClientId: "${clientId}", ClientSecret: "${clientSecret}"}).
    //Listen for Open Platform events
    RegisterAllEventHandler(func(event *clientV2.GenericOpenDingTalkEvent) clientV2.EventStatus {
      println("receive event ", event.Data)
      //Return clientV2.EventStatusSuccess on success, clientV2.EventStatusLater on failure
      return clientV2.EventStatusSuccess
    }).
    Build().
    Start(context.Background())

  if e != nil {
    println("failed to start stream client", e.Error())
    return
  }

  select {}
}

Sample Code

The following example uses a Bot callback for reference.

func OnChatReceive(ctx context.Context, data *chatbot.BotCallbackDataModel) error {
  return nil
}

func StartRobot() {
  logger.SetLogger(logger.NewStdTestLogger())
  cli := client.NewStreamClient(
    client.WithAppCredential(client.NewAppCredentialConfig(${clientId}, ${clientSecret})),
    client.WithUserAgent(client.NewDingtalkGoSDKUserAgent()),
    client.WithSubscription(utils.SubscriptionTypeKCallback, ${topic}, chatbot.NewDefaultChatBotFrameHandler(OnChatReceive).OnEventReceived),
  )

  err := cli.Start(context.Background())
  if err != nil {
    panic(err)
  }

  defer cli.Close()

  select {}
}

Parameter	Description
`clientId`	The AppKey for internal app development / the SuiteKey for third-party enterprise apps.
`clientSecret`	The AppSecret for internal app development / the SuiteSecret for third-party enterprise apps.
`topic`	The Bot callback name. Fixed value: `/v1.0/im/bot/messages/get`.

Other Language Support

Java SDK Quick-Start Project

Golang SDK and Sample Code

Python SDK and Sample Code

Node.js SDK and Sample Code

If you run into any issues during the process, you can submit feedback and discuss them through Technical Support.

Error Codes

When receiving an event returns the following error code, resolve it according to the solution.

Error Code (errCode)	Error Message (errMsg)	Description	Solution
20001	Affected by exceeding the call quota, your message service is currently suspended. Contact your organization administrator to handle this. An `errMsg` field is added to the received message to display the error message.	The received message has no content and no `text` or `content` field. Log in to the Developer Console to view the call quota.	Upgrade to DingTalk Professional Edition or purchase an add-on package.

FAQ

Can I start multiple event listeners in one application?

Yes. You can start multiple event listening services and configure multiple Stream clients as needed.

Internal app: An enterprise only needs to configure one Stream client.
Third-party enterprise app: Listen to that third-party enterprise app only to obtain the event subscription content of the currently authorized enterprise.

Develop HTTP Mode

Prerequisites

Understand the Configure HTTP Push (Not Recommended) process.
Development environment: Maven 3, JDK 1.8 or later.

Integrate the Event Message Encryption/Decryption Class

package com.dingtalk.open;

import java.io.ByteArrayOutputStream;
import java.nio.charset.Charset;
import java.security.MessageDigest;
import java.security.Permission;
import java.security.PermissionCollection;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.Random;
import java.security.Security;
import java.lang.reflect.Field;

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

import com.alibaba.fastjson.JSON;

import org.apache.commons.codec.binary.Base64;

For more languages, see dingtalk-callback-Crypto.

Write the HTTP Push Server Code

Receive event messages

Parameter	Description
`msg_signature`	The message body signature.
`timestamp`	The timestamp.
`nonce`	A random string.
`json`	The encrypted event data body.

import com.alibaba.fastjson.JSONObject;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
public class CallbackController {

  @PostMapping("{the urlpath of your registered HTTP address}")
  public Map<String, String> callBack(
            @RequestParam(value = "msg_signature", required = false) String msg_signature,
            @RequestParam(value = "timestamp", required = false) String timeStamp,
            @RequestParam(value = "nonce", required = false) String nonce,
            @RequestBody(required = false) JSONObject json) {

    }
}

Respond to event messages

When you receive a POST verification request from the Open Platform, you must decrypt it and respond within 2500 ms.

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class CallbackController {

    private final Logger bizLogger = LoggerFactory.getLogger(getClass());
    @PostMapping("{the urlpath of your registered HTTP address}")
    public Map<String, String> callBack(
            @RequestParam(value = "msg_signature", required = false) String msg_signature,
            @RequestParam(value = "timestamp", required = false) String timeStamp,
            @RequestParam(value = "nonce", required = false) String nonce,
            @RequestBody(required = false) JSONObject json) {

Your HTTP push server is now developed. You can follow the Configure HTTP Push (Not Recommended) process to verify that the integration is correct.

Develop SyncHTTP Mode

Prerequisites

Understand the Configure SyncHTTP Push (Not Recommended) process.
Development environment: Maven 3, JDK 1.8 or later.

Integrate the Event Message Encryption/Decryption Class

package com.dingtalk.open;

import java.io.ByteArrayOutputStream;
import java.nio.charset.Charset;
import java.security.MessageDigest;
import java.security.Permission;
import java.security.PermissionCollection;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import java.util.Random;
import java.security.Security;
import java.lang.reflect.Field;

import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

import com.alibaba.fastjson.JSON;

import org.apache.commons.codec.binary.Base64;

For more languages, see dingtalk-callback-Crypto.

Write the SyncHTTP Push Server Code

Receive event messages

Parameter	Description
`msg_signature`	The message body signature.
`timestamp`	The timestamp.
`nonce`	A random string.
`json`	The encrypted event data body.

import com.alibaba.fastjson.JSONObject;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
public class CallbackController {

  @PostMapping("{the urlpath of your registered HTTP address}")
  public Map<String, String> callBack(
            @RequestParam(value = "msg_signature", required = false) String msg_signature,
            @RequestParam(value = "timestamp", required = false) String timeStamp,
            @RequestParam(value = "nonce", required = false) String nonce,
            @RequestBody(required = false) JSONObject json) {

    }
}

Respond to event messages

When you receive a POST verification request from the Open Platform, you must decrypt it and respond within 2500 ms.

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class CallbackController {

    private final Logger bizLogger = LoggerFactory.getLogger(getClass());
    @PostMapping("{the urlpath of your registered HTTP address}")
    public Map<String, String> callBack(
            @RequestParam(value = "msg_signature", required = false) String msg_signature,
            @RequestParam(value = "timestamp", required = false) String timeStamp,
            @RequestParam(value = "nonce", required = false) String nonce,
            @RequestBody(required = false) JSONObject json) {

Platform overview

Developer guide

Build a bot app

Event subscription

Getting Started

App Types & Access

Robots

Message Templates & Notifications

Event Subscription & Push

Security & Compliance

Connectors

Resources & Rate Limits

Sign-in & SSO

Develop Stream Mode (Recommended)

Sample Code

Sample Code

Other Language Support

Java SDK Quick-Start Project

Golang SDK and Sample Code

Python SDK and Sample Code

Node.js SDK and Sample Code

Error Codes

FAQ

Develop HTTP Mode

Develop SyncHTTP Mode

​Develop Stream Mode (Recommended)

​Sample Code

​Sample Code

​Other Language Support

Java SDK Quick-Start Project

Golang SDK and Sample Code

Python SDK and Sample Code

Node.js SDK and Sample Code

​Error Codes

​FAQ

​Develop HTTP Mode

​Develop SyncHTTP Mode

Develop Stream Mode (Recommended)

Sample Code

Sample Code

Other Language Support

Error Codes

FAQ

Develop HTTP Mode

Develop SyncHTTP Mode