Send A Message

Guide to sending text, media, and custom messages to users and groups using the CometChat iOS SDK with delivery callbacks.

Quick Reference for AI Agents & Developers

• Text message: TextMessage(receiverUid:text:receiverType:) → CometChat.sendTextMessage(message:onSuccess:onError:)
• Media message: MediaMessage(receiverUid:fileurl:messageType:receiverType:) → CometChat.sendMediaMessage(message:onSuccess:onError:)
• Custom message: CustomMessage(receiverUid:receiverType:customData:type:) → CometChat.sendCustomMessage(message:onSuccess:onError:)
• Receiver types: .user, .group
• Related: Receive Message · Interactive Messages · Messaging Overview

Using CometChat, you can send three types of messages:

1. A text message, the most common and standard message type.
2. A media message, for sending photos, videos and files.
3. A custom message, for sending completely custom data using JSON structures.
4. A Interactive Messages , for sending end-user interactive messages of type form, card and custom Interactive

You can also send metadata along with a text, media or custom message. Think, for example, if you’d want to share the user’s location with every message, you can use the metadata field.

---

Object Structures

TextMessage Object

The TextMessage object represents a text message in CometChat.

Parameter	Type	Description
id	Int	Unique message identifier assigned by CometChat
muid	String	Message unique identifier (client-generated)
conversationId	String	Unique conversation identifier
senderUid	String	UID of the message sender
receiverUid	String	UID/GUID of the message receiver
receiverType	CometChat.ReceiverType	.user (0) or .group (1)
messageType	CometChat.MessageType	.text (0) for text messages
messageCategory	CometChat.MessageCategory	.message (0) for standard messages
sentAt	Int	Unix timestamp when message was sent
deliveredAt	Double	Unix timestamp when message was delivered
readAt	Double	Unix timestamp when message was read
editedAt	Double	Unix timestamp when message was edited
deletedAt	Double	Unix timestamp when message was deleted
updatedAt	Double	Unix timestamp of last update
editedBy	String	UID of user who edited the message
deletedBy	String	UID of user who deleted the message
parentMessageId	Int	ID of parent message (for threaded replies)
replyCount	Int	Number of replies to this message
unreadRepliesCount	Int	Number of unread replies
metaData	[String: Any]	Custom metadata dictionary
mentionedUsers	[User]	Array of mentioned users
mentionedMe	Bool	Whether current user is mentioned
reactions	[ReactionCount]	Array of reaction counts
text	String	The text content of the message
tags	[String]	Array of tags associated with the message
sender	User	User object of the sender
receiver	User or Group	User or Group object of the receiver

MediaMessage Object

The MediaMessage object represents a media message (image, video, audio, file) in CometChat.

Parameter	Type	Description
id	Int	Unique message identifier assigned by CometChat
muid	String	Message unique identifier (client-generated)
conversationId	String	Unique conversation identifier
senderUid	String	UID of the message sender
receiverUid	String	UID/GUID of the message receiver
receiverType	CometChat.ReceiverType	.user (0) or .group (1)
messageType	CometChat.MessageType	.image (1), .video (2), .audio (3), .file (4)
messageCategory	CometChat.MessageCategory	.message (0) for standard messages
sentAt	Int	Unix timestamp when message was sent
deliveredAt	Double	Unix timestamp when message was delivered
readAt	Double	Unix timestamp when message was read
editedAt	Double	Unix timestamp when message was edited
deletedAt	Double	Unix timestamp when message was deleted
updatedAt	Double	Unix timestamp of last update
parentMessageId	Int	ID of parent message (for threaded replies)
replyCount	Int	Number of replies to this message
unreadRepliesCount	Int	Number of unread replies
metaData	[String: Any]	Custom metadata dictionary
mentionedUsers	[User]	Array of mentioned users
mentionedMe	Bool	Whether current user is mentioned
reactions	[ReactionCount]	Array of reaction counts
attachment	Attachment	Single attachment object
attachments	[Attachment]?	Array of attachments (for multiple files)
caption	String?	Caption text for the media
tags	[String]	Array of tags associated with the message
sender	User	User object of the sender
receiver	User or Group	User or Group object of the receiver

CustomMessage Object

The CustomMessage object represents a custom message with arbitrary data.

