Send Message | docs.d3security

Last updated: Feb 27, 2024

Use in a playbook to send messages within an incident and in global chat. Replies from third-party integrations can be found within the context data.

Implementation	System
Command Category	System Utility
Tags	Communication Messaging

Inputs

Parameter Name	Required/Optional	Description	Sample Data
Recipient	Optional	Select the recipient(s) of this message. It can be a group, a single user, or the messaging integrations with the option 'Allow messages to also be sent through this connection' enabled.	User01
Content	Required	Message content.	Sample for plain text message: I am seeking approval. Sample for Sending Teams message with custom HTML content: { "type": "message", "text": "Hi <h1><b>this is mention message to notify the target users or groups</b></h1> <p>this is a custom html passage</p> <div> this is a division </div>, <at>target_user</at> <at>target_group(tag)</at>, please respond this message.", "textFormat": "xml", "entities": [ { "type": "mention", "text": "<at>target_user</at>", "mentioned": { "id": "84d5cca5-7cdf-4f35-b668-a875799d1fad", "name": "the user display name in message" } }, { "type": "mention", "text": "<at>target_group</at>", "mentioned": { "id": "84d5cca5-7cdf-4f35-b668-a875799d1fad", "name": "the group display name in message" } } ] } Sample for Sending Teams message with mention support and Adaptive Card with buttons: { "type": "message", "text": "<table style=\"border: 1px solid black;\"><tr><td width=\"80\" style=\"border: 1px solid black ;\">Foo</td><td style=\"border: 1px solid black ;\">Hi, <at>target_user</at>, please respond this message.</td><td width=\"65\" style=\"border: 1px solid black ;\">Foo2</td></tr><tr style=\"border: 1px solid black;\"><td style=\"border: 1px solid black;\">Bar1 </td><td style=\"border: 1px solid black;\">Bar2, <at>target_group</at> </td><td style=\"border: 1px solid black;\">Bar3</td></tr></table>", "textFormat": "xml", "entities": [ { "type": "mention", "text": "<at>target_user</at>", "mentioned": { "id": "84d5cca5-7cdf-4f35-b668-a875799d1fad", "name": "the user display name in message" } }, { "type": "mention", "text": "<at>target_group</at>", "mentioned": { "id": "ZjYyMWFkYmEtYTA5NS00NTVmLThlZTktNjNlNzYxNDlmZWVkIyMzMWIxNTdlMi01YTVkLTRiOGUtOWMxYS02Y2JmNGRlZTQ3NmQjI3RRSEpxb1h4MQ==", "name": "the group display name in message", "type": "tag" } } ], "attachments": [ { "contentType": "application/vnd.microsoft.card.adaptive", "content": { "type": "AdaptiveCard", "version": "1.3", "body": [ { "type": "TextBlock", "text": "And this mentions tag <at>d3support</at>!", "size": "Medium", "wrap": true }, { "type": "TextBlock", "text": "Connection ID: 2364", "separation": "none" }, { "type": "TextBlock", "text": "Comments", "wrap": true }, { "type": "Input.Text", "style": "text", "isMultiline": true, "id": "responseComment" } ], "msteams": { "entities": [ { "type": "mention", "text": "<at>d3support</at>", "mentioned": { "id": "ZjYyMWFkYmEtYTA5NS00NTVmLThlZTktNjNlNzYxNDlmZWVkIyMzMWIxNTdlMi01YTVkLTRiOGUtOWMxYS02Y2JmNGRlZTQ3NmQjI3RRSEpxb1h4MQ==", "name": "d3support", "type": "tag" } } ] }, "actions": [ { "type": "Action.Submit", "title": "Approve", "data": { "msteams": { "type": "invoke", "displayText": "Approve", "text": "text to bots approve", "value": { "respUrl": "<<UserActionRequiredURL>>", "action": 1 } } } }, { "type": "Action.Submit", "title": "Reject", "data": { "msteams": { "type": "invoke", "displayText": "Reject", "text": "text to bots decline ", "value": { "respUrl": "<<UserActionRequiredURL>>", "action": 2 } } } }, { "type": "Action.Submit", "title": "Custom Action Button", "data": { "msteams": { "type": "invoke", "value": { "respUrl": "<<UserActionRequiredURL>>", "customizedAction": "2000", "action": 3 } } } } ] } } ] }
Reply Mode	Required	The mode to determine if this message requires a response or approval. When it is specified as No Action, any external user actions will not be reponded.	Require Approval
Reply Due Time	Optional	The duration of time (in minutes) to wait for a reply.	100

Output

Return Data

The returned result of this command. If some required parameters are not defined, this returned data could be empty. The returned result can be passed down directly to a subsequent command in playbooks.

Sample Data

JSON

Successful

Context Data

The response data from the utility command.

Sample Data

JSON

{
    "action": "1",
    "comment": "",
    "actionName": "Approved",
    "Approved by": "User01"
}

Remote Command API

The D3 command API allows you to send requests to D3 SOAR to execute this utility command via REST API.

Request

POST

https:/{base_url}/{api_namespace}/api/Command/SendMessage

Headers

Please refer to the page Webhook Configuration Guide - Authentication Method: API Keys for more details.

Request Body

JSON

{
  "Username": "<Username here>",
  "Site": "<Site here>",
  "CommandParams": {
    "Recipient": "<Recipient here>",
    "Content": "<Content here>
    "Reply Mode": "<Reply Mode here>",
    "Reply Due Time": "<Reply Due Time here>"
  }
}

Body Parameters

Parameter Name	Type	Required/Optional	Description
Username	`String`	Required	The username of your D3 SOAR account.
Site	`String`	Required	The D3 SOAR site to run the remote command.
Recipient	`Text`	Optional	Select the recipient(s) of this message. It can be a group, a single user, or the messaging integrations with the option 'Allow messages to also be sent through this connection' enabled.
Content	`Text`	Required	Message content.
Reply Mode	`Text`	Required	The mode to determine if this message requires a response or approval. When it is specified as No Action, any external user actions will not be reponded.
Reply Due Time	`Number`	Optional	The duration of time (in minutes) to wait for a reply.

Sample Request

Sample Data

JSON

