WhatsApp API
# WhatsApp API
# API Declaration
The "token" param must be contained in the header of the https request when calling the API.
Token is the onlysg 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 seconds. 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 | 10-digit timestamp |
sign | String | Yes | Signature md5(appid+create_time+app_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 (unit: s) |
Timestamp conversion tool:
http:// tool.chinaz.com/Tools/unixtime.aspx
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"
}
2
3
4
5
6
7
8
# ● Get Phone No. Code via Phone No.
Request method:
GET
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/getPhoneNumberId
Request param:
Param | Type | Required | Description |
---|---|---|---|
phone | String | Yes | Concatenate the region of the current phone no. before the phone no., such as 86184xxxx3511 |
curl https://sg.sobot.io/chat-whatsapp/whatsapp/getPhoneNumberId?phone=86184xxxx3511
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
2
Return example:
{
"item": {
"phone": " 86184 xxxx 3511 ",
"phoneNumberId": "1234567890",
"wabaId": " 1234567890 "
},
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
6
7
8
9
10
Return param:
Param | Type | Required | Description |
---|---|---|---|
ret_code | String | Yes | Return code |
ret_msg | String | Yes | Return message |
items | Object | No | Return object |
items object:
Param | Type | Description |
---|---|---|
phone | String | Phone No. |
phoneNumberId | String | Phone no. code |
wabaId | String | The unique ID of WhatsApp business account |
# Outbound Message
# ● Send text message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | text (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
text | String | Yes | Content |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"text": "this is text"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "text"
} '
2
3
4
5
6
7
8
9
10
11
12
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send image message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | image (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
mediaUrl | String | Yes | Resource link |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "image"
} '
2
3
4
5
6
7
8
9
10
11
12
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send file message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | document (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
mediaUrl | String | Yes | Resource link |
filename | String | No | File name |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png",
"filename": "example.txt"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "document"
} '
2
3
4
5
6
7
8
9
10
11
12
13
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send video message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | video (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
mediaUrl | String | Yes | Resource link |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "video"
} '
2
3
4
5
6
7
8
9
10
11
12
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send audio message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | audio (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
mediaUrl | String | Yes | Resource link |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "audio"
} '
2
3
4
5
6
7
8
9
10
11
12
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send sticker message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | sticker (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
mediaUrl | String | Yes | Resource link |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "sticker"
} '
2
3
4
5
6
7
8
9
10
11
12
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send location message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | location (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
latitude | String | Yes | Latitude |
longitude | String | Yes | Longitude |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"latitude": "LAT_NUMBER",
"longitude": "LONG_NUMBER"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "location"
} '
2
3
4
5
6
7
8
9
10
11
12
13
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send contact message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | contacts (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
contacts | List | Yes | Contacts |
contacts param:
Param | Type | Required | Description |
---|---|---|---|
name | Object | Yes | Contact name |
phones | List | No | Contact phone no. |
name param:
Param | Type | Required | Description |
---|---|---|---|
formatted_name | String | Yes | Full name displayed |
first_name | String | No | Name |
phones param:
Param | Type | Required | Description |
---|---|---|---|
phone | String | No | Phone no. |
type | String | No | CELL, MAIN, IPHONE, HOME and WORK are optional |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"contacts": [{
"name": {
"formatted_name": "NAME",
"first_name": "NAME"
},
"phones": [{
"phone": "PHONE_NUMBER",
"type": "CELL"
}]
}]
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "contacts"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send button message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | button (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
button | Object | Yes | Button content |
button param:
Param | Type | Required | Description |
---|---|---|---|
payload | String | Yes | Payload |
text | String | Yes | Content |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d ' {
"content": {
"button": {
"payload": "No-Button-Payload",
"text": "No"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "button"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send order message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | order (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
order | Object | Yes | Order content |
order param:
Param | Type | Required | Description |
---|---|---|---|
catalog_id | String | Yes | The unique identifier of the Facebook Catalog associated with your WhatsApp enterprise account |
text | String | Yes | Order content |
product_items | List | No | Multi-product list is required to pass |
product_items param:
Param | Type | Required | Description |
---|---|---|---|
quantity | String | Yes | Quantity |
product_ret ailer_id | String | Yes | Product's unique identifier in the catalog |
item_price | String | Yes | Price |
currency | String | Yes | Currency |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"order": {
"catalog_id": "the-catalog_id",
"text": "text-message-sent-along-with-the-order",
"product_items": [{
"quantity": "number-of-item",
"product_retailer_id": "the-product-SKU-identifier",
"item_price": "unitary-price-of-item",
"currency": "price-currency"
}]
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "order"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send interactive message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | interactive (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
interactive | Object | Yes | Interactive message content |
interactive param:
Param | Type | Required | Description |
---|---|---|---|
type | String | Yes | Button type, supported values: button: used for reply button list: used for list message product: used for single product message product_ List: used for multi-product messages |
button_reply | Object | Yes | Order content |
button_reply param:
Param | Type | Required | Description |
---|---|---|---|
id | String | Yes | Button ID |
title | String | Yes | Button title |
Request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "unique-button-identifier-here",
"title": "button-text"
}
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "interactive"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# ● Send template message
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/whatsapp/forword
Request param:
Param | Type | Required | Description |
---|---|---|---|
from | String | Yes | Sender |
to | String | Yes | Receiver |
type | String | Yes | template (fixed value) |
content | Object | Yes | Message Content |
content param:
Param | Type | Required | Description |
---|---|---|---|
template | Object | Yes | Template content |
template param:
Param | Type | Required | Description |
---|---|---|---|
name | String | Yes | Template name |
language | Object | Yes | Template Language |
components | List | Yes | Template creation variable |
language param:
Param | Type | Required | Description |
---|---|---|---|
code | String | Yes | Template language code |
components param:
Note:
If no variable is created in the WhatsApp backend, components is a null array
If there is a variable, the variable content cannot be null or null string
Request example: header variable is text
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"template": {
"components": [{
"type": "header",
"parameters": [{
"text": "CONTENT",
"type": "text"
}]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE_NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Request example: header variable is material
image | video | document (the filename parameter can be passed, peer level as link)
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"template": {
"components": [{
"type": "header",
"parameters": [{
"image": {
"link": "https:// img.sobot.io/console/common/face/robot.png"
},
"type": "image"
}]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE_NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Request example: header variable is location
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802'
-d '{
"content": {
"template": {
"components": [{
"type": "header",
"parameters": [{
"location": {
"address": "your address",
"latitude": "-12.283171",
"name": "your location name",
"longitude": "130.501951"
},
"type": "LOCATION"
}]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Request example: newer Authentication templates
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802'
-d '{
"content": {
"template": {
"components": [{
"type": "body",
"parameters": [{
"type": "text",
"text": "<ONE-TIME PASSWORD>"
}]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [{
"type": "text",
"text": "<ONE-TIME PASSWORD>"
}]
}
],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
Request example: body variable
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"template": {
"components": [{
"type": "body",
"parameters": [
{
"text": " CONTENT1 ",
"type": "text"
},
{
"text": " CONTENT2 ",
"type": "text"
}
]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE NAME"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Request example: button variable
If the current button variable is the first in the template, index=0, the second, index=1
If the current button variable contains Chinese, it needs to encode the Chinese
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"template": {
"components": [{
"sub_type": "URL",
"index": 0,
"type": "button",
"parameters": [
{
"payload": "BUTTON CONTENT",
"type": "payload"
}
]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE_NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Complete request example:
curl https://sg.sobot.io/chat-whatsapp/whatsapp/forword
-X POST
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"content": {
"template": {
"components": [{
"type": "header",
"parameters": [
{
"document": {
"filename": "xxx.txt",
"link": "https:// example/xxx.txt"
},
"type": "document"
}
]
},
{
"type": "body",
"parameters": [
{
"text": "CONTENT",
"type": "text"
}
]
},
{
"sub_type": "URL",
"index": 0,
"type": "button",
"parameters": [
{
"payload": "BUTTON CONTENT",
"type": "payload"
}
]
}],
"language": {
"code": "TEMPLATE_LANGUAGE_CODE"
},
"name": "TEMPLATE_NAME"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "template"
}'
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
Return example:
{
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
# Inbound Message
Request URL:
webhook notification message return example, configured in the Sobot Admin Center backend
# ● Text message
Return example:
{
"content": {
"text": "this is text"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "text",
"name": "NAME"
}
2
3
4
5
6
7
8
9
# ● Image message
Return example:
{
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "image",
"name": "NAME"
}
2
3
4
5
6
7
8
9
# ● File message
Return example:
{
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png",
"filename": "example.txt"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "document",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
# ● Video message
Return example:
{
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "video",
"name": "NAME"
}
2
3
4
5
6
7
8
9
# ● Audio message
Return example:
{
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "audio",
"name": "NAME"
}
2
3
4
5
6
7
8
9
# ● Sticker message
Return example:
{
"content": {
"mediaUrl": "https:// img.sobot.io/console/common/face/robot.png"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "sticker",
"name": "NAME"
}
2
3
4
5
6
7
8
9
# ● Location message
Return example:
{
"content": {
"latitude": "LAT_NUMBER",
"longitude": "LONG_NUMBER"
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "location",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
# ● Contact message
Return example:
{
"content": {
"contacts": [
{
"name": {
"formatted_name": "NAME",
"first_name": "NAME"
},
"phones": [
{
"phone": "PHONE_NUMBER",
"wa_id": " 8617343038250 ",
"type": "CELL"
}
]
}
]
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "contacts",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# ● Button message
Return example:
{
"content": {
"button": {
"payload": "No-Button-Payload",
"text": "No"
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "button",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
11
12
# ● Order message
Return example:
{
"content": {
"order": {
"catalog_id": "the-catalog_id",
"text": "text-message-sent-along-with-the-order",
"product_items": [
{
"quantity": "number-of-item",
"product_retailer_id": "the-product-SKU-identifier",
"item_price": "unitary-price-of-item",
"currency": "price-currency"
}
]
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "order",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ● Interactive message
Return example:
{
"content": {
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "unique-button-identifier-here",
"title": "button-text"
}
}
},
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"type": "interactive",
"name": "NAME"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Message Status Notification
Request URL:
webhook notification message return example, configured in the Sobot Admin Center backend
# ● Message status notification
Status attribute | Status meaning |
---|---|
sent | Sent |
delivered | Delivered |
read | Read |
Return example:
{
"from": "FROM_PHONE_NUMBER_ID",
"to": "PHONE_NUMBER",
"timestamp": " 1667453467 ",
"type": "status",
"status": "sent",
"messageId": "wamid.HBgNEUCABEYEkNGNTZDRkNCDMUIwRUM4QTIwQgA="
}
2
3
4
5
6
7
8
# Bill
# ● Get bill details
Request method:
GET
Request URL:
https://sg.sobot.io/chat-whatsapp/cost/billDetailList
Request param:
Param | Type | Required | Description |
---|---|---|---|
month | String | Yes | Query month (yyyy-MM) |
queryType | String | Yes | Query chat type (user: indicate the user, business: indicate the enterprise) |
sender | String | No | Sender phone no. |
Request example:
curl https://sg.sobot.io/chat-whatsapp/cost/billDetailList?month=2022-10&queryType=user
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
2
Return example:
{
"items": [
{
"areaCode": "971",
"totalPrice": 0.1440,
"countryCode": "AE",
"countryName": "United Arab Emirates",
"conversation": 6
},
{
"areaCode": "880",
"totalPrice": 0.0274,
"countryCode": "BD",
"countryName": "Bangladesh",
"conversation": 1
}
],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Return param:
Param | Type | Required | Description |
---|---|---|---|
ret_code | String | Yes | Return code |
ret_msg | String | Yes | Return message |
items | Object | No | Return object |
items object:
Param | Type | Description |
---|---|---|
areaCode | String | Region code |
totalPrice | double | Billing amount |
countryCode | String | ISO code |
countryName | String | Region name |
conversation | int | No. of chats |
# Template Message Management
# ● Get message template
API description: Retrieve all templates in the current wabaId
Request method:
GET
Request URL:
https://sg.sobot.io/chat-whatsapp/template/templateList
Request param:
Param | Type | Required | Description |
---|---|---|---|
wabaId | String | Yes | The unique ID of WhatsApp business account |
Request example:
curl https://sg.sobot.io/chat-whatsapp/template/templateList?wabaId=12345
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
2
Return example:
{
"item": {
"data": [
{
"components": [
{
"format": "DOCUMENT",
"type": "HEADER",
"example": {
"header_handle": [
"https:// scontent.whatsapp.net/v/t61.29466-34/224083690_601486205046207_3953929358019518287_n.pdf?ccb=1-7&_nc_sid=57045b&_nc_ohc=ANcodTypUrsAX_c3ME8&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&oh=01_AdRen_9v352EcZ7FFjoA6bVf0fUODwqoIfRjDa1PE0Uicw&oe=63931F4C"
]
}
},
{
"text": "This is {{1}} content, and also have {{2}} params.",
"type": "BODY",
"example": {
"body_text": [
[
"rick",
" 2 "
]
]
}
},
{
"text": "Footer",
"type": "FOOTER"
},
{
"buttons": [
{
"phone_number": "+86184xxxx7413",
"text": "call me",
"type": "PHONE_NUMBER"
},
{
"text": "Access the chat page",
"type": "URL",
"url": "https// xxx.html?name=text&partnerid={{1}}",
"example": [
"https// xxx.html?name=text&partnerid=1234"
]
}
],
"type": "BUTTONS"
}
],
"name": "templates_test",
"language": "zh_CN",
"id": " 601486201712874 ",
"category": "TRANSACTIONAL",
"status": "APPROVED"
}
],
"namespace": "9eb0ceda_9fc9_42ad_ad5a_5dd9d905a15a"
},
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
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 | Description |
---|---|---|
namespace | String | Template namespace |
id | String | Template code |
name | String | Template name |
language | String | Template Language |
status | String | Template status |
category | String | Template Category |
components | List | Template content |
# ● Create message template
API description: Retrieve all templates in the current wabaId
Request method:
GET
Request URL:
https://sg.sobot.io/chat-whatsapp/template/createTemplateInfo
Request param:
Param | Type | Required | Description |
---|---|---|---|
wabaId | String | Yes | The unique ID of WhatsApp business account |
name | String | Yes | Template name |
category | String | Yes | Template category (options: TRANSACTIONAL, OTP, MARKETING) |
language | String | Yes | Template language code |
components | String | Yes | Template content |
For more template parameter information, you can view in WhatsApp Business API (opens new window)
For languages available for template, you can query in Available language-WhatsApp Business API (opens new window)
Request example:
curl https://sg.sobot.io/chat-whatsapp/template/createTemplateInfo
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
-d '{
"wabaId": " 123456789 ",
"name": "template_name",
"category": "OTP",
"language": "en_US",
"components": [
{
"type": "BODY",
"text": "hello word"
},
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"https:// example.media.file"
]
}
},
{
"type": "FOOTER",
"text": "your-footer-text"
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "your-phone-button-text",
"phone_number": "+1(650) 555-1111"
},
{
"type": "URL",
"text": "your-url-button-text",
"url": "https:// www.xxx.com/{{1}}",
"example": [
"https:// www.xxx.com/example"
]
}
]
}
]
}'
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
Return example:
{
"item": {
"id": " 431829025804988 "
},
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
6
7
8
# ● Delete message template
API description: If the message template of this name has multiple language versions, all language versions will be deleted.
Request method:
GET
Request URL:
https://sg.sobot.io/chat-whatsapp/template/deleteTemplate
Request param:
Param | Type | Required | Description |
---|---|---|---|
wabaId | String | Yes | The unique ID of WhatsApp business account |
templateName | String | Yes | Template name |
Request example:
curl https://sg.sobot.io/chat-whatsapp/template/deleteTemplate?wabaId=12345&templateName=test
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802 '
2
Return example:
{
"item": {
"success": true
},
"items": [],
"retCode": "000000",
"retMsg": "success"
}
2
3
4
5
6
7
8
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 | Description |
---|---|---|
success | boolean | true: Deleted |
# Upload media
Request method:
POST
Request URL:
https://sg.sobot.io/chat-whatsapp/api/whatsapp/media_upload
Request param:
Param | Type | Required | Description |
---|---|---|---|
phone_numberid | String | Yes | receive |
url | String | Yes | Media attachment path |
Return param:
Param | Type | Description |
---|---|---|
ret_code | String | Yes |
ret_msg | String | Yes |
item | Object | No |
item object:
Param | Type | Description |
---|---|---|
id | String | Yes |
Request example:
curl -H 'token: 4ac37cb2e9c740dba4b75a34d5358802' https://sg.sobot.io/chat-whatsapp/api/whatsapp/media_upload?phone_numberid=1102434620&url=https://sg.sobot.io/console/c72d7e67c0f64d38879/kb/file/d736d26d756e420eac7ef8a6fe4d934f.mp4
Return example:
{
"item": {
"id": "1011461420318338"
},
"ret_code": "000000",
"ret_msg": "成功"
}
2
3
4
5
6
7