Parameter	Type	Description
id	Int	Unique message identifier assigned by CometChat
muid	String	Message unique identifier (client-generated)
conversationId	String	Unique conversation identifier
senderUid	String	UID of the message sender
receiverUid	String	UID/GUID of the message receiver
receiverType	CometChat.ReceiverType	.user (0) or .group (1)
messageType	CometChat.MessageType	Custom type string
messageCategory	CometChat.MessageCategory	.custom (3) for custom messages
sentAt	Int	Unix timestamp when message was sent
deliveredAt	Double	Unix timestamp when message was delivered
readAt	Double	Unix timestamp when message was read
editedAt	Double	Unix timestamp when message was edited
deletedAt	Double	Unix timestamp when message was deleted
updatedAt	Double	Unix timestamp of last update
parentMessageId	Int	ID of parent message (for threaded replies)
replyCount	Int	Number of replies to this message
unreadRepliesCount	Int	Number of unread replies
metaData	[String: Any]	Custom metadata dictionary
mentionedUsers	[User]	Array of mentioned users
mentionedMe	Bool	Whether current user is mentioned
reactions	[ReactionCount]	Array of reaction counts
customType	String	Custom type identifier (e.g., “location”, “poll”)
customData	[String: Any]	Custom data dictionary
subType	String?	Optional sub-type for further categorization
updateConversation	Bool	Whether to update conversation’s last message
conversationText	String?	Custom text for conversation preview/notifications
tags	[String]	Array of tags associated with the message
sender	User	User object of the sender
receiver	User or Group	User or Group object of the receiver

User Object

The User object represents a CometChat user.

Parameter	Type	Description
uid	String	Unique user identifier
name	String	Display name of the user
avatar	String?	Avatar image URL
link	String?	Profile link URL
role	String	User role (e.g., “default”, “moderator”, “admin”)
status	CometChat.UserStatus	.online (0) or .offline (1)
statusMessage	String?	Custom status message
lastActiveAt	Double	Unix timestamp of last activity
hasBlockedMe	Bool	Whether this user has blocked the logged-in user
blockedByMe	Bool	Whether the logged-in user has blocked this user
metadata	[String: Any]	Custom metadata dictionary
deactivatedAt	Double	Unix timestamp when user was deactivated (0 if active)
tags	[String]	Array of tags associated with the user

Group Object

The Group object represents a CometChat group.

Parameter	Type	Description
guid	String	Unique group identifier
name	String	Display name of the group
icon	String?	Group icon image URL
description	String?	Group description
type	CometChat.GroupType	.public, .private, or .password
owner	String	UID of the group owner
membersCount	Int	Number of members in the group
createdAt	Double	Unix timestamp when group was created
updatedAt	Double	Unix timestamp of last update
hasJoined	Bool	Whether the logged-in user has joined the group
joinedAt	Double	Unix timestamp when user joined the group
scope	CometChat.GroupMemberScope	.participant, .moderator, or .admin
metadata	[String: Any]?	Custom metadata dictionary
tags	[String]?	Array of tags associated with the group

Attachment Object

The Attachment object represents a file attachment in a media message.

Parameter	Type	Description
fileName	String	Name of the file
fileExtension	String	File extension (e.g., “jpg”, “pdf”)
fileSize	Int	File size in bytes
fileMimeType	String	MIME type (e.g., “image/jpeg”, “application/pdf”)
fileUrl	String	URL to access the file

CometChatException Object

The CometChatException object represents an error returned by the SDK.

Parameter	Type	Description
errorCode	String	Unique error code identifier
errorDescription	String	Human-readable error message
details	String?	Additional context or troubleshooting information

---

Text Message

In other words, as a sender, how do I send a text message?

To send a text message to a single user or group, you need to use the sendMessage() method and pass a TextMessage object to it.

Add Metadata

To send custom data along with a text message, you can use the metadata field provided in TextMessage. A metadata field is a dictionary of type [String: Any] which will be received as it was sent without any processing from CometChat. It can be used to send any additional data that needs to be sent along with a message.

Swift

let metadata = ["latitude":"50.6192171633316","longitude":"-72.68182268750002"];

textMessage.metaData = metadata;

Objective C

NSDictionary * metadata = @{@"latitude":@"50.6192171633316",@"longitude":@"-72.68182268750002"};

[textMessage setMetaData:metadata];

Add Tags

To add a tag to a message you can use Array of strings that you need to set it to property tags.

Swift

let tags = ["pinned"]

textMessage.tags = tags;

Objective C

NSArray * tags = @[@"latitude"];

[textMessage setTags:tags];

Once the text message object is ready, you need to use the sendMessage() method to send the text message to the recipient.

User(Swift)

let receiverID = "cometchat-uid-2"
let text = "Hello"

let textMessage = TextMessage(receiverUid: receiverID, text: text, receiverType: .user)