{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Recipient": "Administrators",
    "Content": "\r\nSample for plain text message: I am seeking approval.\r\n\r\nSample for Sending Teams message with custom HTML content:\r\n    {\r\n        \"type\": \"message\",\r\n        \"text\": \"Hi 
this is mention message to notify the target users or groups
 
this is a custom html passage

 
 this is a division 
, target_user target_group(tag), please respond this message.\",\r\n\t    \"textFormat\": \"xml\",\r\n        \"entities\": [\r\n            {\r\n                \"type\": \"mention\",\r\n                \"text\": \"target_user\",\r\n                \"mentioned\": {\r\n                    \"id\": \"84d5cca5-7cdf-4f35-b668-a875799d1fad\",\r\n                    \"name\": \"the user display name in message\"\r\n                }\r\n            },\r\n            {\r\n                \"type\": \"mention\",\r\n                \"text\": \"target_group\",\r\n                \"mentioned\": {\r\n                    \"id\": \"84d5cca5-7cdf-4f35-b668-a875799d1fad\",\r\n                    \"name\": \"the group display name in message\"\r\n                }\r\n            }\r\n        ]\r\n    }\r\n\r\nSample for Sending Teams message with mention support and Adaptive Card with buttons:\r\n\t{\r\n        \"type\": \"message\",\r\n        \"text\": \"
Foo	Hi, target_user, please respond this message.	Foo2
Bar1 	Bar2, target_group 	Bar3
\",\r\n\t    \"textFormat\": \"xml\",\r\n        \"entities\": [\r\n            {\r\n                \"type\": \"mention\",\r\n                \"text\": \"target_user\",\r\n                \"mentioned\": {\r\n                    \"id\": \"84d5cca5-7cdf-4f35-b668-a875799d1fad\",\r\n                    \"name\": \"the user display name in message\"\r\n                }\r\n            },\r\n            {\r\n                \"type\": \"mention\",\r\n                \"text\": \"target_group\",\r\n                \"mentioned\": {\r\n                    \"id\": \"ZjYyMWFkYmEtYTA5NS00NTVmLThlZTktNjNlNzYxNDlmZWVkIyMzMWIxNTdlMi01YTVkLTRiOGUtOWMxYS02Y2JmNGRlZTQ3NmQjI3RRSEpxb1h4MQ==\",\r\n                    \"name\": \"the group display name in message\",\r\n                    \"type\": \"tag\"\r\n                }\r\n            }\r\n        ],\r\n        \"attachments\": [\r\n            {\r\n                \"contentType\": \"application/vnd.microsoft.card.adaptive\",\r\n                \"content\": {\r\n                    \"type\": \"AdaptiveCard\",\r\n                    \"version\": \"1.3\",\r\n                    \"body\": [\r\n                        {\r\n                            \"type\": \"TextBlock\",\r\n                            \"text\": \"**And this mentions tag** d3support!\",\r\n                            \"size\": \"Medium\",\r\n                            \"wrap\": true\r\n                        },\r\n                        {\r\n                            \"type\": \"TextBlock\",\r\n                            \"text\": \"**Connection ID:** 2364\",\r\n                            \"separation\": \"none\"\r\n                        },\r\n                        {\r\n                            \"type\": \"TextBlock\",\r\n                            \"text\": \"Comments\",\r\n                            \"wrap\": true\r\n                        },\r\n                        {\r\n                            \"type\": \"Input.Text\",\r\n                            \"style\": \"text\",\r\n                            \"isMultiline\": true,\r\n                            \"id\": \"responseComment\"\r\n                        }\r\n                    ],\r\n                    \"msteams\": {\r\n                        \"entities\": [\r\n                            {\r\n                                \"type\": \"mention\",\r\n                                \"text\": \"d3support\",\r\n                                \"mentioned\": {\r\n                                    \"id\": \"ZjYyMWFkYmEtYTA5NS00NTVmLThlZTktNjNlNzYxNDlmZWVkIyMzMWIxNTdlMi01YTVkLTRiOGUtOWMxYS02Y2JmNGRlZTQ3NmQjI3RRSEpxb1h4MQ==\",\r\n                                    \"name\": \"d3support\",\r\n                                    \"type\": \"tag\"\r\n                                }\r\n                            }\r\n                        ]\r\n                    },\r\n                    \"actions\": [\r\n                        {\r\n                            \"type\": \"Action.Submit\",\r\n                            \"title\": \"Approve\",\r\n                            \"data\": {\r\n                                \"msteams\": {\r\n                                    \"type\": \"invoke\",\r\n                                    \"displayText\": \"Approve\",\r\n                                    \"text\": \"text to bots approve\",\r\n                                    \"value\": {\r\n                                        \"respUrl\": \"<>\",\r\n                                        \"action\": 1\r\n                                    }\r\n                                }\r\n                            }\r\n                        },\r\n                        {\r\n                            \"type\": \"Action.Submit\",\r\n                            \"title\": \"Reject\",\r\n                            \"data\": {\r\n                                \"msteams\": {\r\n                                    \"type\": \"invoke\",\r\n                                    \"displayText\": \"Reject\",\r\n                                    \"text\": \"text to bots decline \",\r\n                                    \"value\": {\r\n                                        \"respUrl\": \"<>\",\r\n                                        \"action\": 2\r\n                                    }\r\n                                }\r\n                            }\r\n                        },\r\n                        {\r\n                            \"type\": \"Action.Submit\",\r\n                            \"title\": \"Custom Action Button\",\r\n                            \"data\": {\r\n                                \"msteams\": {\r\n                                    \"type\": \"invoke\",\r\n                                    \"value\": {\r\n                                        \"respUrl\": \"<>\",\r\n\t\t\t\t\t\t\t\t\t\t\"customizedAction\": \"2000\",\r\n                                        \"action\": 3\r\n                                    }\r\n                                }\r\n                            }\r\n                        }\r\n                    ]\r\n                }\r\n            }\r\n        ]\r\n    }\r\n",
    "Reply Mode": "Require Approval",
    "Reply Due Time": 100
  }
}

Response

Response Fields

Field Name	Type	Description
error	`Text`	The error message if the API request has failed.
returnData	`Text`	The return data from the API request.
contextData	`JSON Object`	The context data from the API request.

Sample Response

JSON

{
    "error": "",
    "returnData": "Successful",
    "contextData": {
      "action": "1",
      "comment": "",
      "actionName": "Approved",
      "Approved by": "User01"
    }
}