Wechaty Puppet Service OpenAPI Specification (1.5.2)

Download OpenAPI specification:Download

Wechaty: [email protected] URL: https://github.com/wechaty/openapi License: Apache-2.0

Wechaty is a Conversational RPA SDK for chatbot makers. With only 6 lines of code, you can create a bot on the most popular IMs like WeChat, Whatsapp, WeCom, Gitter, etc.

Wechaty Puppet Service is the RESTful API for Wechaty API, which is build on top of the Wechaty Puppet Abstraction and the gRPC proto definition.

Puppet

* Huan(202002): consider changing response to a stream in the future for better performance

Responses

Response samples

200
default

Content type

application/json

{"ids": ["string"
]
}

* Operate Sub-Collections https://cloud.google.com/apis/design/design_patterns#list_sub-collections

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_ContactSelfName

path Parameters

name

required

string

Responses

Response samples

200
default

Content type

application/json

{ }

*

Contact Self

Responses

Response samples

200
default

Content type

application/json

{"qrcode": "string"
}

Puppet_ContactSelfSignature

Request Body schema: application/json

signature

string

Responses

Request samples

Payload

Content type

application/json

{"signature": "string"
}

Response samples

200
default

Content type

application/json

{ }

Puppet_ContactCorporationRemark

path Parameters

contactId

required

string

Request Body schema: application/json

corporationRemarkStringValueDeprecated	string
corporationRemark	string

Responses

Request samples

Payload

Content type

application/json

{"corporationRemarkStringValueDeprecated": "string",
"corporationRemark": "string"
}

Response samples

200
default

Content type

application/json

{ }

Puppet_ContactDescription

path Parameters

contactId

required

string

Request Body schema: application/json

descriptionStringValueDeprecated	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"descriptionStringValueDeprecated": "string",
"description": "string"
}

Response samples

200
default

Content type

application/json

{ }

Puppet_ContactPhone

path Parameters

contactId

required

string

Request Body schema: application/json

phones

Array of strings

Responses

Request samples

Payload

Content type

application/json

{"phones": ["string"
]
}

Response samples

200
default

Content type

application/json

{"phones": ["string"
]
}

Puppet_TagContactList

path Parameters

contactId

required

string

query Parameters

contactIdStringValueDeprecated

string

@deprecated: Huan(202109): Wrapper types must not be used going forward. https://cloud.google.com/apis/design/design_patterns#optional_primitive_fields

Responses

Response samples

200
default

Content type

application/json

{"ids": ["string"
]
}

Puppet_TagContactRemove

path Parameters

contactId required	string
id required	string

Responses

Response samples

200
default

Content type

application/json

{ }

*

Tag

path Parameters

contactId required	string
id required	string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_ContactAlias

path Parameters

id

required

string

Request Body schema: application/json

aliasStringValueDeprecated	string (nullable)
alias	string

Responses

Request samples

Payload

Content type

application/json

{"aliasStringValueDeprecated": "string",
"alias": "string"
}

Response samples

200
default

Content type

application/json

{"aliasStringValueDeprecated": "string",
"alias": "string"
}

Puppet_ContactAvatar

path Parameters

id

required

string

query Parameters

fileboxStringValueDeprecated	string
fileBox	string

Responses

Response samples

200
default

Content type

application/json

{"fileboxStringValueDeprecated": "string",
"fileBox": "string"
}

Puppet_DirtyPayload2

path Parameters

id required	string
type required	stringPAYLOAD_TYPE_CONTACT Enum: "PAYLOAD_TYPE_UNSPECIFIED" "PAYLOAD_TYPE_MESSAGE" "PAYLOAD_TYPE_CONTACT" "PAYLOAD_TYPE_ROOM" "PAYLOAD_TYPE_ROOM_MEMBER" "PAYLOAD_TYPE_FRIENDSHIP"

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_MessageSendContact

path Parameters

conversationId

required

string

Request Body schema: application/json

contactId

string

Responses

Request samples

Payload

Content type

application/json

