APIs Related to Third-Party Voice Device Relationship Management

Third-party voice devices can be bound to the graffiti cloud house by binding. After binding, intelligent control of the devices under the house can be realized through voice open API.

API List

Request method	API	description
GET	/v1.0/osaas/voices/{voice_id}/room/binding	API for Obtaining Speaker-Room Binding Information.
GET	/v1.0/osaas/voice/brands	API for Obtaining the Voice Brand List.
GET	/v1.0/osaas/projects/{project_id}/room/voice/relations	API for Querying the Room Voice Device Relationship List.
POST	/v1.0/osaas/rooms/{room_id}/voice/relation	API for Adding the Room Voice Device Relationship.
PUT	/v1.0/osaas/rooms/{room_id}/voice/relations/{relation_id}	API for Modifying the Room Voice Device Relationship.
DELETE	/v1.0/osaas/rooms/{room_id}/voice/relations/{relation_id}	API for Deleting the Room Voice Device Relationship.
PUT	/v1.0/osaas/projects/{project_id}/third-party/voice/authorization	API for Setting Third-Party Voice Open Platform Authorization Credentials.
DELETE	/v1.0/osaas/projects/{project_id}/third-party/voice/authorization	API for Deleting Third-Party Voice Open Platform Authorization Credentials.

API for Obtaining Speaker-Room Binding Information

API Description

You can use this API to obtain the speaker-room binding information based on the unique ID of the speaker.

API Address

GET /v1.0/osaas/voices/{voice_id}/room/binding

Request Parameters

Parameter	Type	Position	Description	Mandatory
voice_id	String	URI	Unique ID of a speaker	Yes
code	String	URL	Unique code of a speaker brand, allocated upon entry of the speaker brand.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
room_no	String	Room number.
room_name	String	Room name.
project_name	String	Project name.

Request Example

GET {url}/v1.0/osaas/voices/******/room/binding?code=******

Success Response Example

{
  "success": true,
  "t": 1566053034624,
  "result": {
    "room_no": "1101",
    "room_name": "1101 Room",
    "project_name": "*** Hotel"
  }
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining the Voice Brand List

API Description

You can use this API to obtain the voice brand list.

API Address

GET /v1.0/osaas/voice/brands

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Array	List of Voice Brands.

Parameters in result

Parameter	Type	Description
brand_id	String	Unique ID of a brand.
brand_name	String	Brand name.

Request Example

GET {url}/v1.0/osaas/voice/brands

Success Response Example

{
  "success": true,
  "t": 1566053034624,
  "result": [
    {
      "brand_id": "33",
      "brand_name": "*** Voice"
    }
  ]
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying the Room Voice Device Relationship List

API Description

You can use this API to query room voice device relations list.

API Address

GET /v1.0/osaas/projects/{project_id}/room/voice/relations

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
page_no	Integer	URL	Page number.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
relations	Arrays	List of relations.

Parameters in relations

Parameter	Type	Description
relation_id	String	Unique ID of a relation.
brand_id	String	Unique ID of a brand.
room_id	String	Unique ID of a room.
voice_id	Integer	Unique ID of a voice device.
gmt_create	Long	Creation time, which is a 13-digit timestamp.
gmt_modified	Long	Modification time, which is a 13-digit timestamp.

Request Example

GET {url}/v1.0/osaas/projects/12338239650******/room/voice/relations

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 20,
    "relations": [
      {
        "relation_id": "1233965053******",
        "brand_id": "33",
        "room_id": "12156722******",
        "voice_id": "************",
        "gmt_create": 1559707046000,
        "gmt_modified": 1559707046000
      }
    ]
  },
  "success": true,
  "t": 1572936751228
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Adding the Room Voice Device Relationship

API Description

You can use this API to add room voice device relation.

API Address

POST /v1.0/osaas/rooms/{room_id}/voice/relation

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room	Yes
voice_id	String	BODY	Unique ID of a voice.	Yes
brand_id	String	BODY	Unique ID of a brand	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	String	Unique ID of a relation.

Request Example

POST {url}/v1.0/osaas/rooms/1233823962******/voice/relation

{
  "voice_id": "************",
  "brand_id": "33"
}

Success Response Example

{
  "success": true,
  "result": "11123823965053******",
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Modifying the Room Voice Device Relationship

API Description

You can use this API to modify room voice device relation.

API Address

PUT /v1.0/osaas/rooms/{room_id}/voice/relations/{relation_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes
relation_id	String	URI	Unique ID of a relation.	Yes
voice_id	String	BODY	Unique ID of a voice.	No
brand_id	String	BODY	Unique ID of a brand.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

PUT {url}/v1.0/osaas/rooms/123382396******/voice/relations/178******

{
  "voice_id": "************",
  "brand_id": "33"
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Deleting the Room Voice Device Relationship

API Description

You can use this API to delete room voice device relation.

API Address

DELETE /v1.0/osaas/rooms/{room_id}/voice/relations/{relation_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes
relation_id	String	URI	Unique ID of a relation.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

DELETE {url}/v1.0/osaas/rooms/123382396******/voice/relations/1782******

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Setting Third-Party Voice Open Platform Authorization Credentials

API Description

You can use this API to set third-party voice open platform authorization credentials.

API Description

PUT /v1.0/osaas/projects/{project_id}/third-party/voice/authorization

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
brand_id	String	BODY	Unique ID of a brand.	Yes
app_id	String	BODY	Unique ID of a app	Yes
app_secret	String	BODY	App secret.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

PUT {url}/v1.0/osaas/projects/123382396505******/dueros/voice /authorization

{
  "brand_id": "33",
  "app_id": "************",
  "app_secret": "************"
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Deleting Third-Party Voice Open Platform Authorization Credentials

API Description

You can use this API to delete third-party voice open platform authorization credentials.

API Address

DELETE /v1.0/osaas/projects/{project_id}/third-party/voice/authorization

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
brand_id	String	URL	Unique ID of a brand.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

DELETE {url}/v1.0/osaas/projects/123382396505******/third-party/voice/authorization?brand_id=33

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error