Messages

Messaging is one of the core features of CometChat. We've thoughtfully created APIs to help you send and retrieve message history.

Users can send messages to a user or group.
No limit to the number of unread messages per user.
No limit to the number of unread messages per group.
Soft deleted messages will be available in the database but permanently deleted messages will not be available.

📘
Properties and constraints:

The maximum File size that can be uploaded per message is 100MB.

For a group with more than 300 members, the conversations and unread message counts are not updated.

Delivery and read receipts will be sent for a group of up to 300 online users.

Data is an arbitrary JSON structure. It accepts utf8mb4. It can have any user defined properties. but the below properties have meaning for CometChat: text, attachments, custome_data, metadata
Note: The attachment size is separate. Here, the attachment is only the attachment properties (such as URL, size, etc.). The size must not exceed 10KB for the data object.

A message can have up to 25 tags with 100 characters per tag. The tags can be in any language. The character set must be UTF8mb4.

The following table lists the properties that the Message API supports.

Parameters	Type	Description
receiver	string	Specifies receiver of the message. Maximum length is 100 characters. Allowed characters: alpha-dash (a-z, 0-9 with -and _ ) without spaces
receiverType	string	Specifies the type of receiver of the message. Either user or group.
category	string	Specifies the category of the message. The available categories are message and custom.
type	string	Specifies the type of the message. The available values are text, image, file, audio, video.
data	nested object	Specifies a JSON object to store up to 10K characters (JSON stringified data) for text,metadata,customData,attachments.
multipleReceivers	object	Specifies a list of receivers who will receive the message. It can have the below optional properties: uids: A string array of UIDs of the existing users to be added as receivers. guids: A string array of GUIDs of the existing groups to be added as receivers. Failure to sending a message to a receiver does not result into create send message API failure. However, the individual message failure can be seen in the error objects in uids or guids. Maximum of 25 receivers(uids and guids combined) can be added for a single message.
tags	array of strings	(optional) Specifies a list of tags to be associated with certain users. Maximum of 25 tags can be associated with a single user.

Interactive Messages:

Parameters	Type	Description
receiver	string	Specifies receiver of the message. Maximum length is 100 characters. Allowed characters: alpha-dash (a-z, 0-9 with -and _ ) without spaces
receiverType	string	Specifies the type of receiver of the message. Either user or group.
category	string	Specifies the category of the message. The available category is interactive.
type	string	Specifies the type of the message. The available values are form, card and customInteractive for type interactive.
data	nested object	Specifies a JSON object to store up to 10K characters (JSON stringified data) for text,metadata,customData,attachments.
data.interactionGoal	nested object	(optional) Specifies a JSON Object which has two properties type and elementIds.
data.interactionGoal.type	string	Defines the goal to mark the message as Interaction goals are successful none → no element IDs required, AllOf→ at least one element ID is required AnyOf → at least one element ID required AnyAction → no element ID required
data.interactionGoal.elementIds	Array of Strings	Defines an array of element IDs which when mentioned help in achieving the goal based on the above types.
data.allowSenderInteractions	boolean	(optional) If present, specifies if the interaction from sender will be allowed or not
data.interactiveData	nested object	Specifies a JSON Object to add Interactive data.
data.interactiveData.title	String	Specifies the title of the form.
data.interactiveData.text	String	Note: required in case of type : card
data.interactiveData.goalCompletionText	String	optional Specifies the goal completion text.
data.interactiveData.formFields	nested object	(Required) defines the fields visible in the form, Form fields will contain the different elements. Note: required in case of type : form
data.interactiveData.imageUrl	String	optional Would be considered in case of type: form
data.interactiveData.cardActions	JSON Array	Required, defines the submit button to be visible in the Form, Validate it for button element JSON. Note: required in case of type : card
data.interactiveData.submitElement	JSON Array	If specified, it defines the submit button to be visible in the Form, Validate it for button element JSON
multipleReceivers	object	Specifies a list of receivers who will receive the message. It can have the below optional properties: uids: A string array of UIDs of the existing users to be added as receivers. guids: A string array of GUIDs of the existing groups to be added as receivers. Failure to sending a message to a receiver does not result into create send message API failure. However, the individual message failure can be seen in the error objects in uids or guids. Maximum of 25 receivers(uids and guids combined) can be added for a single message.
tags	array of strings	(optional) Specifies a list of tags to be associated with certain users. Maximum of 25 tags can be associated with a single user.

Element List:

The following mentioned elements will come inside formFields key mentioned above:

1. LabelElement

{
    "elementType": "label",
    "elementId": "",
    "text": "Something to show" 
}

JSON Property	Type	Description
text	String	Required, text to be displayed in the label element

2. TextInputElement