{"contactId": "string"
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_MessageForward2

path Parameters

conversationId required	string
messageId required	string

Responses

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_MessageSendLocation

path Parameters

conversationId

required

string

Request Body schema: application/json

object (puppetLocationPayload)

accuracy	number <float>
address	string
latitude	number <double>
longitude	number <double>
name	string

Responses

Request samples

Payload

Content type

application/json

{"location": {"accuracy": 0.1,
"address": "string",
"latitude": 0.1,
"longitude": 0.1,
"name": "string"
}
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

Puppet_MessageSendMiniProgram

path Parameters

conversationId

required

string

Request Body schema: application/json

miniProgramDeprecated	string (* Huan(202110): We should use payload instead of JSON.stringify string The compatible code will be removed after Dec 31, 2022)
	object (puppetMiniProgramPayload)

Responses

Request samples

Payload

Content type

application/json

{"miniProgramDeprecated": "string",
"miniProgram": {"appid": "string",
"description": "string",
"pagePath": "string",
"iconUrl": "string",
"shareId": "string",
"thumbUrl": "string",
"title": "string",
"username": "string",
"thumbKey": "string"
}
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_MessageSendText

path Parameters

conversationId

required

string

Request Body schema: application/json

text	string
mentionalIds	Array of strings (Huan(202011) FIXME: Issue #99 https://github.com/wechaty/grpc/issues/99)

Responses

Request samples

Payload

Content type

application/json

{"text": "string",
"mentionalIds": ["string"
]
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_MessageSendUrl

path Parameters

conversationId

required

string

Request Body schema: application/json

urlLinkDeprecated	string (* Huan(202110): We should use payload instead of JSON.stringify string The compatible code will be removed after Dec 31, 2022)
	object (puppetUrlLinkPayload)

Responses

Request samples

Payload

Content type

application/json

{"urlLinkDeprecated": "string",
"urlLink": {"description": "string",
"thumbnailUrl": "string",
"title": "string",
"url": "string"
}
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_Ding

Request Body schema: application/json

data

string

Responses

Request samples

Payload

Content type

application/json

{"data": "string"
}

Response samples

200
default

Content type

application/json

{ }

* File/Blob download & upload

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"result": {"chunk": "string"
},
"error": {"code": 0,
"message": "string",
"details": [{"@type": "string",
"property1": null,
"property2": null
}
]
}
}

*

Event - Server Stream

Responses

Response samples

200
default

Content type

application/json

{"result": {"type": "EVENT_TYPE_UNSPECIFIED",
"payload": "string"
},
"error": {"code": 0,
"message": "string",
"details": [{"@type": "string",
"property1": null,
"property2": null
}
]
}
}

Puppet_FriendshipAccept

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_FriendshipAdd

path Parameters

contactId

required

string

Request Body schema: application/json

hello	string
sourceRoomIdStringValueDeprecated	string
sourceContactIdStringValueDeprecated	string
	object (* "Referrer" and "Referral" refers to different things. "Referrer" is something or somebody who refers. "Referral" is the act of referring. - https://english.stackexchange.com/questions/33135/referrer-versus-referral-versus-referer)

Responses

Request samples

Payload

Content type

application/json

{"hello": "string",
"sourceRoomIdStringValueDeprecated": "string",
"sourceContactIdStringValueDeprecated": "string",
"referrer": {"contactId": "string",
"roomId": "string"
}
}

Response samples

200
default

Content type

application/json

{ }

Puppet_FriendshipSearchHandle

path Parameters

weixin

required

string

Huan(202203): in gRPC, we can freely rename the field name as long as the number keep consistent. so we can just rename weixin to handle here.

(Huan(20220329): use weixin for now, until we upgrade to v2.0 the [email protected] will use the latest v1.x automatically when running npm install which will causing a breaking change. @link https://github.com/wechaty/getting-started/issues/254

TODO: rename weixin to handle in v2.0.0

Responses

Response samples

200
default

Content type

application/json

{"contactIdStringValueDeprecated": "string",
"contactId": "string"
}

Puppet_FriendshipSearchPhone

path Parameters

phone

required

string

Responses

Response samples

200
default

Content type

application/json

{"contactIdStringValueDeprecated": "string",
"contactId": "string"
}

*

Friendship

path Parameters

id

required

string

query Parameters

payloadStringValueDeprecated	string Huan(202003): What's the reason we need belowing payload? We should remove it if possible.
payload	string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"contactId": "string",
"hello": "string",
"type": "FRIENDSHIP_TYPE_UNSPECIFIED",
"stranger": "string",
"ticket": "string",
"scene": "FRIENDSHIP_SCENE_TYPE_UNSPECIFIED"
}

Puppet_DirtyPayload5

path Parameters

id required	string
type required	stringPAYLOAD_TYPE_FRIENDSHIP Enum: "PAYLOAD_TYPE_UNSPECIFIED" "PAYLOAD_TYPE_MESSAGE" "PAYLOAD_TYPE_CONTACT" "PAYLOAD_TYPE_ROOM" "PAYLOAD_TYPE_ROOM_MEMBER" "PAYLOAD_TYPE_FRIENDSHIP"

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_Logout

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_MessagePayload

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"filename": "string",
"text": "string",
"timestampDeprecated": "string",
"type": "MESSAGE_TYPE_UNSPECIFIED",
"talkerId": "string",
"roomId": "string",
"listenerId": "string",
"mentionIds": ["string"
],
"receiveTime": "2019-08-24T14:15:22Z"
}

Puppet_MessageContact

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"id": "string"
}

Puppet_DirtyPayload

path Parameters

id required	string
type required	stringPAYLOAD_TYPE_MESSAGE Enum: "PAYLOAD_TYPE_UNSPECIFIED" "PAYLOAD_TYPE_MESSAGE" "PAYLOAD_TYPE_CONTACT" "PAYLOAD_TYPE_ROOM" "PAYLOAD_TYPE_ROOM_MEMBER" "PAYLOAD_TYPE_FRIENDSHIP"

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_MessageLocation

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"location": {"accuracy": 0.1,
"address": "string",
"latitude": 0.1,
"longitude": 0.1,
"name": "string"
}
}

Puppet_MessageMiniProgram

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"miniProgramDeprecated": "string",
"miniProgram": {"appid": "string",
"description": "string",
"pagePath": "string",
"iconUrl": "string",
"shareId": "string",
"thumbUrl": "string",
"title": "string",
"username": "string",
"thumbKey": "string"
}
}

Puppet_MessageRecall

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"success": true
}

Puppet_MessageUrl

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"urlLinkDeprecated": "string",
"urlLink": {"description": "string",
"thumbnailUrl": "string",
"title": "string",
"url": "string"
}
}

