Enterprise actively sends offline message 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
create_time	String	Yes	Timestamp
sign	String	Yes	Signature

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"
}

Param and Status Code Description

PARAM

Request header param description:

Param	Type	Required	Description	Remarks
token	String	Yes	token
language	String	No	Language tag	en: English, zh: Chinese, not passed or defaulted to "zh" illegally

Uniform Status Code Description

Return param:

Status Code	Description	Remarks
000000	Succeed
900001	Token is null!
900002	token authentication failed
999999	System internal error
129000	Frequent API call	API call frequency limit: 100 times max allowed within 1 min, and 20,000 times max allowed within 1 day. Call frequency beyond the above limit will be limited. The limit start time per minute is the time (time window) of API initiating the first call, and the start time of call per day is 00:00 in GMT+8 time zone. The call times for the day will be reset after 00:00 in GMT+8 time zone
120001	Request body cannot be null
120002	Message body cannot be blank
120003	PartnerId cannot be blank
120004	Type cannot be blank
120005	source param error
120006	Type param error
120007	User status is not offline. Message sending is not allowed
120008	Card message body format or content error

Enterprise sends offline messages

● Send Offline Messages

Request method:

POST

Request URL:

 https://sg.sobot.io/chat-third/api/eis/message/send

Request param:

Param	Type	Required	Description	Remarks
partnerId	String	Yes	Docking ID
source	Integer	No	Channel	0:PC、4:WAP、2:APP。Default:2
message	Object	No	Message Content	Refer to message object below

message Object:

Param	Type	Required	Description	Remarks
type	String	Yes	Message Type	0: Text, 1: Image, 4: File, 50: Rich text, 521: Card
content	String	Yes	Message Content	When type is 521 (card) message, convert into the corresponding jsonString with reference to card entity input param. Pass String type in other circumstances
fileName	String	No	File Name	When type is 4 (file) message, if it is blank, the system will display system default file name

When type is 521 card message, pass content char json object in the following format. You can also refer to more complete examples of cards

 https://codecenter.sobot.io/pages/246fbc/#v6-%E6%96%B0%E7%89%88%E5%95%86%E5%93%81%E3%80%81%E8%AE%A2%E5%8D%95%E5%8D%A1%E7%89%87

Universal Card Field

content Object： Embed custom small cards into the universal card field by defining the universal card structure.

Param	Type	Required	Description	Remarks
cardStyle	Number	Card style: Flat: 0 List: 1 Default to 1	No
cardType	Number	Card type: Order: 0 Product: 1 Default to 1	No
cardGuide	String	Card Guidance Text	No	Only support displaying below list style
cardImg	String	Card Image	No	Only support displaying below list style
cardDesc	String	Card Description	No	Only support displaying below list style
cardLink	String	Card Hyperlink	No	Only support displaying below list style
customField	Object	Custom Field	No	Only support displaying below list style；Support 10 custom fields max.
customCards	Array	Custom Card List See the custom card field below for detailed params	No	Support 10 cards max. Due to different browser restrictions on URL length, the specific settings are based on the browser used by the user
cardMenus	Array	Custom Button List See the custom button field below for detailed params	No	Universal Card Only support displaying below list style Support 3 buttons max
cardTrigger	Number	Card sending link: Bot stage: 0 Agent: 1 Bot and agent: 2 Default to 1	No
cardOldPrompt	String	If the customer has not upgraded to the latest SDK version, the card will not be displayed properly. The default prompt text is: Your APP version needs to be upgraded to view this message. Please upgrade to the latest version of the APP.	No

Custom Card Field

customCards Object: Custom cards can be embedded in universal cards to display specific order and product information.

Param	Type	Required	Description	Remarks
customCardId	String	Card ID	No
customCardStatus	String	Card Status	No	Only support order cards
customCardCount	String	Card Quantity	No	Only support order cards
customCardCode	String	Card Code	No	Only support order cards
customCardTime	String	Card creation Time	No	Only support order cards
customCardName	String	Card Title	Yes
customCardThumbnail	String	Card Thumbnail	Yes
customCardAmount	String	Card Amount	No
customCardAmountSymbol	String	Card Amount Unit	No
customCardLink	String	Card Hyperlink	No
customCardDesc	String	Card Description	No
customMenus	Array	Custom Button See the custom button field below for detailed params	No

Button Field

cardMenus And customMenus Object: Define button names and types on universal and custom cards

