Skip to main content

Wechaty Puppet Service OpenAPI Specification (1.5.2)

Download OpenAPI specification:Download

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

Content type
application/json
{
  • "ids": [
    ]
}

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

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

Puppet_ContactSelfName

path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{ }

*

Contact Self

Responses

Response samples

Content type
application/json
{
  • "qrcode": "string"
}

Puppet_ContactSelfSignature

Request Body schema: application/json
signature
string

Responses

Request samples

Content type
application/json
{
  • "signature": "string"
}

Response samples

Content type
application/json
{ }

Puppet_ContactCorporationRemark

path Parameters
contactId
required
string
Request Body schema: application/json
corporationRemarkStringValueDeprecated
string
corporationRemark
string

Responses

Request samples

Content type
application/json
{
  • "corporationRemarkStringValueDeprecated": "string",
  • "corporationRemark": "string"
}

Response samples

Content type
application/json
{ }

Puppet_ContactDescription

path Parameters
contactId
required
string
Request Body schema: application/json
descriptionStringValueDeprecated
string
description
string

Responses

Request samples

Content type
application/json
{
  • "descriptionStringValueDeprecated": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{ }

Puppet_ContactPhone

path Parameters
contactId
required
string
Request Body schema: application/json
phones
Array of strings

Responses

Request samples

Content type
application/json
{
  • "phones": [
    ]
}

Response samples

Content type
application/json
{
  • "phones": [
    ]
}

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

Content type
application/json
{
  • "ids": [
    ]
}

Puppet_TagContactRemove

path Parameters
contactId
required
string
id
required
string

Responses

Response samples

Content type
application/json
{ }

*

Tag

path Parameters
contactId
required
string
id
required
string

Responses

Response samples

Content type
application/json
{ }

Puppet_ContactAlias

path Parameters
id
required
string
Request Body schema: application/json
aliasStringValueDeprecated
string (nullable)
alias
string

Responses

Request samples

Content type
application/json
{
  • "aliasStringValueDeprecated": "string",
  • "alias": "string"
}

Response samples

Content type
application/json
{
  • "aliasStringValueDeprecated": "string",
  • "alias": "string"
}

Puppet_ContactAvatar

path Parameters
id
required
string
query Parameters
fileboxStringValueDeprecated
string
fileBox
string

Responses

Response samples

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

Content type
application/json
{ }

Puppet_MessageSendContact

path Parameters
conversationId
required
string
Request Body schema: application/json
contactId
string

Responses

Request samples

Content type
application/json
{
  • "contactId": "string"
}

Response samples

Content type
application/json
{
  • "idStringValueDeprecated": "string",
  • "id": "string"
}

Puppet_MessageForward2

path Parameters
conversationId
required
string
messageId
required
string

Responses

Response samples

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

Content type
application/json
{
  • "location": {
    }
}

Response samples

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

Content type
application/json
{
  • "miniProgramDeprecated": "string",
  • "miniProgram": {
    }
}

Response samples

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

Content type
application/json
{
  • "text": "string",
  • "mentionalIds": [
    ]
}

Response samples

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

Content type
application/json
{
  • "urlLinkDeprecated": "string",
  • "urlLink": {
    }
}

Response samples

Content type
application/json
{
  • "idStringValueDeprecated": "string",
  • "id": "string"
}

Puppet_Ding

Request Body schema: application/json
data
string

Responses

Request samples

Content type
application/json
{
  • "data": "string"
}

Response samples

Content type
application/json
{ }

* File/Blob download & upload

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

*

Event - Server Stream

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

Puppet_FriendshipAccept

path Parameters
id
required
string

Responses

Response samples

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

Content type
application/json
{
  • "hello": "string",
  • "sourceRoomIdStringValueDeprecated": "string",
  • "sourceContactIdStringValueDeprecated": "string",
  • "referrer": {
    }
}

Response samples

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 wechaty-grpc@1.0.0 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

Content type
application/json
{
  • "contactIdStringValueDeprecated": "string",
  • "contactId": "string"
}

Puppet_FriendshipSearchPhone

path Parameters
phone
required
string

Responses

Response samples

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

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

Content type
application/json
{ }

Puppet_Logout

Responses

Response samples

Content type
application/json
{ }

Puppet_MessagePayload

path Parameters
id
required
string

Responses

Response samples

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

Puppet_MessageContact

path Parameters
id
required
string

Responses

Response samples

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

Content type
application/json
{ }

Puppet_MessageLocation

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "location": {
    }
}

