Messenger

Messaging: discussions, messages, invites, unread counts, settings, and typing state.

Endpoints

Endpoint	Arguments	Returns
`messenger.discussion_links`	`ObjectId`	object[]
`messenger.find_user_discussion`	`ObjectId`	object
`messenger.get_unread_count`	`unknown`	object
`messenger.invite_users`	`ObjectId, unknown`	unknown
`messenger.join_event_discussion`	`ObjectId`	object
`messenger.leave_discussion`	`unknown, ObjectId`	object
`messenger.load_discussions`	`unknown, options`	object[] \| Record<string, object> \| object
`messenger.load_messages`	`ObjectId, options`	object[]
`messenger.save_discussion_settings`	`options`	unknown
`messenger.send`	`message, discussionId`	object
`messenger.set_discussion_last_seen`	`ObjectId`	unknown
`messenger.set_discussion_typing_state`	`ObjectId, unknown, unknown`	boolean

`messenger.discussion_links`

Description

List discussion links

Parameters

Argument 1 (ObjectId, required): discussionId

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.discussion_links', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
`uid`	string	yes	userId
`link`	string	yes	link
`date`	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
`messageText`	string	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.find_user_discussion`

Description

Find private discussion with user

Parameters

Argument 1 (ObjectId, required): withUid

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.find_user_discussion', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`created`	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
`uid`	ObjectId	yes
`participants`	ObjectId[]	yes
`subject`	string	no
`private`	boolean	no
`description`	string	no
`updated`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)
`cid`	ObjectId	no
`last_active`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)
`linked_activity`	ObjectId	no
`process`	ObjectId	no
`linked_tasklist`	ObjectId	no
`linked_event`	ObjectId	no
`last_seen`	object[]	no
`cover_picture`	ObjectId	no
`isStarred`	boolean	yes
`isMuted`	boolean	no
`members`	object[]	no
`moderators`	userId[]	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.get_unread_count`

Description

Get unread messages count for discussion

Response:

json

{
  "<discussionId-1>": 3
  "<discussionId-2>": 7
}

Parameters

Argument 1 (any \| ObjectId \| ObjectId[], optional):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.get_unread_count', [
  '...', // argument 1
]);
console.log(result);

Returns

Record<string, number>

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.invite_users`

Description

Invite users to discussion

Emits signal to participants discussion.updated({ discussion: ObjectId })

Parameters

Argument 1 (ObjectId, required): discussionId

Argument 2 (ObjectId[] \| ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.invite_users', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  ['507f1f77bcf86cd799439011'], // argument 2 (required)
]);
console.log(result);

Returns

Undocumented

The return value is not described in the source yet.

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.join_event_discussion`

Description

Join calendar event discussion

Parameters

Argument 1 (ObjectId, required):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.join_event_discussion', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes
`created`	timestamp	yes	Time (milliseconds since 1970-01-01 UTC)
`uid`	ObjectId	yes
`participants`	ObjectId[]	yes
`subject`	string	no
`private`	boolean	no
`description`	string	no
`updated`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)
`cid`	ObjectId	no
`last_active`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)
`linked_activity`	ObjectId	no
`process`	ObjectId	no
`linked_tasklist`	ObjectId	no
`linked_event`	ObjectId	no
`last_seen`	object[]	no
`cover_picture`	ObjectId	no
`isStarred`	boolean	yes
`isMuted`	boolean	no
`members`	object[]	no
`moderators`	userId[]	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.leave_discussion`

Description

Leave discussion

First argument may be a single discussion ID or an array of IDs. Single ID: void on success, throws on error (e.g. lone admin, ball holder must pass first). Array: runs leave logic per discussion (duplicate IDs are processed once), never throws on per-item failures, returning { left, skipped }. passToUserId is honored only on the single-ID path; in the array path, discussions where the caller holds the ball are skipped.

Parameters

Argument 1 (ObjectId \| ObjectId[], required):

Argument 2 (ObjectId, optional): passToUserId for single-discussion ball pass on leave

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.leave_discussion', [
  '507f1f77bcf86cd799439011', // argument 1 (required)
  '507f1f77bcf86cd799439011', // ObjectId
]);
console.log(result);

Returns

Field	Type	Required	Description
`left`	ObjectId[]	yes
`skipped`	ObjectId[]	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.load_discussions`

Description

Load discussions

json

{
  ...
  last_seen: { "userId": isoDateString }
}

Parameters

Argument 1 (ObjectId \| ObjectId[] \| any, optional):

Argument 2 (object, optional):

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.load_discussions', [
  '507f1f77bcf86cd799439011', // argument 1
  { /* ... */ },
]);
console.log(result);

Returns

