Views: 9384
Last Modified: 23.03.2022

Gets list of recent chat messages

Revision Get current information about current API revision (platform version) – im.revision.get : 18

Attention: restCommand function is used here for illustration purposes only. It is taken from the EchoBot example. You can send a REST command with your own function, or use the BX24.callMethod or bitrix24-php-sdk methods.

Parameters

Parameter Example Required Description Revision
USER_ID 1 Yes Dialog ID. Format:
chatXXX – recipient chat, in case of chat message
or XXX – recipient ID, in case of private conversation
19
LAST_ID 28561624 No ID of the last loaded message 19
FIRST_ID 454322 No ID of the first loaded message 19
LIMIT 20 No Limiting of number of selected messages in dialog 19
  • If the LAST_ID and FIRST_ID keys were not passed, the last 20 chat messages will be loaded.
  • To load next 20 messages you must pass LAST_ID with the minimal message ID, received from the last selection.
  • If you need to load next 20 messages, you must pass FIRST_ID with the maximum message ID, received from the last selection.
  • If you need to load first 20 messages, you must pass FIRST_ID with the ID equal to '0'. You will receive the result with the very first message, available to you in this chat.

Attention! Due to potential significant volume of data, this method does not support standard Bitrix24 REST API page navigation.


Called method and response

JavaScript

BX24.callMethod('im.dialog.messages.get', {
	DIALOG_ID: 'chat29'
}, function(result){
	if(result.error())
	{
		console.error(result.error().ex);
	}
	else
	{
		console.log(result.data());
	}
});

PHP

$result = restCommand('im.dialog.messages.get', Array(
	'DIALOG_ID': 'chat29'
), $_REQUEST["auth"]);

Example of response

{
	"result": {
		"messages": [
		  {
			"id": 28561624,
			"chat_id": 29,
			"author_id": 1,
			"date": "2018-01-29T16:58:47+03:00",
			"text": "http://squirrel.com",
			"params": {
			  "URL_ID": [
				5
			  ],
			  "URL_ONLY": "Y",
			  "ATTACH": [
				{
				  "ID": "5",
				  "BLOCKS": [
					{
					  "RICH_LINK": [
						{
						  "NAME": "Squirrel",
						  "LINK": "http://squirrel.com",
						  "DESC": "Can find everything",
						  "PREVIEW": "https://yastatic.net/morda-logo/i/share-logo-ru.png"
						}
					  ]
					}
				  ],
				  "COLOR": "transparent"
				}
			  ]
			}
		  },
		  {
			"id": 28561623,
			"chat_id": 29,
			"author_id": 28,
			"date": "2018-01-29T16:43:38+03:00",
			"text": "",
			"params": {
			  "FILE_ID": [
				540
			  ]
			}
		  },
		  {
			"id": 28561622,
			"chat_id": 29,
			"author_id": 1,
			"date": "2018-01-29T16:43:12+03:00",
			"text": "Its operational :)",
			"params": {
			  "IS_EDITED": "Y"
			}
		  },
		  {
			"id": 28561618,
			"chat_id": 29,
			"author_id": 0,
			"date": "2018-01-25T15:15:22+03:00",
			"text": "John Harrington changed chat topic to \"The big chat\"",
			"params": null
		  },
		],
		"users": {
		  "1": {
			"id": 1,
			"name": "John Harrington",
			"first_name": "John",
			"last_name": "Harrington",
			"work_position": "",
			"color": "#df532d",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/1d3/100_100_2/Harrington.png",
			"gender": "M",
			"birthday": "",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": "2018-01-29T17:35:31+03:00",
			"mobile_last_date": false,
			"departments": [
			  50
			],
			"absent": false,
			"phones": {
			  "work_phone": "",
			  "personal_mobile": "",
			  "personal_phone": ""
			}
		  },
		  "28": {
			"id": 28,
			"name": "Chris Curtis",
			"first_name": "Chris",
			"last_name": "Curtis",
			"work_position": "manager",
			"color": "#728f7a",
			"avatar": "http://192.168.2.232/upload/resize_cache/main/8b8/100_100_2/26.jpg",
			"gender": "M",
			"birthday": "26-01",
			"extranet": false,
			"network": false,
			"bot": false,
			"connector": false,
			"external_auth_id": "default",
			"status": "online",
			"idle": false,
			"last_activity_date": false,
			"mobile_last_date": false,
			"departments": [
			  58
			],
			"absent": false,
			"phones": {
			  "work_phone": "8 (97643) 4590-563-2318",
			  "personal_mobile": "8 (33741) 1578-234-8853",
			  "personal_phone": ""
			}
		  },
		},
		"files": {
			"540": {
				"id": 540,
				"chatId": 29,
				"date": "2018-01-29T16:43:39+03:00",
				"type": "image",
				"preview": "",
				"name": "1176297_698081120237288_696773366_n.jpeg",
				"size": 55013,
				"image": {
					"width": 960,
					"height": 640
				},
				"status": "done",
				"progress": 100,
				"authorId": 1,
				"authorName": "John Harrington",
				"urlPreview": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/show.file.php?fileId=540&preview=Y&fileName=1176297_698081120237288_696773366_n.jpeg",
				"urlShow": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/show.file.php?fileId=540&fileName=1176297_698081120237288_696773366_n.jpeg",
				"urlDownload": "http://192.168.2.232/bitrix/components/bitrix/im.messenger/download.file.php?fileId=540"
			}
		},
		"chat_id": 29
	}
}    