Puppet_MessageForward

path Parameters

messageId required	string
conversationId required	string

Responses

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

*

Room Invitation

path Parameters

id

required

string

query Parameters

payloadStringValueDeprecated	string Huan(202002): `payload` should be removed. The puppet server should take the responsibilities for storing the unaccepted friend-request payload. @deprecated: use payload instead. Huan(202109): Wrapper types must not be used going forward. https://cloud.google.com/apis/design/design_patterns#optional_primitive_fields
payload	string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"inviterId": "string",
"topic": "string",
"memberCount": 0,
"memberIds": ["string"
],
"timestampUint64Deprecated": "string",
"avatar": "string",
"invitation": "string",
"receiverId": "string",
"receiveTime": "2019-08-24T14:15:22Z"
}

Puppet_RoomInvitationAccept

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_RoomList

Responses

Response samples

200
default

Content type

application/json

{"ids": ["string"
]
}

Puppet_RoomCreate

Request Body schema: application/json

contactIds	Array of strings
topic	string

Responses

Request samples

Payload

Content type

application/json

{"contactIds": ["string"
],
"topic": "string"
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

*

Room

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"topic": "string",
"avatar": "string",
"ownerId": "string",
"adminIds": ["string"
],
"memberIds": ["string"
],
"handle": "string"
}

Puppet_RoomQuit

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_RoomAdd

path Parameters

id required	string
contactId required	string

query Parameters

inviteOnly

boolean

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_RoomAnnounce

path Parameters

id

required

string

query Parameters

textStringValueDeprecated	string
text	string

Responses

Response samples

200
default

Content type

application/json

{"textStringValueDeprecated": "string",
"text": "string"
}

Puppet_RoomAnnounce2

path Parameters

id

required

string

Request Body schema: application/json

textStringValueDeprecated	string
text	string

Responses

Request samples

Payload

Content type

application/json

{"textStringValueDeprecated": "string",
"text": "string"
}

Response samples

200
default

Content type

application/json

{"textStringValueDeprecated": "string",
"text": "string"
}

Puppet_RoomAvatar

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"fileBox": "string"
}

Puppet_DirtyPayload4

path Parameters

id required	string
type required	stringPAYLOAD_TYPE_ROOM_MEMBER Enum: "PAYLOAD_TYPE_UNSPECIFIED" "PAYLOAD_TYPE_MESSAGE" "PAYLOAD_TYPE_CONTACT" "PAYLOAD_TYPE_ROOM" "PAYLOAD_TYPE_ROOM_MEMBER" "PAYLOAD_TYPE_FRIENDSHIP"

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_DirtyPayload3

path Parameters

id required	string
type required	stringPAYLOAD_TYPE_ROOM Enum: "PAYLOAD_TYPE_UNSPECIFIED" "PAYLOAD_TYPE_MESSAGE" "PAYLOAD_TYPE_CONTACT" "PAYLOAD_TYPE_ROOM" "PAYLOAD_TYPE_ROOM_MEMBER" "PAYLOAD_TYPE_FRIENDSHIP"

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_RoomDel

