Message notification types

This topic describes the message notification types and data formats in DingTalk.

DingTalk message notification types

Work notification messages: Notification messages pushed to employees on behalf of a micro app in the work notification chat of an organization. Examples include birthday greetings and onboarding reminders.

Text message (text)

{
    "msgtype": "text",
    "text": {
        "content": "Monthly meeting notification"
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	text	Message type. Set to `text` for text messages.
content	String	Yes	Monthly meeting notification	Message content. Up to 500 characters are recommended.

Message sample

Image message

{
    "msgtype": "image",
    "image": {
        "media_id": "@lADOADmaWMzazQKA"
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	image	Message type. Set to `image` for image messages.
media_id	String	Yes	@lADOADmaWMzazQKA	The media ID. Call the Upload media files API to obtain the `mediaId` parameter value. A size of 600 x 400 pixels with an aspect ratio of 3:2 is recommended.

Message sample

Voice message

{
    "msgtype": "voice",
    "voice": {
       "media_id": "@lADOADmaWMzazQKA",
       "duration": "10"
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	voice	Message type. Set to `voice` for voice messages.
media_id	String	Yes	@lADOADmaWMzazQKA	The media file ID. Call the Upload media files API to obtain this value.
duration	String	Yes	50	A positive integer less than 60 that indicates the audio duration.

Message sample

File message

{
    "msgtype": "file",
    "file": {
       "media_id": "MEDIA_ID"
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	file	Message type. Set to `file` for file messages.
media_id	String	Yes	@lADOADmaWMzazQKA	The media file ID. The referenced media file must not exceed 10 MB. Call the Upload media files API to obtain this value.

Message sample

Link message

{
    "msgtype": "link",
    "link": {
        "messageUrl": "http://s.dingtalk.io/market/dingtalk/error_code.php",
        "picUrl":"@lALOACZwe2Rk",
        "title": "Test",
        "text": "Test"
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	link	Message type. Set to `link` for link messages.
link.messageUrl	String	Yes	http://dingtalk.io	The URL to open when the message is clicked. When the message is sent to a mini program, a mini program redirect URL is supported. See Message link description.
link.picUrl	String	Yes	@lADOADmaWMzazQKA	Call the Upload media files API to obtain this value.
link.title	String	Yes	Link message test	The message title. Up to 100 characters are recommended.
link.text	String	Yes	Message content test	The message description. Up to 500 characters are recommended.

Message sample

OA message

{
     "msgtype": "oa",
     "oa": {
        "message_url": "http://dingtalk.io",
        "head": {
            "bgcolor": "FFBBBBBB",
            "text": "Header title"
        },
        "body": {
            "title": "Body title",
            "form": [
                {
                    "key": "Name:",
                    "value": "John"
                },
                {
                    "key": "Age:",
                    "value": "20"
                },
                {
                    "key": "Height:",
                    "value": "1.8 m"
                },
                {
                    "key": "Weight:",
                    "value": "65 kg"
                },
                {
                    "key": "Education:",
                    "value": "Bachelor's degree"
                },
                {
                    "key": "Hobbies:",
                    "value": "Ball games, listening to music"
                }
            ],
            "rich": {
                "num": "15.6",
                "unit": "USD"
            },
            "content": "Long text content long text content long text content long text content",
            "image": "@lADOADmaWMzazQKA",
            "file_count": "3",
            "author": "Jane "
        }
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	oa	Message type. Set to `oa` for OA messages.

OA message body parameters

Name	Type	Required	Example	Description
oa.message_url	String	Yes	http://dingtalk.io	The URL to open when the message is clicked. When the message is sent to a mini program, a mini program redirect URL is supported. See Message link description.
oa.pc_message_url	String	No	http://dingtalk.io	The URL to open when the message is clicked on the desktop client.
oa.head	JSON Object	Yes		The message header.
oa.head.bgcolor	String	Yes	FFBBBBBB	The font color of the message header title. The length is limited to 8 English characters. The first 2 characters indicate transparency, and the last 6 characters indicate the color value. Do not add `0x`.
oa.head.text	String	Yes	Header title	The message header title. For Send work notifications, this parameter is replaced with the current app name.
oa.status_bar	JSON Object	No		The message status bar. Only the `userid` list of recipients is supported. A maximum of 5 user IDs is allowed. Note Department ID lists are not supported, and `to_all_user` cannot be set to `true`.
oa.status_bar.status_value	String	No	In progress	The status bar text.
oa.status_bar.status_bg	String	No	0xFFF65E5E	The status bar background color. The default is black. The recommended format is `0xFF` followed by a 6-digit color value.
oa.body	JSON Object	Yes		The message body.
oa.body.title	String	No	Body title	The message body title. Up to 50 characters are recommended.
oa.body.form	Array[JSON Object]	No		The message body form. A maximum of 6 entries are displayed. Additional entries are hidden.
oa.body.form.key	String	No	Name	The keyword in the message body.
oa.body.form.value	String	No	John	The value corresponding to the keyword in the message body.
oa.body.rich	JSON Object	No		The single-line rich text information.
oa.body.rich.num	String	No	15.6	The number in the single-line rich text.
oa.body.rich.unit	String	No	USD	The unit in the single-line rich text.
oa.body.content	String	No	Long text content	The message body content. A maximum of 3 lines is displayed.
oa.body.image	String	No	@lADOADmaWMzazQKA	The image in the message body. The `@mediaId` image resource is supported. Call the Upload media files API to obtain this value. A size of 600 x 400 pixels with an aspect ratio of 3:2 is recommended.
oa.body.file_count	String	No	3	The custom number of attachments. This number is for display only and is not verified by DingTalk.
oa.body.author	String	No	Jane	The custom author name.

Message sample

Markdown message

{
    "msgtype": "markdown",
    "markdown": {
        "title": "Content displayed on the first screen of the chat",
        "text": "# This is text that supports markdown   \n   ## Heading 2    \n   * List item 1   \n  "
    }
}

Markdown syntax

Title
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
 
Quote
> A man who stands for nothing will fall for anything.
 
Bold, Italic
**bold**
*italic*
 
Link
[this is a link](http://name.com)
 
Image

 
Bulleted List
- item1
- item2
 
Numbered List
1. item1
2. item2

Line break
  \n  (It is recommended to add 2 spaces before and after \n)

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	markdown	Message type. Call the Upload media files API to obtain this value. Set to `markdown` for Markdown messages.
title	String	Yes	Test title	The content displayed on the first screen of the chat.
text	String	Yes	Test content	The Markdown-formatted message. The maximum length is 5,000 characters.

Message sample

Card message

Card messages support the overall-redirect ActionCard style and the independent-redirect ActionCard style:

The overall-redirect ActionCard style supports a single click action. The single_title and single_url parameters are required.

{
    "msgtype": "action_card",
    "action_card": {
        "title": "Text displayed in the chat list and notifications",
        "markdown": "Body content in Markdown format",
        "single_title": "View details",
        "single_url": "https://open.dingtalk.com"
    }
}

The independent-redirect ActionCard style supports multiple click actions. The btn_orientation and btn_json_list parameters are required.

{
    "msgtype": "action_card",
    "action_card": {
        "title": "Text displayed in the chat list and notifications",
        "markdown": "Body content in Markdown format",
        "btn_orientation": "1",
        "btn_json_list": [
            {
                "title": "Button one",
                "action_url": "https://www.taobao.com"
            },
            {
                "title": "Button two",
                "action_url": "https://www.tmall.com"
            }
        ]
    }
}

Parameters

Name	Type	Required	Example	Description
msgtype	String	Yes	action_card	Message type. Set to `action_card` for card messages.
action_card.markdown	String	Yes	Body content in Markdown format	The message content. Markdown is supported. Follow the standard Markdown syntax. Up to 1,000 characters are recommended.
action_card.title	String	No	Test title	The text displayed in the chat list and notifications.
action_card.single_title	String	No	View details	The title used with the overall-redirect ActionCard style. Must be set together with `single_url`. The maximum length is 20 characters. Note For the overall-redirect ActionCard style, single_title and single_url are required.
action_card.single_url	String	No	https://open.dingtalk.com	The URL to open when the message is clicked. Call the Upload media files API to obtain this value. When the message is sent to a mini program, a mini program redirect URL is supported. The maximum length is 500 characters.
action_card.btn_orientation	String	No	0	The button layout used with the independent-redirect ActionCard style: - 0: vertical - 1: horizontal Must be set together with `btn_json_list`.
action_card.btn_json_list	JSONArray	No		The button list used with the independent-redirect ActionCard style. Must be set together with `btn_orientation`. The total length must not exceed 1,000 characters. Note For the independent-redirect ActionCard style, `btn_json_list` and `btn_orientation` are required.
action_card.btn_json_list.title	String	No	Two buttons	The button title used with the independent-redirect ActionCard style. The maximum length is 20 characters.
action_card.btn_json_list.action_url	String	No	https://www.tmall.com	The redirect URL used with the independent-redirect ActionCard style. The maximum length is 700 characters.

Message sample

A message sent with the overall-redirect ActionCard message type appears as follows:
A message sent with the independent-redirect ActionCard message type appears as follows:

API calling guide

Authentication & authorization

Contacts

Calendar

Conferencing

AI Table

Docs & files

IM

DingTalk message notification types

Text message (text)

Parameters

Message sample

Image message

Parameters

Message sample

Voice message

Parameters

Message sample

File message

Parameters

Message sample

Link message

Parameters

Message sample

OA message

Parameters

OA message body parameters

Message sample

Markdown message

Markdown syntax

Parameters

Message sample

Card message

Parameters

Message sample

​DingTalk message notification types

​Text message (text)

​Parameters

​Message sample

​Image message

​Parameters

​Message sample

​Voice message

​Parameters

​Message sample

​File message

​Parameters

​Message sample

​Link message

​Parameters

​Message sample

​OA message

​Parameters

​OA message body parameters

​Message sample

​Markdown message

​Markdown syntax

​Parameters

​Message sample

​Card message

​Parameters

​Message sample

DingTalk message notification types

Text message (text)

Parameters

Message sample

Image message

Parameters

Message sample

Voice message

Parameters

Message sample

File message

Parameters

Message sample

Link message

Parameters

Message sample

OA message

Parameters

OA message body parameters

Message sample

Markdown message

Markdown syntax

Parameters

Message sample

Card message

Parameters

Message sample