Doorbell Call Service

Last Updated on : 2023-09-19 03:00:53download

A doorbell can be bound with a home and stay online on your app. In this case, if the doorbell is pressed, IPC SDK receives a doorbell call event. Doorbell call operations are implemented with the management class. For example, listen for changes on the doorbell call status, and answer, hang up or reject calls.

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

Query the doorbell call management class

Example

Objective-C:

ThingSmartDoorBellManager *manager = [ThingSmartDoorBellManager sharedInstance];

Swift:

let manager = ThingSmartDoorBellManager.sharedInstance()

Doorbell call models

Doorbell calls are encapsulated by the model class ThingSmartDoorBellCallModel. 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 matches a model indicated by ThingSmartDoorBellCallModel.

Parameter Description
type The type of doorbell call. Valid values:
  • doorbell
  • ac_doorbell
  • Custom type
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

To get the status of a doorbell call, use the model ThingSmartDoorBellCallModel to return the target instance of ThingSmartDoorBellCallModel.

API description

- (ThingSmartDoorBellCallModel *)callModelWithMessageId:(NSString *)messageId;

Parameters

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

Register a doorbell call listener

The app process must be active before the listener can be effective. If the app process runs in the background or is terminated, the listener becomes invalid.

API description

- (void)addObserver:(id<ThingSmartDoorBellObserver>)observer;

Parameters

Parameter Description
ThingSmartDoorBellObserver 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
didReceivedFromDevice ThingSmartDoorBellCallModel, ThingSmartDeviceModel void The doorbell call event from the device is received.
doorBellCallDidHangUp ThingSmartDoorBellCallModel void The doorbell call is hung up on the device.
doorBellCallDidAnsweredByOther ThingSmartDoorBellCallModel 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.
    doorBellCallDidAnswered ThingSmartDoorBellCallModel void The doorbell call is answered by other users.
    doorBellCallDidCanceled ThingSmartDoorBellCallModel, BOOL void The doorbell call is canceled. The doorbell call is canceled. The parameter isTimeOut indicates whether the call is automatically canceled due to timeout or manually canceled on the device.
    doorBellCallDidRefuse ThingSmartDoorBellCallModel void The doorbell call is rejected.

    When the doorbell call event didReceivedFromDevice from the device is received, we recommend that you save the object ThingSmartDoorBellCallModel or the doorbell call identifier messageId. Either will be required in the API request to answer, hang up, or reject calls.

    Example

    Objective-C:

    @interface CameraDoorbellManager ()<ThingSmartDoorBellObserver>
    @property (nonatomic, copy) NSString *messageId;
    @end
    
    @implementation CameraDoorbellManager
    
    - (void)doorBellCall:(ThingSmartDoorBellCallModel *)callModel didReceivedFromDevice:(ThingSmartDeviceModel *)deviceModel {
        self.messageId = callModel.messageId;
    }
    
    - (void)doorBellCallDidRefuse:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidHangUp:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidAnsweredByOther:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidAnswered:(ThingSmartDoorBellCallModel *)callModel {
    
    }
    
    - (void)doorBellCallDidCanceled:(ThingSmartDoorBellCallModel *)callModel timeOut:(BOOL)isTimeOut {
    
    }
    
    @end
    

    Swift:

    class DoorbellManager: NSObject {
        let manager = ThingSmartDoorBellManager.sharedInstance()
        var messageId:String = ""
    }
    
    extension DoorbellManager:ThingSmartDoorBellObserver {
        func doorBellCall(_ callModel: ThingSmartDoorBellCallModel!, didReceivedFromDevice deviceModel: ThingSmartDeviceModel!) {
            messageId = callModel.messageId
        }
    
        func doorBellCallDidRefuse(_ callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidHangUp(_ callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidAnswered(byOther callModel: ThingSmartDoorBellCallModel!) {
    
        }
    
        func doorBellCallDidCanceled(_ callModel: ThingSmartDoorBellCallModel!, timeOut isTimeOut: Bool) {
    
        }
    }
    

    Remove a doorbell call listener

    Removes a doorbell call listener if it is not required.

    API description

    - (void)removeObserver:(id<ThingSmartDoorBellObserver>)observer;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] removeObserver:self];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.remove(self)
    

    Ignore calls following an ongoing call on the same device

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

    Property description

    @property (nonatomic, assign) BOOL ignoreWhenCalling;
    
    Property Description
    ignoreWhenCalling
    • YES: automatically ignores subsequent calls when a call is being answered on the same device.
    • NO: does not ignore calls following an ongoing call on the same device.
    Default value: YES.

    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 doorBellCallDidCanceled is executed to send a notification and end this call.

    Property description

    @property (nonatomic, assign) NSInteger doorbellRingTimeOut;
    
    Property 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

    - (ThingDoorBellError)answerDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] answerDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.answerDoorBellCall(messageId)
    

    Reject a doorbell call

    Rejects a doorbell call after it is received.

    API description

    - (void)refuseDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] refuseDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.refuseDoorBellCall(messageId)
    

    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

    - (ThingDoorBellError)hangupDoorBellCall:(NSString *)messageId;
    

    Example

    Objective-C:

    [[ThingSmartDoorBellManager sharedInstance] hangupDoorBellCall:self.messageId];
    

    Swift:

    ThingSmartDoorBellManager.sharedInstance()?.hangupDoorBellCall(messageId)
    

    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)generateCall:(NSDictionary *)params;
    

    Parameters

    Parameter Description
    params The received doorbell call notification.

    Description of key-value pairs in params

    key value
    devId The device ID.
    cid The value of nodeId for the device.
    edata The message ID.
    eType The type of received doorbell call notification.
    time The timestamp of received doorbell call notification.

    Error codes

    For more information, see Error Codes.

    Enum value Error code Description
    ThingDoorBellError_NoError 0 The operation is successful without errors.
    ThingDoorBellError_CallFailed -2300 Failed to process the call. Possible reason:
    • The call event is ended. For example, it is hung up or rejected.
    • Same reason as that of ThingDoorBellError_NotSupport.
    ThingDoorBellError_AnsweredByOther -2301 A doorbell call is being answered by another user when the API method is called to answer the call.
    ThingDoorBellError_DidCanceled -2302 The doorbell call has been canceled on the device.
    ThingDoorBellError_TimeOut -2303 The doorbell call timed out.
    ThingDoorBellError_AnsweredBySelf -2304 The doorbell call has been answered.
    ThingDoorBellError_NotAnswered -2305 A doorbell call is not answered when the API method is called to hang up the call.
    ThingDoorBellError_NotSupport -2306 The device type such as doorbell is not supported.

    Doorbell audio resource file

    To implement the features of the low-power doorbell, you must download the default resource file resources.zip, decompress it, and then add the resources to your project. You can also add a custom audio file with the default file name.