Param	Type	Required	Description	Remarks
menuType	Number	Button type: Jump button: 0 OK button: 1 Send button: 2 Default to 2	Yes
menuName	String	Button Name	Yes
menuLink	String	Button Jump Hyperlink	No	Only support jump button type
menuLinkType	Number	Jump button support scenarios: Agent and visitor display: 0 Agent workbench and console display: 1 Only visitor display: 2	No	Only support jump button type
menuTip	String	Button prompt message	No	Only support acknowledge button type

Request example:

1. Send plain text messages

curl --location 'https://sg.sobot.io/chat-third/api/eis/message/send' \
--header 'token: e6809a1178524b78ac11b55ad8c7f4e5' \
--header 'language: en' \
--header 'Content-Type: application/json' \
--data '{
    "partnerId": "partnerId01",
    "source": 0,
    "message": {
        "content": "Test Text Message",
        "type": "0"
    }
}'

2. Send image messages

curl --location 'https://sg.sobot.io/chat-third/api/eis/message/send' \
--header 'token: e6809a1178524b78ac11b55ad8c7f4e5' \
--header 'language: en' \
--header 'Content-Type: application/json' \
--data '{
    "partnerId": "partnerId01",
    "source": 0,
    "message": {
        "content": "https://sobot-test.oss-cn.aliyuncs.com/chatres/443af7afa23f4c87a8900f178137d09c/msg/20231019/451fb18966e64a73acbfdb989ffe51d2/cbe32bd7a5804a6588b95daa0ca352df.jpg",
        "type": "1"
    }
}'

3. Send file messages

curl --location 'https://sg.sobot.io/chat-third/api/eis/message/send' \
--header 'token: e6809a1178524b78ac11b55ad8c7f4e5' \
--header 'language: en' \
--header 'Content-Type: application/json' \
--data '{
    "partnerId": "partnerId01",
    "source": 0,
    "message": {
        "content": "https://sobot-test.oss-cn.aliyuncs.com/chatres/443af7afa23f4c87a8900f178137d09c/msg/20231019/451fb18966e64a73acbfdb989ffe51d2/920c2c7182f34aada46ddef4beeeec86.txt",
        "type": "4",
        "fileName": "hello.txt"
    }
}'

4. Send rich text messages

curl --location 'https://sg.sobot.io/chat-third/api/eis/message/send' \
--header 'token: e6809a1178524b78ac11b55ad8c7f4e5' \
--header 'language: en' \
--header 'Content-Type: application/json' \
--data '{
    "partnerId": "partnerId01",
    "source": 0,
    "message": {
        "content": "<p1>hello!!</p1>",
        "type": "50"
    }
}'

5. Send card messages

curl --location 'https://sg.sobot.io/chat-third/api/eis/message/send' \
--header 'token: e6809a1178524b78ac11b55ad8c7f4e5' \
--header 'language: en' \
--header 'Content-Type: application/json' \
--data '{
    "partnerId": "partnerId01",
    "source": 0,
    "message": {
        "content": "{\"cardGuide\":\"please check\",\"cardLink\":\"https://sg.sobot.io\",\"cardMenus\":[{\"menuLink\":\"https://sg.sobot.io\",\"menuLinkType\":\"2\",\"menuName\":\"details\",\"menuType\":\"0\"},{\"menuName\":\"ticket\",\"menuTip\":\"check ok\",\"menuType\":\"1\"},{\"menuName\":\"send\",\"menuType\":\"2\"}],\"cardStyle\":\"1\",\"cardType\":\"0\",\"customCards\":[{\"customCardAmount\":\"7699.00\",\"customCardAmountSymbol\":\"¥\",\"customCardCode\":\"DD2023081038299\",\"customCardCount\":\"1\",\"customCardDesc\":\"good\",\"customCardId\":\"10611111\",\"customCardLink\":\"https://sg.sobot.io\",\"customCardName\":\"Apple iPhone 14 Pro 256GB \",\"customCardStatus\":\"checking\",\"customCardThumbnail\":\"https://img.sobot.io/chatres/137647808eba49b8ab81b4cf0b8e8c9d/msg/20230629/bb8f52abcde9fb64eae76fe546600be6/3eaed97a216349048bea79e4c8db81e9.png\",\"customCardTime\":\"\",\"customMenus\":[{\"menuName\":\"send\",\"menuType\":\"2\"},{\"menuLink\":\"https://sg.sobot.io\",\"menuLinkType\":\"2\",\"menuName\":\"details\",\"menuType\":\"0\"},{\"menuName\":\"check\",\"menuTip\":\"check ok\",\"menuType\":\"1\"}]}]}",
        "type": "521"
    }
}'

Return param:

Param	Type	Required	Description
ret_code	String	Yes	Return code
ret_msg	String	Yes	Return message

Return example:

{
  "ret_code": "000000",
  "ret_msg": "Succeed"
}