Call Logs

Guide to fetching and filtering call history using the CometChat iOS SDK CallLogsRequest builder.

Quick Reference for AI Agents & Developers

• Build request: CometChatCallsSDK.CallLogsRequest.CallLogsBuilder().set(limit:).build()
• Fetch logs: callLogsRequest.fetchNext(onSuccess:onError:)
• Filters: .set(callType:), .set(callStatus:), .set(hasRecording:), .set(callDirection:)
• Call details: CometChat.getCallDetails(sessionID:onSuccess:onError:)
• Related: Ringing · Call Session · Calling Overview

Overview

CometChat’s iOS Call SDK provides a comprehensive way to integrate call logs into your application, enhancing your user experience by allowing users to effortlessly keep track of their communication history. Call logs provide crucial information such as call duration, participants, and more.

This feature not only allows users to review their past interactions but it also serves as an effective tool to revisit important conversation details. With the flexibility of fetching call logs, filtering them according to specific parameters, and obtaining detailed information of individual calls, application developers can use this feature to build a more robust and interactive communication framework.

In the following sections, we will guide you through the process of working with call logs, offering a deeper insight into how to optimally use this feature in your iOS application.

Fetching Call Logs

To fetch all call logs in your iOS application, you should use the CallLogRequestBuilder, This builder allows you to customize the call logs fetching process according to your needs.

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callCategory: .call)
    .build()

Sample Payload - CallLogsRequest.CallLogsBuilder()

Builder Configuration:

Parameter	Type	Description
authToken	String	Logged-in user’s authentication token. Example: "cometchat-uid-2_177010263828e3f97e747c568b2e22e600141afe"
limit	Int	Number of call logs to fetch per request. Example: 30
callCategory	CallCategory	Category filter for calls. Example: .call

Built CallLogsRequest Object:

Parameter	Type	Description
authToken	String	Authentication token for API requests
limit	Int	Maximum results per page. Example: 30
callCategory	CallCategory	Filter category. Example: .call
cursor	String?	Pagination cursor. Example: nil (initial request)

CallLogRequestBuilder has the following settings available.

Setting	Description
set(limit: Int)	Specifies the number of call logs to fetch.
set(callType: CallType)	Sets the type of calls to fetch (call or meet).
set(callStatus: CallStatus)	Sets the status of calls to fetch (initiated, ongoing, etc.)
setg(hasRecording: HasRecording)	Sets whether to fetch calls that have recordings.
set(callCategory: CallCategory)	Sets the category of calls to fetch (call or meet).
set(callDirection: CallDirection)	Sets the direction of calls to fetch (incoming or outgoing)
set(uid: String)	Sets the UID of the user whose call logs to fetch.
set(guid: String)	Sets the GUID of the user whose call logs to fetch.
set(authToken: String)	Sets the Auth token of the logged-in user.

Sample Payload - Builder Methods Reference

CallLogsBuilder Methods:

Method	Type	Description
set(limit: Int)	Int	Number of logs to fetch per request. Example: 30
set(callType: CallType)	CallType	Filter by call type. Example: .audio or .video
set(callStatus: CallStatus)	CallStatus	Filter by call status. Example: .initiated, .ongoing, .ended
set(hasRecording: Bool)	Bool	Filter by recording availability. Example: true
set(callCategory: CallCategory)	CallCategory	Filter by category. Example: .call or .meet
set(callDirection: CallDirection)	CallDirection	Filter by direction. Example: .incoming or .outgoing
set(uid: String)	String	Filter by user UID. Example: "cometchat-uid-2"
set(guid: String)	String	Filter by group GUID. Example: "cometchat-guid-1"
set(authToken: String)	String	Logged-in user’s auth token. Example: "cometchat-uid-2_177010263828e3..."

CallType Enum Values:

Value	Description
.audio	Audio-only call
.video	Video call

CallStatus Enum Values:

Value	Description
.initiated	Call has been initiated
.ongoing	Call is currently in progress
.unanswered	Call was not answered
.rejected	Call was rejected by receiver
.busy	Receiver was busy
.cancelled	Call was cancelled by initiator
.ended	Call has ended normally

CallCategory Enum Values:

Value	Description
.call	Regular one-to-one or group call
.meet	Scheduled meeting

CallDirection Enum Values:

Value	Description
.incoming	Incoming call to the user
.outgoing	Outgoing call from the user

Fetch Next

The**fetchNext()**method retrieves the next set of call logs.

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callCategory: .call)
    .build()

callLogRequest.fetchNext() { [weak self] callLogs in
        print("fetchNext success")
    } onError: { [weak self] error in
        print("fetchNext failed with error; \(error.errorDescription)")
}

Sample Payload - fetchNext() Request

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls
Method	GET

Query Parameters:

Parameter	Type	Description
mode	String	Call category filter. Example: "call"
page	Int	Page number for pagination. Example: 1
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token. Example: "cometchat-uid-2_177010263828e3f97e747c568b2e22e600141afe"
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Sample Payload - fetchNext() Response

Success Callback Parameter:

Parameter	Type	Description
callLogs	[CallLog]	Array of CallLog objects. See CallLog Object below

CallLog Object:

Parameter	Type	Description
sessionId	String	Unique call session identifier. Example: "v1.us.12345678901234567890"
initiator	Initiator	User who initiated the call. See Initiator Object below
receiver	Receiver	User/Group who received the call. See Receiver Object below
callType	String	Type of call. Example: "video" or "audio"
callStatus	String	Final status of call. Example: "ended"
callDirection	String	Direction relative to logged-in user. Example: "outgoing"
startedAt	Int	Unix timestamp when call started. Example: 1699900000
endedAt	Int	Unix timestamp when call ended. Example: 1699900300
duration	Int	Call duration in seconds. Example: 300
hasRecording	Bool	Whether call has recording. Example: true
recordings	[Recording]?	Array of recordings if available. See Recording Object below

Initiator Object:

Parameter	Type	Description
uid	String	Initiator’s unique ID. Example: "user1"
name	String	Initiator’s display name. Example: "John Doe"
avatar	String?	Initiator’s avatar URL. Example: "https://example.com/avatar.png"
status	String	Online status. Example: "online"
role	String	User role. Example: "default"

Receiver Object (User):

Parameter	Type	Description
uid	String	Receiver’s unique ID. Example: "user2"
name	String	Receiver’s display name. Example: "Jane Smith"
avatar	String?	Receiver’s avatar URL. Example: "https://example.com/avatar2.png"
status	String	Online status. Example: "offline"
role	String	User role. Example: "default"

Receiver Object (Group):

Parameter	Type	Description
guid	String	Group’s unique ID. Example: "cometchat-guid-1"
name	String	Group’s display name. Example: "Development Team"
icon	String?	Group’s icon URL. Example: "https://example.com/group.png"
type	String	Group type. Example: "public"
membersCount	Int	Number of members. Example: 15

Recording Object:

Parameter	Type	Description
rid	String	Recording ID. Example: "rec_abc123"
recordingUrl	String	URL to download recording. Example: "https://storage.cometchat.io/recordings/..."
startedAt	Int	Recording start timestamp. Example: 1699900010
endedAt	Int	Recording end timestamp. Example: 1699900290
duration	Int	Recording duration in seconds. Example: 280

Error Callback Parameter:

Parameter	Type	Description
error	CometChatException	Error object with details
error.errorCode	String	Error code. Example: "AUTH_ERR"
error.errorDescription	String	Human-readable error message

Fetch Previous

The**fetchPrevious()**method retrieves the previous set of call logs.

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callCategory: .call)
    .build()

callLogRequest.fetchPrevious() { [weak self] callLogs in
    print("fetchPrevious success")
} onError: { [weak self] error in
    print("fetchNext failed with error; \(error.errorDescription)")
}

Sample Payload - fetchPrevious() Request

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls
Method	GET

Query Parameters:

Parameter	Type	Description
mode	String	Call category filter. Example: "call"
page	Int	Previous page number. Example: 0
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token. Example: "cometchat-uid-2_177010263828e3f97e747c568b2e22e600141afe"
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Sample Payload - fetchPrevious() Response

Success Callback Parameter:

Parameter	Type	Description
callLogs	[CallLog]	Array of CallLog objects. See CallLog Object above

Note: Returns empty array [] if no previous logs exist.

