Doorbell Calls

Last Updated on : 2024-11-18 11:33:14download

Solution overview

Doorbell calls can be implemented after the app is started, and a doorbell is bound with a home and stays online. The app listens for a message of 43 protocol over MQTT to receive a doorbell call. Then, the app continues with more doorbell operations based on messages of 308 protocol over MQTT. For example, answer, hang up, or reject the call. To help you easily integrate the doorbell services and minimize development costs, the IPC SDK encapsulates the doorbell services.

If a doorbell call is received, the IPC SDK notifies the app of the call with the help of the doorbell call listener. Then, backed by the IPC SDK, the app can continue with more doorbell operations. For example, answer, hang up, or reject the call.

After the app exits, MQTT connections are closed. In this case, push notifications can be enabled to notify users of doorbell calls. When users receive the push notification of a doorbell call, on the doorbell call page that appears, users can continue with more doorbell operations. For example, answer, hang up, or reject the call. However, in the case of push notifications, doorbell calls are not processed over MQTT. As a result, the IPC SDK is not involved in this type of doorbell call. Subsequent operations (for example, answer, hang up, or reject the call) will thus fail if the IPC SDK is integrated to process these operations.

To fix the problem, you can call the open methods of the IPC SDK, and manually add the push notifications of doorbell calls to the management scope of the IPC SDK. For more information, see Process other types of doorbell calls.

To implement video streaming during doorbell calls, the live video streaming API methods must also be integrated.

Additional solutions

Currently, the preceding solution is used for IPC video doorbells, whose type is ac_doorbell. However, this solution does not apply to all doorbell devices.

Take a low-power doorbell (whose type is doorbell) as an example. The app is notified of a doorbell call based on the message of 43 protocol over MQTT. But subsequent operations (for example, answer, hang up, or reject the call) are implemented based on data points (DPs). In light of this, you can register a doorbell call listener to listen for doorbell calls from a low-power doorbell. However, you need to call device control API methods that deal with DPs for subsequent doorbell operations. For example, answer, hang up, or reject the call.

For certain smart locks, all doorbell operations are processed with DPs. For example, initiate, receive, answer, hang up, and reject doorbell calls. The IPC SDK that encapsulates doorbell call services is inapplicable.

Integrate with push notifications

After the app exits, MQTT connections are closed. In this case, push notifications can be enabled to notify users of doorbell calls. To improve user experience, the push SDK is required. For more information, see Integrate with Push Notifications.

After a doorbell is pressed, the app receives a push notification. Users can tap the push notification and perform subsequent operations.

Manage doorbell call notifications

Prerequisites

The app process must be active.

Query the doorbell call management class

Example

 ITuyaIPCDoorBellManager doorBellInstance = TuyaIPCSdk.getDoorbell().getIPCDoorBellManagerInstance();

Doorbell call models

Doorbell calls are encapsulated by the model class TYDoorBellCallModel. This class is used to store information about doorbell calls and maintain the doorbell call status.

Each doorbell call is assigned a unique message ID indicated by messageId and corresponds to a model indicated by TYDoorBellCallModel.

Parameter	Description
type	The type of doorbell call. Valid values: doorbell ac_doorbell custom
devId	The device ID.
messageId	The unique identifier of a doorbell call notification.
time	The Unix timestamp when a doorbell call is triggered. Unit: seconds.
answeredBySelf	Indicates whether the doorbell call is answered by the device owner.
answeredByOther	Indicates whether the doorbell call is answered by other users.
canceled	Indicates whether the doorbell call is canceled.

Query doorbell call models

The doorbell call status is maintained by the model class TYDoorBellCallModel. To get the status of a doorbell call, use the class to return the target instance of TYDoorBellCallModel.

API description

TYDoorBellCallModel getCallModelByMessageId(String messageId);

Parameters

Parameter	Description
messageId	The unique identifier of a doorbell call notification.

Register a doorbell call listener

Registers a doorbell call listener and passes in a listener subclass.

Prerequisites

The app process must be active. If the app process is cleaned up, the listener is invalid.

API description

void addObserver(TuyaSmartDoorBellObserver observer);

Parameters

Parameter	Description
observer	The doorbell call listener.

TuyaSmartDoorBellObserver

The doorbell call listener involves the callbacks throughout the life cycle of doorbell calls. The following table describes these callbacks.

API name	Parameter list	Return value	Description
doorBellCallDidReceivedFromDevice	TYDoorBellCallModel, DeviceBean	void	The doorbell call event from the device is received.
doorBellCallDidHangUp	TYDoorBellCallModel	void	The doorbell call is hung up on the device.
doorBellCallDidAnsweredByOther	TYDoorBellCallModel	void	The doorbell call is answered by other users. The service layer determines whether to automatically cancel or hold the call. To reject the call, call the refuseDoorBellCall API method and end the call. To hold the call, the device owner can pick up and listen to the ongoing call that is being answered by another user but cannot talk through the call.
doorBellCallDidCanceled	TYDoorBellCallModel, boolean	void	The doorbell call is canceled. The parameter `isTimeOut` indicates whether the call is automatically canceled due to timeout or manually canceled on the device.
doorBellCallDidAnswered	TYDoorBellCallModel	void	The doorbell call is answered.
doorBellCallDidRefuse	TYDoorBellCallModel	void	The doorbell call is rejected.

