Call Logs - CometChat Docs

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
Video Calls

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

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
Outgoing Calls

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

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
Without Recording

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

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)

​Overview

​Fetching Call Logs

​Fetch Next

​Fetch Previous

​Get Call Details

​Filter Examples

​Filter by Call Type

​Filter by Call Direction

​Filter by Recording Status

​Filter by User

​Filter by Group

​Filter by Call Category (Meetings)

Overview

Fetching Call Logs

Fetch Next

Fetch Previous

Get Call Details

Filter Examples

Filter by Call Type

Filter by Call Direction

Filter by Recording Status

Filter by User

Filter by Group

Filter by Call Category (Meetings)