Doorbell Calls

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.

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

 IThingIPCDoorBellManager doorBellInstance = ThingIPCSdk.getDoorbell().getIPCDoorBellManagerInstance();

Doorbell call models

Doorbell calls are encapsulated by the model class ThingDoorBellCallModel. 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 ThingDoorBellCallModel.

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 ThingDoorBellCallModel. To get the status of a doorbell call, use the class to return the target instance of ThingDoorBellCallModel.

API description

ThingDoorBellCallModel 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(ThingSmartDoorBellObserver observer);

Parameters

Parameter	Description
observer	The doorbell call listener.

ThingSmartDoorBellObserver

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	ThingDoorBellCallModel, DeviceBean	void	The doorbell call event from the device is received.
doorBellCallDidHangUp	ThingDoorBellCallModel	void	The doorbell call is hung up on the device.
doorBellCallDidAnsweredByOther	ThingDoorBellCallModel	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	ThingDoorBellCallModel, 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	ThingDoorBellCallModel	void	The doorbell call is answered.
doorBellCallDidRefuse	ThingDoorBellCallModel	void	The doorbell call is rejected.

Example

private ThingDoorBellCallModel mCallModel;

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

    @Override
    public void doorBellCallDidAnsweredByOther(ThingDoorBellCallModel callModel) {
    }

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

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

When the doorbell call event doorBellCallDidReceivedFromDevice from the device is received, the object ThingDoorBellCallModel 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(ThingSmartDoorBellObserver 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 ThingSmartDoorBellObserver#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.
cid	NodeId of the sub device (for example: gateway sub device), nullable

Example

ThingIPCSdk.getDoorbell().getIPCDoorBellManagerInstance().generateCallModel(deviceId, messageType, msgId, startTime, String cid);

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 -2306 .
-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.