Error Callback Parameter:

Parameter	Type	Description
error	CometChatException	Error object with details
error.errorCode	String	Error code. Example: "AUTH_ERR"
error.errorDescription	String	Human-readable error message

Get Call Details

To retrieve the specific details of a call, use the**getCallDetails()**method. This method requires the Auth token of the logged-in user and the session ID along with a success and error callback. Upon success, this function will return a list of call details, as multiple calls can be initiated for one session ID.

var sessionID = "SESSION_ID";
CometChatCalls.getCallDetail(authToken: CometChat.getUserAuthToken(), sessionID: sessionID) { callLogs in
  // Handle the fetched call details
} onError: { error in
    // Handle the error
}

Sample Payload - getCallDetail() Request

Method Parameters:

Parameter	Type	Description
authToken	String	Logged-in user’s authentication token. Example: "cometchat-uid-2_177010263828e3f97e747c568b2e22e600141afe"
sessionID	String	Call session ID to fetch details for. Example: "v1.us.12345678901234567890"

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls/{sessionID}
Method	GET

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID
sdk	String	SDK identifier. Example: "ios@v3.0"

Sample Payload - getCallDetail() Response

Success Callback Parameter:

Parameter	Type	Description
callLogs	[CallLog]	Array of CallLog objects (multiple calls can share same session ID). See CallLog Object below

CallLog Object (Detailed):

Parameter	Type	Description
sessionId	String	Unique call session identifier. Example: "v1.us.12345678901234567890"
initiator	Initiator	User who initiated the call. See Initiator Object below
receiver	Receiver	User/Group who received the call. See Receiver Object below
callType	String	Type of call. Example: "video"
callStatus	String	Final status of call. Example: "ended"
callDirection	String	Direction relative to logged-in user. Example: "outgoing"
startedAt	Int	Unix timestamp when call started. Example: 1699900000
endedAt	Int	Unix timestamp when call ended. Example: 1699900300
duration	Int	Call duration in seconds. Example: 300
hasRecording	Bool	Whether call has recording. Example: true
recordings	[Recording]?	Array of recordings. See Recording Object below
participants	[Participant]?	Array of call participants. See Participant Object below

Initiator Object:

Parameter	Type	Description
uid	String	Initiator’s unique ID. Example: "user1"
name	String	Initiator’s display name. Example: "John Doe"
avatar	String?	Initiator’s avatar URL. Example: "https://example.com/avatar.png"
status	String	Online status. Example: "online"
role	String	User role. Example: "default"
lastActiveAt	Int	Last active timestamp. Example: 1699899000

Receiver Object:

Parameter	Type	Description
uid	String	Receiver’s unique ID. Example: "user2"
name	String	Receiver’s display name. Example: "Jane Smith"
avatar	String?	Receiver’s avatar URL. Example: "https://example.com/avatar2.png"
status	String	Online status. Example: "offline"
role	String	User role. Example: "default"

Recording Object:

Parameter	Type	Description
rid	String	Recording ID. Example: "rec_abc123"
recordingUrl	String	URL to download recording. Example: "https://storage.cometchat.io/recordings/..."
startedAt	Int	Recording start timestamp. Example: 1699900010
endedAt	Int	Recording end timestamp. Example: 1699900290
duration	Int	Recording duration in seconds. Example: 280

Participant Object:

Parameter	Type	Description
uid	String	Participant’s unique ID. Example: "user1"
name	String	Participant’s display name. Example: "John Doe"
avatar	String?	Participant’s avatar URL
joinedAt	Int	Timestamp when participant joined. Example: 1699900005
leftAt	Int	Timestamp when participant left. Example: 1699900295
totalDuration	Int	Total time in call (seconds). Example: 290

Error Callback Parameter:

Parameter	Type	Description
error	CometChatException	Error object with details
error.errorCode	String	Error code. Example: "SESSION_NOT_FOUND"
error.errorDescription	String	Human-readable error message

Note: Replace**"SESSION_ID"**with the ID of the session you are interested in.

Filter Examples

The following examples demonstrate how to use various filters with the CallLogsBuilder.

Filter by Call Type

Audio Calls

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callType: .audio)
    .build()