Puppet_MessageMiniProgram

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "miniProgramDeprecated": "string",
  • "miniProgram": {
    }
}

Puppet_MessageRecall

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Puppet_MessageUrl

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "urlLinkDeprecated": "string",
  • "urlLink": {
    }
}

Puppet_MessageForward

path Parameters
messageId
required
string
conversationId
required
string

Responses

Response samples

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

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

Puppet_RoomInvitationAccept

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

Puppet_RoomList

Responses

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Puppet_RoomCreate

Request Body schema: application/json
contactIds
Array of strings
topic
string

Responses

Request samples

Content type
application/json
{
  • "contactIds": [
    ],
  • "topic": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

*

Room

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "topic": "string",
  • "avatar": "string",
  • "ownerId": "string",
  • "adminIds": [
    ],
  • "memberIds": [
    ],
  • "handle": "string"
}

Puppet_RoomQuit

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{ }

Puppet_RoomAdd

path Parameters
id
required
string
contactId
required
string
query Parameters
inviteOnly
boolean

Responses

Response samples

Content type
application/json
{ }

Puppet_RoomAnnounce

path Parameters
id
required
string
query Parameters
textStringValueDeprecated
string
text
string

Responses

Response samples

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

Content type
application/json
{
  • "textStringValueDeprecated": "string",
  • "text": "string"
}

Response samples

Content type
application/json
{
  • "textStringValueDeprecated": "string",
  • "text": "string"
}

Puppet_RoomAvatar

path Parameters
id
required
string

Responses

Response samples

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

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

Content type
application/json
{ }

Puppet_RoomDel

path Parameters
id
required
string
contactId
required
string

Responses

Response samples

Content type
application/json
{ }

Puppet_RoomMemberList

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "memberIds": [
    ]
}

*

Room Member

path Parameters
id
required
string
memberId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "roomAlias": "string",
  • "inviterId": "string",
  • "avatar": "string",
  • "name": "string"
}

Puppet_RoomQRCode

path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "qrcode": "string"
}

Puppet_RoomTopic

path Parameters
id
required
string
query Parameters
topicStringValueDeprecated
string
topic
string

Responses

Response samples

Content type
application/json
{
  • "topicStringValueDeprecated": "string",
  • "topic": "string"
}

*

Base

Responses

Response samples

Content type
application/json
{ }

Puppet_Stop

Responses

Response samples

Content type
application/json
{ }

Puppet_Upload

Request Body schema: application/json

(streaming inputs)

chunk
string <byte>

Responses

Request samples

Content type
application/json
{
  • "chunk": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Puppet_Version

Responses

Response samples

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 wechaty-grpc@1.0.0 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

Content type
application/json
{
  • "weixin": "string"
}

Response samples

Content type
application/json
{
  • "contactIdStringValueDeprecated": "string",
  • "contactId": "string"
}

Puppet_MessageFile

Request Body schema: application/json
id
string

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "fileBox": "string"
}

* Deprecated: will be removed after Dec 31, 2022

Request Body schema: application/json
id
string

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

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

Content type
application/json
{
  • "id": "string",
  • "type": "IMAGE_TYPE_UNSPECIFIED"
}

Response samples

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

Content type
application/json
{
  • "id": "string",
  • "type": "IMAGE_TYPE_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

Puppet_MessageSendFile

Request Body schema: application/json
conversationId
string
fileBox
string

Responses

Request samples

Content type
application/json
{
  • "conversationId": "string",
  • "fileBox": "string"
}

Response samples

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

Content type
application/json
{
  • "conversationId": "string",
  • "fileBoxChunk": {
    }
}

Response samples

Content type
application/json
{
  • "idStringValueDeprecated": "string",
  • "id": "string"
}

contact

Get a contact payload

Contact

path Parameters
id
required
string

Responses

Response samples

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": [
    ]
}