Webhook Usage Instructions

This document specifies the input and output values for the webhook interface provided by users.

There are two ways to use the interface: 1. Message Trigger Type 2. Task Push Type
Message Trigger Type: Triggered by matching user messages, replacing the ansContent in the webhook with the answer.
Task Push Type: This requires you to have a certain understanding of the task-based conversation feature in your bot management system. The request parameters are the input parameters given by us when calling your interface, and the request result is the information we need you to return in the specified format within the interface.

Webhook (Message Trigger Type)

1. Authentication Method

Formula

sign=SHA1(integrationName&appKey&timestamp)

Where:

• integrationName: Integration name, the name configured in the webhook
• key: Authentication key, configured in the webhook
• timestamp: Timestamp, seconds from '1970-01-01 00:00:00' until now
• Data is concatenated with '&'

Authentication Data Example

Name	Value
integrationName	Integration One
key	221b368d7f5f597867f525971f28ff75
timestamp	1496631984

Computer Signature:

sign = sha1("Integration One&221b368d7f5f597867f525971f28ff75&1496631984") ->
96d8271cd705d3f134d215e9b3c27bb73f1132ed

Request URL

• POST HOST/{relative address}?timestamp={timestamp}&sign={signature}

Request Parameters

URL Parameters

Path	Type	Required	Description
timestamp	Integer	true	Timestamp
sign	String	true	Signature

Request Body

Path	Type	Required	Description
integrationName	String	true	Integration name
regex	String	true	Regular expression
questionContent	String	true	Question content
extra	Object	false	Additional parameter object
extra.weChatOpenId	String	false	If it's WeChat channel, it's the WeChat openId
customerExtra	Object	false	Custom additional object
customerExtra.customerId	Integer	false	User ID in customer service system

Request Result

Path	Type	Description
answerContent	String	Answer content

Example

$ curl 'HOST/API?timestamp=1513150103&sign=ab991af4ef65fc6061cf16c19d7d9d1bc1e12dcb' -i -X POST -H 'Content-Type: application/json' -d '{
          "integrationName" : "Integration One",
          "regex" : "[abc]",
          "questionContent" : "Question Content",
          "extra" : {
            weChatOpenId : "wechatId"
          }
        }'

Response

{
  "answerContent" : "This is the answer"
}

Webhook (Task Push Type)

Request Parameters

Path	Type	Required	Description
taskNodeId	Integer	true	Node ID, the ID where the current task-based conversation matches
sessionId	Integer	true	Session ID, the ID of the conversation record
timestamp	Long	true	Timestamp
sign	String	true	Signature
variables	Map<String, String>	false	Variable Map, variables collected in the task tree configuration
customerExtra	Object	false	Custom additional object
customerExtra.customerId	Integer	false	User ID in customer service system
customerExtra.callerNumber	String	false	Caller number of voice bot (for voice bot usage)
customerExtra.dialogueDesc	String	false	This field is used for special purposes. It's used to fulfill the requirement of passing custom information from the customer to the bot via webhook. First, in the customer service system, in the custom fields for customers, set a field named "c_cf_dialogueDesc" Then set the value of this field for the customer After that, open the chat plugin and add this field to the path parameters, the format is as follows: https://xxx.udesk.cn/im_client/?web_plugin_id=41597&c_cf_dialogueDesc=******* This way, the system will automatically pass the value of this parameter as a parameter named dialogueDesc into the webhook. Special reminder: Both the customer service system and path parameters are passed with the parameter name "c_cf_dialogueDesc"

Signature

• Content(key + taskNodeId + sessionId + timestamp)
• Method(md5Hex)

Where:

• key: Authentication key, configured in the webhook
• taskNodeId: Passed in the request body, the ID of the node where the current task tree is located
• sessionId: Passed in the request body, the identification ID of the current session
• timestamp: Passed in the request body, timestamp, seconds from '1970-01-01 00:00:00' until now
• Data is directly concatenated

Authentication Data Example

Name	Value
taskNodeId	100
sessionId	100
key	abcde
timestamp	1551510709

Computer Signature:

sign = md5Hex(abcde1001001551510709) ->
9195e2a5c1d84b86dc59819f29a0e300

Request Result

Path	Type	Description
resCode	Integer	Response code [0 success / -1 failure]
resError	String	Non-user-level error message
message	Message	User message
variables	Map<String, String>	Variable settings, you can modify the variable table
toTaskNodeId	Integer	Jump to task node ID, effective for action of jumping to node
routeType	Integer	Type of jump node (1. Direct trigger 2. Wait for reply)
command	String	Action command

Message

Path	Type	Required	Description
msgType	String	true	Message type
msgContent	Object	true	Message content

msg_type

Value	Description	Corresponding msgContent
plain	Plain text	String
rich	Rich text	String
selective_table	Selective table	selective_table
selective_list	Selective list	selective_list
show_product	Product display	show_product
selective_product	Product selection	show_product
custom_card	Card message	custom_card

selective_table

Path	Type	Description
title	String	Title
rowNumber	Integer	Number of rows
columnNumber	Integer	Number of columns
optionList	List<Option>	Option list

selective_list

Path	Type	Description
title	String	Title
optionList	List<Option>	Option list

show_product

Path	Type	Description
title	String	Title
showSize	Integer	Default display quantity
turnFlag	Integer	Carousel flag
productList	List<OptionalProduct>	Product list

custom_card

Path	Type	Description
id	Integer	Primary key
name	String	Name
turnFlag	Integer	Whether carousel flag 0 No 1 Yes default 0 Functionality for switching groups
showSize	Integer	Number of card lists displayed, effective when turnFlag=1
title	String	Title, if not empty, the title card is displayed
cardList	List<Object>	Card list
cardList[].id	Integer	Card ID
cardList[].type	Integer	Card type 1. Rich text card 2. FAQ recommendation list card
cardList[].isHit	Integer	Whether the card can be clicked Effective when type=1 0 No 1 Yes
cardList[].hitType	Integer	Card click effect Effective when type=1&isHit=1 1 Hyperlink 2 Reply message Reply message refers to providing a string of text to the user in the chat window
cardList[].hitContent	String	Card click content Effective when type=1&isHit=1 hitType=1 is the link address hitType=2 is the message content to be replied
cardList[].content	String	Rich text specific content Effective when type=1
cardList[].suggestContent	String	Text of FAQ recommendation cardEffective when type=2
cardList[].suggestList	List<Object>	List of recommended questions for FAQEffective when type=2
cardList[].suggestList[].id	Integer	Identifier ID of the question.Effective when type=2
cardList[].suggestList[].content	String	Content of the question.Effective when type=2
cardList[].suggestList[].type	Integer	Question typeEffective when type=2

optional_product

Path	Type	Description
id	Integer	ID
name	String	Product name
image	String	Product image
url	String	Product link
infoList	List<ProductInfo>	Product information

product_info

Path	Type	Description
info	String	Text
boldFlag	String	Bold flag
url	Integer	Product link
color	String	Color

option

Path	Type	Description
id	String	Option ID
value	String	Option value

Example

## appKey: abcde
## sign: md5Hex(abcde1001001551510709)
$ curl 'https://demo/webhook' -i -X POST -H 'Content-Type: application/json' -d '{
  "taskNodeId" : 100,
  "sessionId" : 100,
  "timestamp" : 1551510709,
  "variables" : {
	"city":"Beijing"，
	"name":"Li Hao"
   },
  "sign" : "9195e2a5c1d84b86dc59819f29a0e300",
}'

Response

{
  "resCode": 0,
  "message": {
    "msgType": "rich",
    "msgContent": "Content returned by webhook"
  }
}