Description of keys:

  • messages – array of messages:

    • id – message ID
    • chat_id – chat ID
    • author_id – author of messages (0 - for system message)
    • date – date of the message in ATOM format
    • text – message text
    • params – message parameters, parameter object, if parameters are not passed null (main types are described below)
  • users – user data description objects:

    • id – user ID
    • name – user first and last name
    • first_name – user name
    • last_name – user last name
    • work_position – position
    • color – user color in 'hex' format
    • avatar – avatar link (if empty, then avatar is not specified)
    • gender – user gender
    • birthday – user birthday in DD-MM format, if empty – not specified
    • extranet – extranet user attribute (true/false)
    • network – Bitrix24.Network user attribute (true/false)
    • bot – bot attribute (true/false)
    • connector – Open Channels user attribute (true/false)
    • external_auth_id – external authorization code
    • status – selected user status
    • idle – idle date when user is not using his/her PC, in ATOM format (if not specified, false)
    • last_activity_date – date of the last user action, in ATOM format
    • mobile_last_date – date of the last action inside mobile app, in ATOM format (if not specified, false)
    • absent – date, to which the user has a leave of absence, in ATOM format (if not specified, false)
  • files – object, describing files in selected messages:

    • id – file ID
    • chatId – chat ID
    • date – date when file is modified
    • type – file type: image – image, file – file
    • name – name of loaded file
    • size – actual size of image in bytes
    • image – actual image size in px
    • width – width in px
    • height – height in px
    • status – current status: done – loaded, upload – loading in progress
    • progress – loading progress percentage: 100 – loaded, -1 – current status unavailable
    • authorId – ID of the user who loaded an object
    • authorName – first and last name of user who loaded an object
    • urlPreview – link to image preview (available fro images)
    • urlShow – link to switch to object in "show" mode
    • urlDownload – link to start the download
  • chat_id – chat ID

Description of additional parameters:

  • ATTACH – object containing rich formatting
  • KEYBOARD – object containing keyboard description
  • IS_DELETED – flag that specifies message deleting
  • IS_EDITED – flag that specifies that message is edited
  • FILE_ID – array of file IDs
  • LIKE – array of user IDs. Those user 'liked' the message

Examples of response when error occurs

{
    "error": "DIALOG_ID_EMPTY",
    "error_description": "Dialog ID can't be empty"
}

Description of keys:

  • error – error code
  • error_description – brief description of error

Possible error codes

Code Description
DIALOG_ID_EMPTY Dialog ID not passed
ACCESS_ERROR Current user does not have appropriate permissions to access the dialog



Courses developed by Bitrix24