path Parameters

id required	string
contactId required	string

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_RoomMemberList

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"memberIds": ["string"
]
}

*

Room Member

path Parameters

id required	string
memberId required	string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"roomAlias": "string",
"inviterId": "string",
"avatar": "string",
"name": "string"
}

Puppet_RoomQRCode

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"qrcode": "string"
}

Puppet_RoomTopic

path Parameters

id

required

string

query Parameters

topicStringValueDeprecated	string
topic	string

Responses

Response samples

200
default

Content type

application/json

{"topicStringValueDeprecated": "string",
"topic": "string"
}

*

Base

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_Stop

Responses

Response samples

200
default

Content type

application/json

{ }

Puppet_Upload

Request Body schema: application/json

(streaming inputs)

chunk

string <byte>

Responses

Request samples

Payload

Content type

application/json

{"chunk": "string"
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

Puppet_Version

Responses

Response samples

200
default

Content type

application/json

{"version": "string"
}

* Huan(202203): https://github.com/wechaty/puppet/issues/181 @deprecated use FriendshipSearchHandle instead, will be removed in v3.0

Request Body schema: application/json

weixin

string

Huan(202203): in gRPC, we can freely rename the field name as long as the number keep consistent. so we can just rename weixin to handle here.

(Huan(20220329): use weixin for now, until we upgrade to v2.0 the [email protected] will use the latest v1.x automatically when running npm install which will causing a breaking change. @link https://github.com/wechaty/getting-started/issues/254

TODO: rename weixin to handle in v2.0.0

Responses

Request samples

Payload

Content type

application/json

{"weixin": "string"
}

Response samples

200
default

Content type

application/json

{"contactIdStringValueDeprecated": "string",
"contactId": "string"
}

Puppet_MessageFile

Request Body schema: application/json

id

string

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Response samples

200
default

Content type

application/json

{"fileBox": "string"
}

* Deprecated: will be removed after Dec 31, 2022

Request Body schema: application/json

id

string

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Response samples

200
default

Content type

application/json

{"result": {"fileBoxChunk": {"data": "string",
"name": "string"
}
},
"error": {"code": 0,
"message": "string",
"details": [{"@type": "string",
"property1": null,
"property2": null
}
]
}
}

Puppet_MessageImage

Request Body schema: application/json

id	string
type	string (puppetImageType) Default: "IMAGE_TYPE_UNSPECIFIED" Enum: "IMAGE_TYPE_UNSPECIFIED" "IMAGE_TYPE_THUMBNAIL" "IMAGE_TYPE_HD" "IMAGE_TYPE_ARTWORK"

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"type": "IMAGE_TYPE_UNSPECIFIED"
}

Response samples

200
default

Content type

application/json

{"fileBox": "string"
}

Puppet_MessageImageStream

Request Body schema: application/json

id	string
type	string (puppetImageType) Default: "IMAGE_TYPE_UNSPECIFIED" Enum: "IMAGE_TYPE_UNSPECIFIED" "IMAGE_TYPE_THUMBNAIL" "IMAGE_TYPE_HD" "IMAGE_TYPE_ARTWORK"

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"type": "IMAGE_TYPE_UNSPECIFIED"
}

Response samples

200
default

Content type

application/json

{"result": {"fileBoxChunk": {"data": "string",
"name": "string"
}
},
"error": {"code": 0,
"message": "string",
"details": [{"@type": "string",
"property1": null,
"property2": null
}
]
}
}

Puppet_MessageSendFile

Request Body schema: application/json

conversationId	string
fileBox	string

Responses

Request samples

Payload

Content type

application/json

{"conversationId": "string",
"fileBox": "string"
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

Puppet_MessageSendFileStream

Request Body schema: application/json

(streaming inputs)

conversationId	string (oneof payload {)
	object (puppetFileBoxChunk)

Responses

Request samples

Payload

Content type

application/json

{"conversationId": "string",
"fileBoxChunk": {"data": "string",
"name": "string"
}
}

Response samples

200
default

Content type

application/json

{"idStringValueDeprecated": "string",
"id": "string"
}

contact

Get a contact payload

Contact

path Parameters

id

required

string

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"gender": "CONTACT_GENDER_UNSPECIFIED",
"type": "CONTACT_TYPE_UNSPECIFIED",
"name": "string",
"avatar": "string",
"address": "string",
"alias": "string",
"city": "string",
"friend": true,
"province": "string",
"signature": "string",
"star": true,
"weixin": "string",
"corporation": "string",
"title": "string",
"description": "string",
"coworker": true,
"phones": ["string"
]
}