Messages

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

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

📘

Properties and constraints:

  1. The maximum File size that can be uploaded per message is 100MB.
  2. For a group with more than 300 members, the conversations and unread message counts are not updated.
  3. Delivery and read receipts will be sent for a group of up to 300 online users.
  4. 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.
  5. 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.

ParametersTypeDescription
receiverstringSpecifies receiver of the message. Maximum length is 100 characters.

Allowed characters: alpha-dash (a-z, 0-9 with -and _ ) without spaces
receiverTypestringSpecifies the type of receiver of the message. Either user or group.
categorystringSpecifies the category of the message. The available categories are message and custom.
typestringSpecifies the type of the message. The available values are text, image, file, audio, video.
datanested objectSpecifies a JSON object to store up to 10K characters (JSON stringified data) for text,metadata,customData,attachments.
multipleReceiversobjectSpecifies 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:

ParametersTypeDescription
receiverstringSpecifies receiver of the message. Maximum length is 100 characters.

Allowed characters: alpha-dash (a-z, 0-9 with -and _ ) without spaces
receiverTypestringSpecifies the type of receiver of the message. Either user or group.
categorystringSpecifies the category of the message. The available category is interactive.
typestringSpecifies the type of the message. The available values are form, card and customInteractive for type interactive.
datanested objectSpecifies a JSON object to store up to 10K characters (JSON stringified data) for text,metadata,customData,attachments.
data.interactionGoalnested object(optional) Specifies a JSON Object which has two properties type and elementIds.
data.interactionGoal.typestringDefines 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.elementIdsArray of StringsDefines an array of element IDs which when mentioned help in achieving the goal based on the above types.
data.allowSenderInteractionsboolean(optional) If present, specifies if the interaction from sender will be allowed or not
data.interactiveDatanested objectSpecifies a JSON Object to add Interactive data.
data.interactiveData.titleStringSpecifies the title of the form.
data.interactiveData.textStringNote: required in case of type : card
data.interactiveData.goalCompletionTextStringoptional Specifies the goal completion text.
data.interactiveData.formFieldsnested 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.imageUrlStringoptional Would be considered in case of type: form
data.interactiveData.cardActionsJSON ArrayRequired, 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.submitElementJSON ArrayIf specified, it defines the submit button to be visible in the Form,

Validate it for button element JSON
multipleReceiversobjectSpecifies 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 PropertyTypeDescription
textStringRequired, text to be displayed in the label element

2. TextInputElement

{
    "elementType": "textInput",
    "elementId": "",
    "optional": false,
    "label": "name",
    "maxLines": 5, 
    "placeholder": {
        "text": "Enter digits"
    }
}
JSON PropertyTypeDescriptionDefault Value
optionalbooleanOptional, will be validated when doing the submission based on thistrue

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 PropertyTypeDescriptionDefault Value
buttonTextStringRequiredfalse
disableAfterInteractedbooleanoptionaltrue
actionJSONrequired, 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 PropertyTypeDescriptionDefault Value
urlStringRequired,
methodStringrequired ,
can be one out of following:
post, put , delete , patch
optionalNested JSON Objectoptional
Nested JSON ObjectNested JSON Objectoptional
dataKeyStringoptional
actionTypeStringrequired

b. urlNavigation(both fields are mandatory)

{
    "url": "<VALID URL>",
    "actionType": "urlNavigation"
}
JSON PropertyTypeDescriptionDefault Value
urlStringRequired,
actionTypeStringrequiredurlNavigation

c. DeepLinking(both fields are mandatory)

{
    "url": "<VALID URL>",
    "actionType": "deepLinkAction"
}
JSON PropertyTypeDescriptionDefault Value
urlStringRequired,
actionTypeStringrequireddeepLinkAction

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 PropertyTypeDescriptionDefault Value
optionalbooleanoptional,true
labelStringrequired
defaultValueArray of stringoptional

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 PropertyTypeDescriptionDefault Value
optionalbooleanoptional,true
labelStringrequired
defaultValueStringoptional
optionsArray of JSONRequired,
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 PropertyTypeDescriptionDefault Value
optionalbooleanoptional,true
labelStringrequired
defaultValueStringoptional
optionsArray of JSONRequired,
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 PropertyTypeDescriptionDefault Value
optionalbooleanoptional,true
labelStringrequired
defaultValueStringoptional
Required,
every element in JSON should have a value and label as a required property
Array of JSON

The following table lists the most common error codes that the Message API may return in case of an error:

CodeDescription
ERR_EMPTY_RECEIVER Indicates that the receiver cannot be empty.
ERR_INVALID_RECEIVER_TYPE Indicates that the invalid receiver type.
ERR_CONVERSATION_NOT_FOUND Indicates that the conversation id does not exists.
ERR_CONVERSATION_NOT_ACCESSIBLE Indicates that the conversation id not accessible to the user.

1. A user can access his own one-to-one conversations.
2. A user can access the group conversations if he is member of the group.
ERR_USER_MESSAGE_DELETE_FAILED Indicates that the API has failed to delete a one-to-one message.
ERR_MESSAGE_ID_NOT_FOUND Indicates that the message does not exist.
ERR_INVALID_MESSAGE_DATA Indicates invalid message body.
ERR_EMPTY_MESSAGE_TEXT Indicates empty messages text for a text message.
ERR_INVALID_MESSAGE_TEXT Indicates that the message text should be string.
ERR_EMPTY_MESSAGE_CATEGORY Indicates message category cannot be empty.
ERR_INVALID_MESSAGE_CATEGORY Indicates invalid message category.
ERR_EMPTY_MESSAGE_TYPE Indicates message type cannot be empty.
ERR_INVALID_MESSAGE_TYPE Indicates invalid message type.
ERR_EMPTY_MESSAGE_FILE Indicates empty FILE for the media message.
ERR_MESSAGE_NOT_A_SENDER Indicates that only sender can edit/delete the message.
ERR_MESSAGE_NO_ACCESS Indicates user does not have access to the message.

1. For one-to-one message user should either be sender or receiver of the message.
2. For group message user should be the member of the group.
ERR_MESSAGE_ACTION_NOT_ALLOWED Indicates that the message can not be edited or deleted. For example, Action messages cannot be edited or deleted by the API.
ERR_EMPTY_CUSTOM_DATA Indicates data.customData can not be empty for custom message.
ERR_INVALID_MEDIA_MESSAGE Indicates invalid media message.
ERR_INVALID_CUSTOM_DATA Indicates invalid data.customData. The customData should be valid JSON.
ERR_INVALID_METADATA Indicates invalid data.metadata. The metadata should be valid JSON.
ERR_WRONG_MESSAGE_THREAD Indicates conversation mismatch for parent and a new threaded message.
ERR_MESSAGE_THREAD_NESTING Indicates nested message threading.
ERR_WRONG_MESSAGE_THREAD_CATEGORY Indicates conversation mismatch for parent and a new threaded message.