Example

private TYDoorBellCallModel mCallModel;

private final TuyaSmartDoorBellObserver observer = new TuyaSmartDoorBellObserver() {
    @Override
    public void doorBellCallDidReceivedFromDevice(TYDoorBellCallModel callModel, DeviceBean deviceModel) {
        mCallModel = callModel;
    }

    @Override
    public void doorBellCallDidAnsweredByOther(TYDoorBellCallModel callModel) {
    }

    @Override
    public void doorBellCallDidCanceled(TYDoorBellCallModel callModel, boolean isTimeOut) {
    }

    @Override
    public void doorBellCallDidHangUp(TYDoorBellCallModel callModel) {
    }
};

When the doorbell call event doorBellCallDidReceivedFromDevice from the device is received, the object TYDoorBellCallModel or the doorbell call identifier messageId must be saved to be passed in to implement subsequent operations. For example, both parameters are required to answer, hang up, or reject calls.

Remove a doorbell call listener

Removes a doorbell call listener if it is not required.

API description

void removeObserver(TuyaSmartDoorBellObserver observer);

Example

The following code block shows the method to remove a specified listener:

if (doorBellInstance != null) {
    doorBellInstance.removeObserver(observer);
}

Ignore calls following ongoing call on same device

Specifies whether to ignore subsequent calls when a call is being answered on the same device.

API description

void setIgnoreWhenCalling(boolean ignoreWhenCalling);

Parameters

Parameter	Description
ignoreWhenCalling	`true`: automatically ignores subsequent calls when a call is being answered on the same device. `false`: does not ignore subsequent calls. Default value: `true`.

Set timeout value for doorbell calls

Sets a timeout value for doorbell calls. If a doorbell call is not processed within the specified period, the callback TuyaSmartDoorBellObserver#doorBellCallDidCanceled is executed to send a notification and end this call.

API description

void setDoorbellRingTimeOut(int doorbellRingTimeOut);

Parameters

Parameter	Description
doorbellRingTimeOut	The timeout value of doorbell calls. Unit: seconds. Default value: `25`.

Answer a doorbell call

Answers a doorbell call after it is received. The call might fail to be answered because it is being answered or canceled, or due to other reasons. In the case of failure to answer a call, the failure reason is returned as an error message. For more information, see Error codes.

API description

int answerDoorBellCall(String messageId);

Parameters

Parameter	Description
messageId	The unique identifier of a doorbell call notification.

Example

if (doorBellInstance != null && mCallModel != null) {
    doorBellInstance.answerDoorBellCall(mCallModel.getMessageId());
}

Reject a doorbell call

Rejects a doorbell call after it is received.

API description

void refuseDoorBellCall(String messageId);

Parameters

Parameter	Description
messageId	The unique identifier of a doorbell call notification.

Example

    if (doorBellInstance != null && mCallModel != null) {
        doorBellInstance.refuseDoorBellCall(mCallModel.getMessageId());
    }

Hang up a doorbell call

Hangs up a doorbell call after it is received. The call might fail to be hung up because it is not answered or due to other reasons. In the case of failure to hang up a call, the failure reason is returned as an error message. For more information, see Error codes.

API description

int hangupDoorBellCall(String messageId);

Parameters

Parameter	Description
messageId	The unique identifier of a doorbell call notification.

Example

if (doorBellInstance != null && mCallModel != null) {
    doorBellInstance.hangupDoorBellCall(mCallModel.getMessageId());
}

Process other types of doorbell calls

Processes doorbell calls that are received on the app by means such as push notifications, rather than MQTT. A doorbell call model is generated based on the parameters passed in to implement subsequent operations. For example, answer, hang up, or reject the doorbell call.

API description

void generateCallModel(String deviceId, String messageType, String msgId, long startTime);

Parameters

Parameter	Description
deviceId	The device ID.
messageType	The type of message.
msgId	The message ID
startTime	The time when a doorbell call is started.

Example

TuyaIPCSdk.getDoorbell().getIPCDoorBellManagerInstance().generateCallModel(deviceId, messageType, msgId, startTime);

Error codes

Error code	Description
0	The operation is successful without errors.
-1	Failed to process the call. Possible reason: The call event is ended. For example, it is hung up or rejected. The same reason described by Error code `-1006`.
-1001	A doorbell call is being answered by another user when the API method is called to answer the call.
-1002	A doorbell call is canceled on the device when the API method is called to answer the call.
-1003	A doorbell call timed out when the API method is called to answer the call.
-1004	A doorbell call has been answered when the API method is called to answer the call.
-1005	A doorbell call is not answered when the API method is called to hang up the call.
-1006	The device type such as `doorbell` is not supported.