Video Calls

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callType: .video)
    .build()

Sample Payload - Filter by Call Type

Audio Calls Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&type=audio&perPage=30
Method	GET

Query Parameters (Audio):

Parameter	Type	Description
page	Int	Page number. Example: 1
type	String	Call type filter. Example: "audio"
perPage	Int	Results per page. Example: 30

Video Calls Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&type=video&perPage=30
Method	GET

Query Parameters (Video):

Parameter	Type	Description
page	Int	Page number. Example: 1
type	String	Call type filter. Example: "video"
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Filter by Call Direction

Incoming Calls

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callDirection: .incoming)
    .build()

Outgoing Calls

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callDirection: .outgoing)
    .build()

Sample Payload - Filter by Call Direction

Incoming Calls Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?direction=incoming&page=1&perPage=30
Method	GET

Query Parameters (Incoming):

Parameter	Type	Description
direction	String	Direction filter. Example: "incoming"
page	Int	Page number. Example: 1
perPage	Int	Results per page. Example: 30

Outgoing Calls Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&perPage=30&direction=outgoing
Method	GET

Query Parameters (Outgoing):

Parameter	Type	Description
direction	String	Direction filter. Example: "outgoing"
page	Int	Page number. Example: 1
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Filter by Recording Status

With Recording

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(hasRecording: true)
    .build()

Without Recording

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(hasRecording: false)
    .build()

Sample Payload - Filter by Recording Status

With Recording Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?hasRecording=1&page=1&perPage=30
Method	GET

Query Parameters (With Recording):

Parameter	Type	Description
hasRecording	Int	Recording filter (1 = true). Example: 1
page	Int	Page number. Example: 1
perPage	Int	Results per page. Example: 30

Without Recording Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&perPage=30
Method	GET

Query Parameters (Without Recording):

Parameter	Type	Description
page	Int	Page number. Example: 1
perPage	Int	Results per page. Example: 30

Note: When hasRecording is false, the parameter is omitted from the request.

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Filter by User

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(uid: "cometchat-uid-2")
    .build()

Sample Payload - Filter by User

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&uid=cometchat-uid-2&perPage=30
Method	GET

Query Parameters:

Parameter	Type	Description
page	Int	Page number. Example: 1
uid	String	User UID filter. Example: "cometchat-uid-2"
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Response:

Parameter	Type	Description
callLogs	[CallLog]	Array of call logs involving the specified user. See CallLog Object

Filter by Group

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(guid: "cometchat-guid-1")
    .build()

Sample Payload - Filter by Group

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?page=1&guid=cometchat-guid-1&perPage=30
Method	GET

Query Parameters:

Parameter	Type	Description
page	Int	Page number. Example: 1
guid	String	Group GUID filter. Example: "cometchat-guid-1"
perPage	Int	Results per page. Example: 30

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Response:

Parameter	Type	Description
callLogs	[CallLog]	Array of call logs for the specified group. See CallLog Object

Filter by Call Category (Meetings)

var callLogRequest = CometChatCallsSDK.CallLogsRequest.CallLogsBuilder()
    .set(authToken: CometChat.getUserAuthToken())
    .set(limit: 30)
    .set(callCategory: .meet)
    .build()

Sample Payload - Filter by Call Category (Meetings)

HTTP Request:

Parameter	Value
URL	https://{appId}.call-in.cometchat.io/v3.0/calls?perPage=30&page=1&mode=meet
Method	GET

Query Parameters:

Parameter	Type	Description
perPage	Int	Results per page. Example: 30
page	Int	Page number. Example: 1
mode	String	Call category filter. Example: "meet"

Request Headers:

Header	Type	Description
authToken	String	User authentication token
appId	String	CometChat application ID. Example: "279557705a948ad6"
sdk	String	SDK identifier. Example: "ios@v3.0"

Response:

Parameter	Type	Description
callLogs	[CallLog]	Array of meeting logs. See CallLog Object

Meeting-Specific CallLog Properties:

Parameter	Type	Description
sessionId	String	Meeting session ID. Example: "v1.us.meet_12345678901234567890"
callCategory	String	Category. Example: "meet"
participants	[Participant]	Array of meeting participants
scheduledAt	Int?	Scheduled meeting time (if applicable)