object[] \| Record<string, object> \| object

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.load_messages`

Description

Load messages from discussion

Parameters

Argument 1 (ObjectId, required): discussionId

Argument 2 (object, optional):

Field	Type	Required	Description
`attachmentsOnly`	boolean	no
`filter`	string	no
`skip`	integer	no	Default: `0`.
`msg_id`	ObjectId \| ObjectId[]	no
`newest`	ObjectId	no
`limit`	integer	no

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.load_messages', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  {
    attachmentsOnly: false,
    filter: 'string',
  },
]);
console.log(result);

Returns

Result form 1:

Array of objects:

Field	Type	Required	Description
`_id`	ObjectId	yes	Message id
`created`	timestamp	yes	Timestamp of when the message was sent
`updated`	timestamp	no	Timestamp of when the message was last updated
`removed`	timestamp	no	Timestamp of when the message was deleted
`edited`	timestamp	no	Timestamp of when the message last edited
`loc`	object	no	Message location data
`from`	userId	no	Sender user id
`uid`	userId	no	Sender user id
`discussion`	discussionId	no	Discussion id
`type`	`user` \| `user.join` \| `user.leave` \| `activity.created` \| `activity.updated` \| `activity.removed` \| `linked.activity.created` \| `linked.activity.moved` \| `event.new` \| `event.updated` \| `event.removed` \| `event.going` \| `event.notgoing` \| `event.attend_response` \| `discussion.invites` \| `discussion.removesinvites` \| `meet.start` \| `meet.end` \| `ball.passed` \| `ball.passed_by` \| `ball.taken` \| `ball.cleared` \| `ball.auto_assigned` \| `collapsed`	no	Type of the message
`meta`	string[] \| object \| string	no	Meta data of the message
`msg`	string	no	The contents of the message
`files`	fileId[]	no	Attached files
`tagged`	object	no
`_metas`	object	no
`localIdentifier`	string	no
`replyTo`	ObjectId	no	Id of the reply message
`replyMessage`	object	no	Reply message
`reactions`	Record<string, string[]>	no	Message user reactions
`stars`	object[]	no
`isStarred`	boolean	no
`linkedData`	array	no
`scheduled`	boolean	no
`cid`	WorkspaceId	no	workspaceId (former networkId)
`deleteAt`	Date	no	Date after which the message should be automatically deleted (BSON Date for MongoDB TTL)
`forwardMessage`	object	no

Result form 2:

Field	Type	Required	Description
`_id`	ObjectId	yes	Message id
`created`	timestamp	yes	Timestamp of when the message was sent
`updated`	timestamp	no	Timestamp of when the message was last updated
`removed`	timestamp	no	Timestamp of when the message was deleted
`edited`	timestamp	no	Timestamp of when the message last edited
`loc`	object	no	Message location data
`from`	userId	no	Sender user id
`uid`	userId	no	Sender user id
`discussion`	discussionId	no	Discussion id
`type`	`user` \| `user.join` \| `user.leave` \| `activity.created` \| `activity.updated` \| `activity.removed` \| `linked.activity.created` \| `linked.activity.moved` \| `event.new` \| `event.updated` \| `event.removed` \| `event.going` \| `event.notgoing` \| `event.attend_response` \| `discussion.invites` \| `discussion.removesinvites` \| `meet.start` \| `meet.end` \| `ball.passed` \| `ball.passed_by` \| `ball.taken` \| `ball.cleared` \| `ball.auto_assigned` \| `collapsed`	no	Type of the message
`meta`	string[] \| object \| string	no	Meta data of the message
`msg`	string	no	The contents of the message
`files`	fileId[]	no	Attached files
`tagged`	object	no
`_metas`	object	no
`localIdentifier`	string	no
`replyTo`	ObjectId	no	Id of the reply message
`replyMessage`	object	no	Reply message
`reactions`	Record<string, string[]>	no	Message user reactions
`stars`	object[]	no
`isStarred`	boolean	no
`linkedData`	array	no
`scheduled`	boolean	no
`cid`	WorkspaceId	no	workspaceId (former networkId)
`deleteAt`	Date	no	Date after which the message should be automatically deleted (BSON Date for MongoDB TTL)
`forwardMessage`	object	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.save_discussion_settings`

Description

Set discussion details

Parameters

Argument 1 (object, optional):

Field	Type	Required	Description
`_id`	ObjectId	yes
`subject`	string	no
`participants`	ObjectId[]	no
`cover_picture`	ObjectId	no	Default: `null`.

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.save_discussion_settings', [
  {
    _id: '507f1f77bcf86cd799439011',
  },
]);
console.log(result);

Returns

Undocumented

