Rule Engine API

API Declaration

The "token" param must be contained in the header of the https request when calling the API.

Token is the only global API call credential for the Sobot API open platform. It is used when developers call the business APIs and thus should be properly kept. At least 32 chars should be reserved to store token. The validity period of token is currently 24 hours. It needs to be refreshed regularly or reacquired according to the token failure prompt returned by the API. When requesting the token API, regardless of the existence of token, a new token will be returned and its expiry time will be reset (currently 24 hours).

Token usage description:

1. Developers need to obtain and manage the token uniformly. When calling the Sobot open APIs of various business, they should use the same token, instead of refreshing and obtaining new tokens for each business. Otherwise, it will easily lead to token invalidation and affect the normal API call.
2. The current validity period of the token is transmitted by the returned expire_in, which is currently a value within 86,400 s. Developers need to refresh the new token in advance based on this valid time.
3. Developers should reacquire the token according to the token invalidation prompt returned by the API.

API Call

● Get the Access Token Code

API description:

Get the open API token, which is only applicable to all APIs of Sobot Open Platform v5.0. Contact the Sobot after-sales service personnel to get appid and app_key in the API.

Request method:

GET

Request URL:

 https://sg.sobot.io/api/get_token

Request param:

Param	Type	Required	Description
appid	String	Yes	API credential ID, the unique API call credential ID for the 3rd-party users
create_time	String	Yes	Timestamp (s), e.g.: timestamp 1569397773 for 2019-09-25 15:49:33
sign	String	Yes	Signature, md5(appid + create_time + app_key) sign signature, app_key is private key

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message
item	Object	No	Return object

item object:

Param	Type	Required	Description
token	String	Yes	token code
expires_in	String	Yes	Credential valid time

Timestamp conversion tool:

 https://www.unixtimestamp.com/

sign signature generation example:

E.g., appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") is 258eec3118705112b2c53dc8043d4d34.

Request example:

curl  https://sg.sobot.io/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

Return example:

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "success"
}

● webhook trigger

API description:

API type: Active call API

API function: Trigger the Rule Engine canvas by calling the API on behalf of the user.

QPS limit: The QPS limit for a single trigger ID in the API is 50 times/second. When exceeding the limit, API calls will be limited, which may affect your business. Please call reasonably.

Request method:

POST

Request URL:

https://sg.sobot.io/logi-flow/webhook/trigger

Request headers：

Param	Type	Required	Description
trigger-id	String	Yes	trigger-id
secret	String	Yes	secret
token	String	Yes	token

Request param:

Param	Type	Required	Description
Contact_id	String	Yes	Customer source field「Customizable Field Name in the System」
nick	String	No	User nickname「Create for customers when the user does not exist」
extParam	String	No	Additional information「Limit 1000 characters, to be used with webhook app」

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code

Request example:

curl --request POST \
  --url https://sg.sobot.io/logi-flow/webhook/trigger \
  --header 'content-type: application/json' \
  --header 'trigger-id: 1760950090021666816' \
  --header 'token: e41fcc4cdff748d0999ce6eac28c0dd7' \
  --header 'secret: c00b6e45bbe346e8bd86e51d2fea06ca' \
  --data '{ Your JSON Data here }'

Return example:

{
  "ret_code": "000000"
}

● webhook app

API Description:

API type: Callback API

API function: Receive webhook App execution messages by specifying an HTTP URL.

Request method:

POST/PUT

Request param:

Param	Type	Required	Description
id	String		Customer ID
pid	String		Company ID
nick	String		User Nickname
uname	String		Real Name
email	String		Email「Multiple email addresses separated by ";"」
tel	String		Phone Number「Multiple phone numbers separated by ";"」
qq	String		qq
remark	String		remark
is_vip	String		Customer Level 0: Normal 1: VIP
vip_level	String		VIP Level
user_label	String		Customer Label「Multiple Labels separated by ","」
face	String		face
ex_fields	Object		Extended Fields
webhook_info	Object		Webhook trigger information

Request example:

{
  "id": "123",
  "pid": "456",
  "nick": "John",
  "uname": "John Doe",
  "email": "15612661266@163.com;15612661267@163.com",
  "tel": "1234567890",
  "qq": "123456",
  "remark": "This is a remark",
  "is_vip": "0",
  "vip_level": "Gold",
  "user_label": "581dfa5ff16644619d8a7e1a45632a79,33d090699539491d9a0cc75f896453bc",
  "face": "https://example.com/avatar.jpg",
  "ex_fields": {
    "7dcf2982a3bc4afaa5351500b8e2e21c": "622453954796438,698821015202242",
    "899f53ad57fd45beaab0628981d87e2b": "2024-03-26",
    "bc41e13cde264af88aceba783444067d": "622107455027943",
    "040778587416412fba9941ea482407f2": "123"
    },
  "webhook_info":{
    "Contact_id":"12123444448",
    "trigger-id":"1854426358074904576",
    "extParam":"this is my extParam"
  }
}

Response explanation: After receiving the receipt, the HTTP status code of the response must be 200, and the response body format should be as follows. Otherwise, the push will fail, triggering a retry.

Return example:

{
  "code": 0,
  "status": 0
}

Return param:

Param	Type	Required	Description
code	Integer		Return code
status	Integer		Execution Status 0 - Success, 1 - Failure

Retry: After the first push fails, a retry will be made at intervals of 1 minute and 5 minutes until the push is successful. If it fails after 3 push attempts, no further retries will be made.

Error code

● Operation Done

HTTP status code	Error code	Error description
200	000000	Operation done (Any code other than this code is an error code)

● System Exception

HTTP status code	Error code	Error description
200	900001	Null token
200	900002	Token expired. Get a new one
200	900003	Incorrect signature
200	900004	Company api configuration info not found
200	999999	Unknown System Exception

● Business Exception

HTTP status code	Error code	Error description
400	910021	Missing trigger-id/token parameter
400	910022	Illegal trigger-id/token parameter
400	910023	Illegal customer ID field parameter
400	910024	triggerId exceeds the QPS limit
400	910025	Canvas not activated
400	910026	No matching customer