CometChat.sendTextMessage(message: textMessage, onSuccess: { (message) in

  print("TextMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("TextMessage sending failed with error: " + error!.errorDescription);
}

User(Objective C)

NSString *receiverID = @"cometchat-uid-1";
NSString *text       = @"Hello";

TextMessage *textMessage = [[TextMessage alloc]initWithReceiverUid:receiverID text:text receiverType:ReceiverTypeUser];

[CometChat sendTextMessageWithMessage:textMessage onSuccess:^(TextMessage * message) {

    NSLog(@"TextMessage sent successfully. %@",[message stringValue]);

} onError:^(CometChatException * error) {

    NSLog(@"TextMessage sending failed with error: %@",[error errorDescription]);
}];

Group(Swift)

let receiverID = "cometchat-guid-102"
let text = "Hello"

let textMessage = TextMessage(receiverUid: receiverID, text: text, receiverType: .group)

CometChat.sendTextMessage(message: textMessage, onSuccess: { (message) in

  print("TextMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("TextMessage sending failed with error: " + error!.errorDescription);
}

Group(Objective C)

NSString *receiverID = @"cometchat-guid-101";
NSString *text       = @"Hello";

TextMessage *textMessage = [[TextMessage alloc]initWithReceiverUid:receiverID text:text receiverType:ReceiverTypeGroup];

[CometChat sendTextMessageWithMessage:textMessage onSuccess:^(TextMessage * message) {

    NSLog(@"TextMessage sent successfully. %@",[message stringValue]);

} onError:^(CometChatException * error) {

    NSLog(@"TextMessage sending failed with error: %@",[error errorDescription]);
}];

The TextMessage class constructor takes the following parameters:

Parameters	Information
receiverID	The UID or GUID of the recipient
text	The text to be sent
receiverType	The type of the receiver to whom the message is to be sent i.e user or group

The login() method returns the TextMessage object containing all the information of the sent message.

Sample Payloads

Request

Method: CometChat.sendTextMessage(message:)

Object Type: TextMessage (before sending)

Parameter	Type	Value
id	Int	0
muid	String	""
conversationId	String	""
senderUid	String	""
receiverUid	String	"cometchat-uid-3"
receiverType	CometChat.ReceiverType	0 (.user)
messageType	CometChat.MessageType	0 (.text)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	0
deliveredAt	Double	0.0
readAt	Double	0.0
editedAt	Double	0.0
deletedAt	Double	0.0
updatedAt	Double	0.0
editedBy	String	""
deletedBy	String	""
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
metaData	[String: Any]	[:] (empty dictionary)
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
text	String	"Hello"
sender	User?	nil
receiver	User?	nil

Success Response

Object Type: TextMessage

Parameter	Type	Value
id	Int	37798
muid	String	""
conversationId	String	"cometchat-uid-2_user_cometchat-uid-3"
senderUid	String	"cometchat-uid-2"
receiverUid	String	"cometchat-uid-3"
receiverType	CometChat.ReceiverType	0 (.user)
messageType	CometChat.MessageType	0 (.text)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1771917734
deliveredAt	Double	0.0
readAt	Double	0.0
editedAt	Double	0.0
deletedAt	Double	0.0
updatedAt	Double	1771917734.0
editedBy	String	""
deletedBy	String	""
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
metaData	[String: Any]	[:] (empty dictionary)
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
text	String	"Hello"

sender (User):

Parameter	Type	Value
uid	String	"cometchat-uid-2"
name	String	"George Alan"
avatar	String	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-2.webp"
link	String?	nil
role	String	"moderator"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1771917720.0
hasBlockedMe	Bool	false
blockedByMe	Bool	false
metadata	[String: Any]	[:] (empty dictionary)
deactivatedAt	Double	0.0

receiver (User):

Parameter	Type	Value
uid	String	"cometchat-uid-3"
name	String	"Nancy Grace"
avatar	String	"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-3.webp"
link	String?	nil
role	String	"moderator"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1771586880.0
hasBlockedMe	Bool	false
blockedByMe	Bool	false
metadata	[String: Any]	[:] (empty dictionary)
deactivatedAt	Double	0.0

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_NOT_LOGGED_IN"
errorDescription	String	"User is not logged in. Please login first."

More Sample Payloads

TextMessage to Group

Object Type: TextMessage

Parameter	Type	Value
id	Int	143
muid	String	"1708934500456_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"group_dev_team"
text	String	"Team meeting at 3 PM"
messageType	CometChat.MessageType	0 (.text)
receiverType	CometChat.ReceiverType	1 (.group)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708934500
deliveredAt	Double?	nil
readAt	Double?	nil
editedAt	Double?	nil
deletedAt	Double?	nil
editedBy	String?	nil
deletedBy	String?	nil
conversationId	String	"group_group_dev_team"
metaData	[String: Any]?	nil
tags	[String]?	nil
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
quotedMessageId	Int	0
quotedMessage	BaseMessage?	nil

sender (User):

Parameter	Type	Value
uid	String	"user_12345"
name	String	"John Doe"
avatar	String	"https://data-us.cometchat.io/avatars/user_12345.png"
link	String?	nil
role	String	"default"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1708934500.0
metadata	[String: Any]?	nil
tags	[String]?	nil
hasBlockedMe	Bool	false
blockedByMe	Bool	false

receiver (Group):

Parameter	Type	Value
guid	String	"group_dev_team"
name	String	"Development Team"
icon	String	"https://data-us.cometchat.io/groups/dev_team.png"
description	String	"Team for development discussions"
type	CometChat.GroupType	"public"
owner	String	"user_admin"
membersCount	Int	15
createdAt	Double	1700000000.0
updatedAt	Double	1708900000.0
hasJoined	Bool	true
joinedAt	Double	1705000000.0
scope	CometChat.GroupMemberScope	"participant"
metadata	[String: Any]?	nil
tags	[String]?	nil

With Metadata

Object Type: TextMessage

Parameter	Type	Value
id	Int	144
muid	String	"1708935000789_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
text	String	"I'm at this location"
messageType	CometChat.MessageType	0 (.text)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708935000
conversationId	String	"user_12345_user_user_67890"
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
quotedMessageId	Int	0
quotedMessage	BaseMessage?	nil
tags	[String]?	nil

metaData ([String: Any]):

Key	Type	Value
latitude	String	"50.6192171633316"
longitude	String	"-72.68182268750002"

sender (User):

Parameter	Type	Value
uid	String	"user_12345"
name	String	"John Doe"
avatar	String	"https://data-us.cometchat.io/avatars/user_12345.png"
status	CometChat.UserStatus	0 (.online)

receiver (User):

Parameter	Type	Value
uid	String	"user_67890"
name	String	"Jane Smith"
avatar	String	"https://data-us.cometchat.io/avatars/user_67890.png"
status	CometChat.UserStatus	0 (.online)

With Tags

Object Type: TextMessage

Parameter	Type	Value
id	Int	145
muid	String	"1708935500123_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
text	String	"Important announcement"
messageType	CometChat.MessageType	0 (.text)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708935500
conversationId	String	"user_12345_user_user_67890"
metaData	[String: Any]?	nil
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
quotedMessageId	Int	0
quotedMessage	BaseMessage?	nil

tags ([String]):

Index	Type	Value
0	String	"pinned"
1	String	"important"
2	String	"announcement"

Set Quoted Message

To set a quoted message for a message, use the quotedMessageId.

Swift

textMessage.quotedMessageId = 0
textMessage.quotedMessage =  // Pass base message object here that you want to quote.

Once the text message object is ready, you need to use the sendMessage() method to send the text message to the recipient.

Swift

var textMessage = TextMessage(receiverUid: currentUser?.uid ?? "", text: message, receiverType: .user)
textMessage.quotedMessageId = swipedMessage.id

CometChat.sendTextMessage(message: textMessage, onSuccess: { (message) in
    print("success")
}) { (error) in
    DispatchQueue.main.async {
        if let error = error {
            print(error.errorDescription)
        }
    }
}

The TextMessage class constructor takes the following parameters:

Parameter	Description
receiverID	UID of the user or GUID of the group receiving the message	Required
messageText	The text message	Required
receiverType	The type of the receiver- CometChatConstants.RECEIVER_TYPE_USER (user) or CometChatConstants.RECEIVER_TYPE_GROUP (group)	Required

When a text message is sent successfully, the response will include a TextMessage object which includes all information related to the sent message.

Sample Payloads - Quoted Message

Request

Method: CometChat.sendTextMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
text	String	"I agree with this!"
receiverType	CometChat.ReceiverType	0 (.user)
quotedMessageId	Int	140

Success Response

Object Type: TextMessage

Parameter	Type	Value
id	Int	146
muid	String	"1708936000456_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
text	String	"I agree with this!"
messageType	CometChat.MessageType	0 (.text)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708936000
conversationId	String	"user_12345_user_user_67890"
quotedMessageId	Int	140

quotedMessage (TextMessage):

Parameter	Type	Value
id	Int	140
muid	String	"1708930000789_user_67890"
senderUid	String	"user_67890"
receiverUid	String	"user_12345"
text	String	"What do you think about the proposal?"
messageType	CometChat.MessageType	0 (.text)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708930000
deliveredAt	Double	1708930005.0
readAt	Double	1708930010.0
conversationId	String	"user_12345_user_user_67890"
replyCount	Int	1

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_NOT_LOGGED_IN"
errorDescription	String	"User is not logged in. Please login first."
details	String?	nil

---

Media Message

In other words, as a sender, how do I send a media message like photos, videos & files?

To send a media message to any user or group, you need to use the sendMediaMessage() method and pass a MediaMessage object to it.

Add Metadata

To send custom data along with a media message, you can use the metadata field provided in MediaMessage. A metadata field is a dictionary of type [String: Any] which will be received as it was sent without any processing from CometChat. It can be used to send any additional data that needs to be sent along with a message.

Swift

let metadata = ["latitude":"50.6192171633316","longitude":"-72.68182268750002"];

mediaMessage.metaData = metadata;

Objective C

NSDictionary * metadata = @{@"latitude":@"50.6192171633316",@"longitude":@"-72.68182268750002"};

[mediaMessage setMetaData:metadata];

Add Caption(Text along with Media Message)

To send a caption with a media message, you can use setCaption method and pass text to it.

Swift

mediaMessage.caption = "Message Caption"

Add Tags

To add a tag to a message you can use Array of strings that you need to set it to property tags.

Swift

let tags = ["pinned"]

textMessage.tags = tags;

Objective C

NSArray * tags = @[@"latitude"];

[textMessage setTags:tags];

There are 2 ways you can send Media Messages using the CometChat SDK:

1. By providing the File : You can directly share the file object while creating an object of the MediaMessage class. When the media message is sent using the sendMediaMessage() method, this file is then uploaded to CometChat servers and the URL of the file is sent in the success response of the sendMediaMessage() function.

Swift

let receiverid = "cometchat-uid-2"

let mediaUrl = "file:___Library_Developer_CoreSimulator_Devices_(numbers and letters)_data_Containers_Data_Application_(numbers and letters)_Documents_image.jpg"

let mediaMessage = MediaMessage(receiverUid: receiverid, fileurl:mediaUrl, messageType: .image, receiverType: .user);

CometChat.sendMediaMessage(message: mediaMessage, onSuccess: { (message) in

  print("MediaMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("MediaMessage sending failed with error: " + error.errorDescription);
}

Objective C

NSString *receiverID = @"cometchat-uid-1";

NSString *filePath = @"Library_Developer_CoreSimulator_Devices_(numbers and letters)_data_Containers_Data_Application_(numbers and letters)_Documents_image.jpg";

MediaMessage *mediaMessage = [MediaMessage alloc]initWithReceiverUid:receiverID fileurl:filePath messageType:messageTypeImage receiverType:ReceiverTypeUser];

[CometChat sendMediaMessageWithMessage:mediaMessage onSuccess:^(MediaMessage * message) {

    NSLog(@"MediaMessage sent successfully. %@",[message stringValue]);

} onError:^(CometChatException * error) {

    NSLog(@"MediaMessage sending failed with error: %@",[error errorDescription]);

}];

To send a media message you need to create an object of the MediaMessage class. The initialize method of the MediaMessage class takes the following mandatory parameters:

Parameter	Description
receiverId	The UID or GUID of the recipient	Required
fileurl	The file path object to be sent	Required
messageType	The type of the message that needs to be sent which in this case can be: - image - video - audio - file	Required
receiverType	The type of the receiver to whom the message is to be sent - user - group	Required

2. By providing the URL of the File: The second way to send media messages using the CometChat SDK is to provide the SDK with the URL of any file that is hosted on your servers or any cloud storage. To achieve this you will have to make use of the Attachment class that is available in the MediaMessage class. For more information, you can refer to the below code snippet:

Swift

let receiverid = "cometchat-uid-2"

let mediaUrl = "https:__pngimg.com_uploads_mario_mario_PNG125.png"

let mediaMessage = MediaMessage(receiverUid: receiverid, fileurl:"", messageType: .image, receiverType: .user);

mediaMessage.attachment = Attachment(fileName: "FileName", fileExtension: "png", fileMimeType: "image_png", fileUrl: mediaUrl);

CometChat.sendMediaMessage(message: mediaMessage, onSuccess: { (message) in

  print("MediaMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("MediaMessage sending failed with error: " + error.errorDescription);
}

On success, you will receive an object of the MediaMessage class containing all the information related to the sent media message.

Sample Payloads

Request

Method: CometChat.sendMediaMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
messageType	CometChat.MessageType	1 (.image)
receiverType	CometChat.ReceiverType	0 (.user)
fileUrl	String	"file:///Library/Developer/CoreSimulator/.../image.jpg"

Success Response

Object Type: MediaMessage

Parameter	Type	Value
id	Int	147
muid	String	"1708936500789_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
messageType	CometChat.MessageType	1 (.image)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708936500
deliveredAt	Double?	nil
readAt	Double?	nil
editedAt	Double?	nil
deletedAt	Double?	nil
editedBy	String?	nil
deletedBy	String?	nil
conversationId	String	"user_12345_user_user_67890"
metaData	[String: Any]?	nil
tags	[String]?	nil
caption	String?	nil
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)
attachments	[Attachment]?	nil

attachment (Attachment):

Parameter	Type	Value
fileName	String	"photo_2024.jpg"
fileExtension	String	"jpg"
fileSize	Int	245678
fileMimeType	String	"image/jpeg"
fileUrl	String	"https://data-us.cometchat.io/assets/images/photo_2024.jpg"

sender (User):

Parameter	Type	Value
uid	String	"user_12345"
name	String	"John Doe"
avatar	String	"https://data-us.cometchat.io/avatars/user_12345.png"
link	String?	nil
role	String	"default"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1708936500.0
metadata	[String: Any]?	nil
tags	[String]?	nil
hasBlockedMe	Bool	false
blockedByMe	Bool	false

receiver (User):

Parameter	Type	Value
uid	String	"user_67890"
name	String	"Jane Smith"
avatar	String	"https://data-us.cometchat.io/avatars/user_67890.png"
link	String?	nil
role	String	"default"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1708936000.0
metadata	[String: Any]?	nil
tags	[String]?	nil
hasBlockedMe	Bool	false
blockedByMe	Bool	false

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_FILE_SIZE_EXCEEDED"
errorDescription	String	"File size exceeds the maximum allowed limit of 100MB."
details	String?	nil

More Sample Payloads

Image to Group

Object Type: MediaMessage

Parameter	Type	Value
id	Int	148
muid	String	"1708937000123_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"group_dev_team"
messageType	CometChat.MessageType	1 (.image)
receiverType	CometChat.ReceiverType	1 (.group)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708937000
conversationId	String	"group_group_dev_team"
caption	String?	nil
parentMessageId	Int	0
replyCount	Int	0

attachment (Attachment):

Parameter	Type	Value
fileName	String	"team_photo.png"
fileExtension	String	"png"
fileSize	Int	512000
fileMimeType	String	"image/png"
fileUrl	String	"https://data-us.cometchat.io/assets/images/team_photo.png"

receiver (Group):

Parameter	Type	Value
guid	String	"group_dev_team"
name	String	"Development Team"
icon	String	"https://data-us.cometchat.io/groups/dev_team.png"
description	String	"Team for development discussions"
type	CometChat.GroupType	"public"
owner	String	"user_admin"
membersCount	Int	15

With Caption

Object Type: MediaMessage

Parameter	Type	Value
id	Int	151
muid	String	"1708938500123_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
messageType	CometChat.MessageType	1 (.image)
receiverType	CometChat.ReceiverType	0 (.user)
sentAt	Int	1708938500
conversationId	String	"user_12345_user_user_67890"
caption	String	"Check out this amazing view from my vacation!"

attachment (Attachment):

Parameter	Type	Value
fileName	String	"vacation_photo.jpg"
fileExtension	String	"jpg"
fileSize	Int	1024000
fileMimeType	String	"image/jpeg"
fileUrl	String	"https://data-us.cometchat.io/assets/images/vacation_photo.jpg"

With Tags

Object Type: MediaMessage

Parameter	Type	Value
id	Int	152
muid	String	"1708939000456_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
messageType	CometChat.MessageType	4 (.file)
receiverType	CometChat.ReceiverType	0 (.user)
sentAt	Int	1708939000
conversationId	String	"user_12345_user_user_67890"
caption	String	"Please review the updated contract"

tags ([String]):

Index	Type	Value
0	String	"pinned"
1	String	"important"
2	String	"contract"

attachment (Attachment):

Parameter	Type	Value
fileName	String	"contract_v2.pdf"
fileExtension	String	"pdf"
fileSize	Int	2048000
fileMimeType	String	"application/pdf"
fileUrl	String	"https://data-us.cometchat.io/assets/files/contract_v2.pdf"

If you wish to send a caption or some text along with the Media Message, you can use the caption field provided by the MediaMessage class. To set the caption you can use the setCaption() method and at the receiver end, you can obtain the caption using the getCaption() method. As with text messages, the metadata field can be used with media messages as well. Any additional information can be passed along with the media message as a JSONObject.

---

Multiple Attachments in a Media Message

Starting version 3.0.906 & above the SDK supports sending of multiple attachments in a single media message. As in case for single attachment in a media message, there are two ways you can send Media Messages using the CometChat SDK:

1. By providing an array of files: You can now share a List of files while creating an object of the MediaMessage class. When the media message is sent using the sendMediaMessage() method, the files are uploaded to the CometChat servers & the URL of the files are sent in the success response of the sendMediaMessage() method.

Swift

String receiverId = "cometchat-uid-1"

let data = try? Data(contentsOf: URL(string: " file:___private_var_mobile_Containers_Data_Application_B71B0A14_tmp_1111.jpeg")
let data1 = try? Data(contentsOf: URL(string: " file:___private_var_mobile_Containers_Data_Application_B71B0A14_tmp_2222.jpeg")
let data2 = try? Data(contentsOf: URL(string: " file:___private_var_mobile_Containers_Data_Application_B71B0A14_tmp_3333.jpeg")

var files = [File]()
files.append(File(name: "FileName 1", data: data)
files.append(File(name: "FileName 2", data: data1)
files.append(File(name: "FileName 3", data: data2)

mediaMessage = MediaMessage(receiverUid: self.currentUser?.uid ?? "", files: files, messageType: .file, receiverType: .user)

CometChat.sendMediaMessage(message: mediaMessage, onSuccess: { (message) in
	print("Message sent successfully")
}, onError: { (error) in
  print("Message sending failed with exception : ", error?.errorDescription)
}

Sample Payloads - Multiple Attachments

Request

Method: CometChat.sendMediaMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
messageType	CometChat.MessageType	4 (.file)
receiverType	CometChat.ReceiverType	0 (.user)

files ([File]):

Index	name	data
0	"FileName 1"	<binary_data>
1	"FileName 2"	<binary_data>
2	"FileName 3"	<binary_data>

Success Response

Object Type: MediaMessage

Parameter	Type	Value
id	Int	153
muid	String	"1708939500789_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
messageType	CometChat.MessageType	4 (.file)
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	0 (.message)
sentAt	Int	1708939500
conversationId	String	"user_12345_user_user_67890"
caption	String	"Here are the project files"
attachment	Attachment?	nil

attachments ([Attachment]):

Index	fileName	fileExtension	fileSize	fileMimeType	fileUrl
0	"document1.pdf"	"pdf"	102400	"application/pdf"	"https://data-us.cometchat.io/assets/files/document1.pdf"
1	"image1.png"	"png"	51200	"image/png"	"https://data-us.cometchat.io/assets/images/image1.png"
2	"video1.mp4"	"mp4"	5242880	"video/mp4"	"https://data-us.cometchat.io/assets/videos/video1.mp4"

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_FILE_SIZE_EXCEEDED"
errorDescription	String	"File size exceeds the maximum allowed limit of 100MB."
details	String?	nil

---

Custom Message

CometChat SDK allows you to send a completely custom message across. You can use this feature to send messages that do not fit in any default categories provided. In order to send a custom message, you need to use the sendCustomMessage() method.

The sendCustomMessage() methods takes an object of the CustomMessage which can be obtained using the below two constructor:

Swift

let customMessage : CustomMessage = CustomMessage(receiverId: receiverId, receiverType: .user, customData : customData, type: "Custom Type")

The above constructor, helps you create a custom message with the message type set to whatever is passed to the constructor and the category set to custom.

The parameters involved are:

1. receiverId - Unique id of the user or group to which the message is to be sent.
2. receiverType - Type of the receiver i.e user or group
3. type - custom message type that you need to set
4. customData - The data to be passed as the message in the form of a Dictionary object.

You can also use the subType field of the CustomMessage class to set a specific type for the CustomeMessage.

Add Tags

To add a tag to a message you can use Array of strings that you need to set it to property tags.

Swift

let tags = ["pinned"]

textMessage.tags = tags;

Objective C

NSArray * tags = @[@"latitude"];

[textMessage setTags:tags];

Once the object of CustomMessage class is ready you can send the custom message using the sendCustomMessage() method.

User(Swift)

let receiverid = "cometchat-uid-2"

let customData : [String : Any] = ["customKey" : "customData"]

let customMessage = CustomMessage(receiverUid: receiverid, receiverType: .user, customData : customData, type: "Custom Type");

CometChat.sendCustomMessage(message: customMessage, onSuccess: { (message) in

  print("CustomMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("CustomMessage sending failed with error: " + error!.errorDescription);
}

Group(Swift)

let receiverid = "cometchat-uid-2"

let customData : [String : Any] = ["customKey" : "customData"]

let customMessage = CustomMessage(receiverUid: receiverid, receiverType: .group, customData : customData, type: "Custom Type");

CometChat.sendCustomMessage(message: customMessage, onSuccess: { (message) in

  print("CustomMessage sent successfully. " + message.stringValue())

}) { (error) in

  print("CustomMessage sending failed with error: " + error!.errorDescription);
}

The above sample explains how custom messages can be used to share the location with a user. The same can be achieved for groups.

In success, you will receive an object of the CustomMessage class.

Sample Payloads

Request

Method: CometChat.sendCustomMessage(message:)

Parameter	Type	Value
receiverUid	String	"cometchat-uid-2"
receiverType	CometChat.ReceiverType	0 (.user)
type	String	"Custom Type"

customData ([String: Any]):

Key	Type	Value
customKey	String	"customData"

Success Response

Object Type: CustomMessage

Parameter	Type	Value
id	Int	200
muid	String	"1708940000123_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
customType	String	"Custom Type"
subType	String?	nil
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	3 (.custom)
sentAt	Int	1708940000
deliveredAt	Double?	nil
readAt	Double?	nil
editedAt	Double?	nil
deletedAt	Double?	nil
editedBy	String?	nil
deletedBy	String?	nil
conversationId	String	"user_12345_user_user_67890"
metaData	[String: Any]?	nil
tags	[String]?	nil
updateConversation	Bool	true
conversationText	String?	nil
parentMessageId	Int	0
replyCount	Int	0
unreadRepliesCount	Int	0
mentionedUsers	[User]	[] (empty array)
mentionedMe	Bool	false
reactions	[ReactionCount]	[] (empty array)

customData ([String: Any]):

Key	Type	Value
customKey	String	"customData"

sender (User):

Parameter	Type	Value
uid	String	"user_12345"
name	String	"John Doe"
avatar	String	"https://data-us.cometchat.io/avatars/user_12345.png"
link	String?	nil
role	String	"default"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1708940000.0
metadata	[String: Any]?	nil
tags	[String]?	nil
hasBlockedMe	Bool	false
blockedByMe	Bool	false

receiver (User):

Parameter	Type	Value
uid	String	"user_67890"
name	String	"Jane Smith"
avatar	String	"https://data-us.cometchat.io/avatars/user_67890.png"
link	String?	nil
role	String	"default"
status	CometChat.UserStatus	0 (.online)
statusMessage	String?	nil
lastActiveAt	Double	1708939000.0
metadata	[String: Any]?	nil
tags	[String]?	nil
hasBlockedMe	Bool	false
blockedByMe	Bool	false

Error Response

Object Type: CometChatException

Parameter	Type	Value
errorCode	String	"ERR_NOT_LOGGED_IN"
errorDescription	String	"User is not logged in. Please login first."
details	String?	nil

Real-World Examples

Location Sharing

Object Type: CustomMessage

Parameter	Type	Value
id	Int	209
muid	String	"1708944500123_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
customType	String	"location"
subType	String?	nil
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	3 (.custom)
sentAt	Int	1708944500
conversationId	String	"user_12345_user_user_67890"
updateConversation	Bool	true
conversationText	String	"📍 Shared a location"

customData ([String: Any]):

Key	Type	Value
latitude	String	"37.7749"
longitude	String	"-122.4194"
address	String	"San Francisco, CA"
accuracy	Double	10.5

Poll Message

Object Type: CustomMessage

Parameter	Type	Value
id	Int	210
muid	String	"1708945000456_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"group_dev_team"
customType	String	"poll"
subType	String	"single_choice"
receiverType	CometChat.ReceiverType	1 (.group)
messageCategory	CometChat.MessageCategory	3 (.custom)
sentAt	Int	1708945000
conversationId	String	"group_group_dev_team"
updateConversation	Bool	true
conversationText	String	"📊 Created a poll: What framework should we use?"

customData ([String: Any]):

Key	Type	Value
question	String	"What framework should we use?"
allowMultiple	Bool	false
expiresAt	Int	1709023400

customData.options ([[String: Any]]):

Index	id	text	votes
0	1	"React"	0
1	2	"Vue"	0
2	3	"Angular"	0

tags ([String]):

Index	Type	Value
0	String	"poll"
1	String	"team-decision"

Payment Request

Object Type: CustomMessage

Parameter	Type	Value
id	Int	211
muid	String	"1708945500789_user_12345"
senderUid	String	"user_12345"
receiverUid	String	"user_67890"
customType	String	"payment_request"
subType	String?	nil
receiverType	CometChat.ReceiverType	0 (.user)
messageCategory	CometChat.MessageCategory	3 (.custom)
sentAt	Int	1708945500
conversationId	String	"user_12345_user_user_67890"
updateConversation	Bool	true
conversationText	String	"💰 Requested $50.00"

customData ([String: Any]):

Key	Type	Value
amount	Double	50.00
currency	String	"USD"
note	String	"Dinner split"
requestId	String	"pay_req_12345"

tags ([String]):

Index	Type	Value
0	String	"payment"

Update Conversation

How can I decide whether the custom message should update last message of a conversation?

By default, a custom message will update the last message of a conversation. If you wish to not update last message of conversation when a custom message is sent, please use updateConversation property of the Custom Message.

User(Swift)

let receiverid = "cometchat-uid-2"
let customData : [String : Any] = ["customKey" : "customData"]
let customMessage = CustomMessage(receiverUid: receiverid, receiverType: .user, customData : customData, type: "Custom Type");

customMessage.updateConversation = false //for not updating conversation

CometChat.sendCustomMessage(message: customMessage, onSuccess: { (message) in
  print("CustomMessage sent successfully. " + message.stringValue())
}) { (error) in
  print("CustomMessage sending failed with error: " + error!.errorDescription);
}

Custom Notification Body

How can i customise the notification body of custom message?

To add a custom notification body for Push, Email & SMS notification of a custom message you can use the conversationText property of Custom Message class.

User(Swift)

let receiverid = "cometchat-uid-2"
let customData : [String : Any] = ["customKey" : "customData"]
let customMessage = CustomMessage(receiverUid: receiverid, receiverType: .user, customData : customData, type: "Custom Type");

customMessage.conversationText = "Custom notification body";

CometChat.sendCustomMessage(message: customMessage, onSuccess: { (message) in
  print("CustomMessage sent successfully. " + message.stringValue())
}) { (error) in
  print("CustomMessage sending failed with error: " + error!.errorDescription);
}

It is also possible to send interactive messages from CometChat , to know more click here

---

Common Error Codes

Error Code	Description	Resolution
ERR_NOT_LOGGED_IN	User is not logged in	Call CometChat.login() first
ERR_FILE_SIZE_EXCEEDED	File size exceeds maximum limit	Reduce file size to under 100MB
ERR_INVALID_RECEIVER	Invalid receiver UID/GUID	Verify the receiver exists
ERR_BLOCKED_BY_USER	Blocked by the receiver	Cannot send messages to users who blocked you
ERR_SDK_NOT_INITIALIZED	SDK not initialized	Call CometChat.init() first
ERR_NETWORK_ERROR	Network connectivity issue	Check internet connection and retry