The return value is not described in the source yet.

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.send`

Description

Send message

Send a message to a discussion

Emits signal messenger.new({ discussion, uid, msg_id, msg_type: "user" | "??" })

Parameters

Argument 1 (message, required):

Field	Type	Required	Description
`msg`	string	no
`subject`	string	no
`files`	fileId[]	no
`loc`	object	no	Default: `null`.
`participants`	userId[]	no	participants
`localIdentifier`	string	no	localIdentifier
`replyTo`	ObjectId	no	messageId
`forwardMessageId`	ObjectId	no	messageId
`replyPrivately`	boolean	no	Indicator that we are replying privately to forwarded message
`links`	array	no
`meta`	object	no	Optional metadata (e.g. AI context), max 50 keys
`scheduled`	boolean	no
`scheduleTime`	timestamp	no	Time (milliseconds since 1970-01-01 UTC)

Argument 2 (discussionId, optional): discussionId

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.send', [
  {
    msg: 'string',
    subject: 'string',
  },
  '507f1f77bcf86cd799439011', // discussionId
]);
console.log(result);

Returns

Field	Type	Required	Description
`_id`	ObjectId	yes	Message id
`created`	timestamp	yes	Timestamp of when the message was sent
`updated`	timestamp	no	Timestamp of when the message was last updated
`removed`	timestamp	no	Timestamp of when the message was deleted
`edited`	timestamp	no	Timestamp of when the message last edited
`loc`	object	no	Message location data
`from`	userId	no	Sender user id
`uid`	userId	no	Sender user id
`discussion`	discussionId	no	Discussion id
`type`	`user` \| `user.join` \| `user.leave` \| `activity.created` \| `activity.updated` \| `activity.removed` \| `linked.activity.created` \| `linked.activity.moved` \| `event.new` \| `event.updated` \| `event.removed` \| `event.going` \| `event.notgoing` \| `event.attend_response` \| `discussion.invites` \| `discussion.removesinvites` \| `meet.start` \| `meet.end` \| `ball.passed` \| `ball.passed_by` \| `ball.taken` \| `ball.cleared` \| `ball.auto_assigned` \| `collapsed`	no	Type of the message
`meta`	string[] \| object \| string	no	Meta data of the message
`msg`	string	no	The contents of the message
`tagged`	object	no
`_metas`	object	no
`localIdentifier`	string	no
`replyTo`	ObjectId	no	Id of the reply message
`replyMessage`	object	no	Reply message
`reactions`	Record<string, string[]>	no	Message user reactions
`stars`	object[]	no
`isStarred`	boolean	no
`linkedData`	array	no
`scheduled`	boolean	no
`cid`	WorkspaceId	no	workspaceId (former networkId)
`deleteAt`	Date	no	Date after which the message should be automatically deleted (BSON Date for MongoDB TTL)
`forwardMessage`	object	no
`files`	fileId[]	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.set_discussion_last_seen`

Description

Update discussion last seen to now

Parameters

Argument 1 (ObjectId, required): discussionId

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.set_discussion_last_seen', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
]);
console.log(result);

Returns

Undocumented

The return value is not described in the source yet.

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

`messenger.set_discussion_typing_state`

Description

Set user is typing state

Emits signal to participants discussion.typing({ discussion, typing, uid, statusText? })

Parameters

Argument 1 (ObjectId, required): discussionId

Argument 2 (boolean, required): typingState

Argument 3 (string, optional): statusText

Example

javascript

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('messenger.set_discussion_typing_state', [
  '507f1f77bcf86cd799439011', // ObjectId (required)
  false, // typingState (required)
  'string', // statusText
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

Endpoints

Legacy

V2

V3

Messenger

Endpoints

`messenger.discussion_links`

`messenger.find_user_discussion`

`messenger.get_unread_count`

`messenger.invite_users`

`messenger.join_event_discussion`

`messenger.leave_discussion`

`messenger.load_discussions`

`messenger.load_messages`

`messenger.save_discussion_settings`

`messenger.send`

`messenger.set_discussion_last_seen`

`messenger.set_discussion_typing_state`

Legacy

V2

V3

Messenger ​

Endpoints ​

messenger.discussion_links ​

messenger.find_user_discussion ​

messenger.get_unread_count ​

messenger.invite_users ​

messenger.join_event_discussion ​

messenger.leave_discussion ​

messenger.load_discussions ​

messenger.load_messages ​

messenger.save_discussion_settings ​

messenger.send ​

messenger.set_discussion_last_seen ​

messenger.set_discussion_typing_state ​

Messenger

Endpoints

`messenger.discussion_links`

`messenger.find_user_discussion`

`messenger.get_unread_count`

`messenger.invite_users`

`messenger.join_event_discussion`

`messenger.leave_discussion`

`messenger.load_discussions`

`messenger.load_messages`

`messenger.save_discussion_settings`

`messenger.send`

`messenger.set_discussion_last_seen`

`messenger.set_discussion_typing_state`