{
    "elementType": "textInput",
    "elementId": "",
    "optional": false,
    "label": "name",
    "maxLines": 5, 
    "placeholder": {
        "text": "Enter digits"
    }
}

JSON Property	Type	Description	Default Value
optional	boolean	Optional, will be validated when doing the submission based on this	true

3. ButtonElement

{
    "elementType": "button",
    "elementId": "",
    "buttonText": "Press it", 
		"disableAfterInteracted": true
    "action": {
			"url" : ""
			"method": ""  
			"payload": payload; 
			"headers":"headers";
			"dataKey":"";  
      "type": "apiAction",
      "url": "https//abc.com", 
      "payload": "", 
      "headers": ""
    }
}

JSON Property	Type	Description	Default Value
buttonText	String	Required	false
disableAfterInteracted	boolean	optional	true
action	JSON	required, There can be four types of actions: 1. apiAction 2. urlNavigation 3. DeepLinking 4. customAction

a. apiAction

{
    "method": "",
    "payload": {},
    "headers": {},
    "dataKey": "",
    "actionType": "apiAction",
    "url": "https//abc.com"
}

JSON Property	Type	Description
url	String	Required,
method	String	required , can be one out of following: post, put , delete , patch
optional	Nested JSON Object	optional
Nested JSON Object	Nested JSON Object	optional
dataKey	String	optional
actionType	String	required

b. urlNavigation(both fields are mandatory)

{
    "url": "<VALID URL>",
    "actionType": "urlNavigation"
}

JSON Property	Type	Description	Default Value
url	String	Required,
actionType	String	required	urlNavigation

c. DeepLinking(both fields are mandatory)

{
    "url": "<VALID URL>",
    "actionType": "deepLinkAction"
}

JSON Property	Type	Description	Default Value
url	String	Required,
actionType	String	required	deepLinkAction

d. CustomAction (only actionType is mandatory):

{
    "actionType": "customAction"
}

4. CheckboxElement

{
    "elementType": "checkbox",
    "elementId": "",
    "optional": false,
    "label": "Select multiple",
    "defaultValue": [
        "",
        ""
    ],
    "options": [
        {
            "value": "option1",
            "label": "This is option 1"
        },
        {
            "value": "option1",
            "label": "This is option 1"
        }
    ]
}

JSON Property	Type	Description	Default Value
optional	boolean	optional,	true
label	String	required
defaultValue	Array of string	optional

5. DropdownElement/SpinnerElement(Android)

{
    "elementType": "dropdown",
    "elementId": "",
    "optional": true,
    "label": "Select multiple",
    "defaultValue": "option1", 
    "options": [
        {
            "value": "option1", 
            "label": "This is option 1" 
        },
        {
            "value": "option1", 
            "label": "This is option 1" 
        }
    ]
}

JSON Property	Type	Description	Default Value
optional	boolean	optional,	true
label	String	required
defaultValue	String	optional
options	Array of JSON	Required, every element in JSON should have a value and label as a required property

6. RadioButtonElement

{
    "elementType": "radio", 
    "elementId": "",
    "optional": false,
    "label": "Select multiple",
    "defaultValue": "option1",
    "options": [
        {
            "value": "option1",
            "label": "This is option 1"
        },
        {
            "value": "option2",
            "label": "This is option 1"
        }
    ]
}

JSON Property	Type	Description	Default Value
optional	boolean	optional,	true
label	String	required
defaultValue	String	optional
options	Array of JSON	Required, every element in JSON should have a value and label as a required property

7. SingleSelectElement

{
    "elementType": "singleSelect",
    "elementId": "",
    "optional": false,
    "label": "Select multiple", 
    "defaultValue": "option1",
    "options": [
        {
            "value": "option1", 
            "label": "This is option 1"
        },
        {
            "value": "option2", 
            "label": "This is option 1"
        }
    ]
}

JSON Property	Type	Description	Default Value
optional	boolean	optional,	true
label	String	required
defaultValue	String	optional
Required, every element in JSON should have a value and label as a required property	Array of JSON

8. DateTimeElement

{
          "elementType": "button",
          "elementId": "element9",
          "buttonText": "Navigate",
          "disableAfterInteracted": true,
          "action": {
            "actionType": "urlNavigation",
            "url": "https://www.cometchat.com"
          }
}

JSON Property	Type	Description	Default Value
elementType	String	required
elementId	String	required
optional	boolean	optional	true
label	String	required property
defaultValue	DateTime	optional
mode	enum	required, can be →date ,dateTime, time	“dateTime”
from	String	"2024-01-09T14:30", // for date : 2024-01-09 and for time: 14:30
to	int	"2024-01-09T14:30", // for date : 2024-01-09 and for time: 14:30
timezoneCode	string time zone code list	required

📘Properties and constraints: