≡ messages.tags API
The messages.tags API allows to manage the user's message tags.
.. rst-class:: api-main-section
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
.. api-member:: :name: :permission:`messagesRead` :refid: messages-tags-permission-messages-read :refname: messagesRead Read your email messages.
.. api-member:: :name: :permission:`messagesTags` :refid: messages-tags-permission-messages-tags :refname: messagesTags Create, modify and delete message tags.
.. api-member:: :name: :permission:`messagesTagsList` :refid: messages-tags-permission-messages-tags-list :refname: messagesTagsList List message tags.
.. rst-class:: api-permission-info
Note
The permission messagesRead is required to use messenger.messages.tags.*.
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 121]
Creates a new message tag and returns the associated key. Tagging a message will store the tag's key in the user's message. Throws if the specified tag key is used already.
.. api-header::
:label: Parameters
.. _messages.tags.create.key:
.. api-member::
:name: [``key``]
:refid: messages-tags-create-key
:refname: key
:type: (string, optional)
Unique tag identifier (will be converted to lower case). Must not include :value:`()<>{/%*"` or spaces. Will be auto-generated if not provided.
.. _messages.tags.create.tag:
.. api-member::
:name: ``tag``
:refid: messages-tags-create-tag
:refname: tag
:type: (string)
Human-readable tag name.
.. _messages.tags.create.color:
.. api-member::
:name: ``color``
:refid: messages-tags-create-color
:refname: color
:type: (string)
Tag color in hex format (i.e.: :value:`#000080` for navy blue).
.. _messages.tags.create.callback:
.. api-member::
:name: [``callback``]
:refid: messages-tags-create-callback
:refname: callback
:type: (function, optional)
:annotation: -- [Added in TB 136]
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTags`
.. api-section-annotation-hack:: -- [Added in TB 121]
Deletes a message tag, removing it from the list of known tags. Its key will not be removed from tagged messages, but they will appear untagged. Recreating a deleted tag, will make all former tagged messages appear tagged again.
.. api-header::
:label: Parameters
.. _messages.tags.delete.key:
.. api-member::
:name: ``key``
:refid: messages-tags-delete-key
:refname: key
:type: (string)
Unique tag identifier (will be converted to lower case). Must not include :value:`()<>{/%*"` or spaces.
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTags`
.. api-section-annotation-hack:: -- [Added in TB 151]
Returns a message tag identified by its key.
.. api-header::
:label: Parameters
.. _messages.tags.get.key:
.. api-member::
:name: ``key``
:refid: messages-tags-get-key
:refname: key
:type: (string)
The key of the message tag to retrieve.
.. api-header::
:label: Return type (`Promise`_)
.. _messages.tags.get.returns:
.. api-member::
:refid: messages-tags-get-returns
:refname: _returns
:type: :ref:`messages.tags.^message^tag`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTagsList`
.. api-section-annotation-hack:: -- [Added in TB 121]
Returns a list of tags that can be set on messages, and their human-friendly name, colour, and sort order.
.. api-header::
:label: Return type (`Promise`_)
.. _messages.tags.list.returns:
.. api-member::
:refid: messages-tags-list-returns
:refname: _returns
:type: array of :ref:`messages.tags.^message^tag`
.. _Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTagsList`
.. api-section-annotation-hack:: -- [Added in TB 121]
Updates a message tag. Throws if the specified tag key does not exist.
.. api-header::
:label: Parameters
.. _messages.tags.update.key:
.. api-member::
:name: ``key``
:refid: messages-tags-update-key
:refname: key
:type: (string)
Unique tag identifier (will be converted to lower case). Must not include :value:`()<>{/%*"` or spaces.
.. _messages.tags.update.update^properties:
.. api-member::
:name: ``updateProperties``
:refid: messages-tags-update-update-properties
:refname: updateProperties
:type: (:ref:`messages.tags.^message^tag^properties`)
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTags`
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 136]
Fired when a new message tag has been created.
.. api-header::
:label: Parameters for onCreated.addListener(listener)
.. _messages.tags.on^created.listener(tag):
.. api-member::
:name: ``listener(tag)``
:refid: messages-tags-on-created-listener-tag
:refname: listener(tag)
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. _messages.tags.on^created.tag:
.. api-member::
:name: ``tag``
:refid: messages-tags-on-created-tag
:refname: tag
:type: (:ref:`messages.tags.^message^tag`)
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTagsList`
.. api-section-annotation-hack:: -- [Added in TB 136]
Fired when a message tag has been deleted.
.. api-header::
:label: Parameters for onDeleted.addListener(listener)
.. _messages.tags.on^deleted.listener(key):
.. api-member::
:name: ``listener(key)``
:refid: messages-tags-on-deleted-listener-key
:refname: listener(key)
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. _messages.tags.on^deleted.key:
.. api-member::
:name: ``key``
:refid: messages-tags-on-deleted-key
:refname: key
:type: (string)
Unique tag identifier of the deleted message tag.
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTagsList`
.. api-section-annotation-hack:: -- [Added in TB 136]
Fired when one or more properties of a message tag have been updated.
.. api-header::
:label: Parameters for onUpdated.addListener(listener)
.. _messages.tags.on^updated.listener(key, changed^properties, old^properties):
.. api-member::
:name: ``listener(key, changedProperties, oldProperties)``
:refid: messages-tags-on-updated-listener-key-changed-properties-old-properties
:refname: listener(key, changedProperties, oldProperties)
A function that will be called when this event occurs.
.. api-header::
:label: Parameters passed to the listener function
.. _messages.tags.on^updated.key:
.. api-member::
:name: ``key``
:refid: messages-tags-on-updated-key
:refname: key
:type: (string)
Unique tag identifier of the updated message tag.
.. _messages.tags.on^updated.changed^properties:
.. api-member::
:name: ``changedProperties``
:refid: messages-tags-on-updated-changed-properties
:refname: changedProperties
:type: (:ref:`messages.tags.^message^tag^properties`)
The changed message tag properties.
.. _messages.tags.on^updated.old^properties:
.. api-member::
:name: ``oldProperties``
:refid: messages-tags-on-updated-old-properties
:refname: oldProperties
:type: (:ref:`messages.tags.^message^tag^properties`)
The old values of the changed message tag properties.
.. api-header:: :label: Required permissions - :permission:`messagesRead` - :permission:`messagesTagsList`
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 121]
.. api-header::
:label: object
.. _messages.tags.^message^tag.color:
.. api-member::
:name: ``color``
:refid: messages-tags-message-tag-color
:refname: color
:type: (string)
Tag color in upper case hex format (i.e.: :value:`#000080` for navy blue).
.. _messages.tags.^message^tag.key:
.. api-member::
:name: ``key``
:refid: messages-tags-message-tag-key
:refname: key
:type: (string)
Unique tag identifier.
.. _messages.tags.^message^tag.ordinal:
.. api-member::
:name: ``ordinal``
:refid: messages-tags-message-tag-ordinal
:refname: ordinal
:type: (string)
A custom sort string.
.. _messages.tags.^message^tag.tag:
.. api-member::
:name: ``tag``
:refid: messages-tags-message-tag-tag
:refname: tag
:type: (string)
Human-readable tag name.
.. api-section-annotation-hack:: -- [Added in TB 136]
.. api-header::
:label: object
.. _messages.tags.^message^tag^properties.color:
.. api-member::
:name: [``color``]
:refid: messages-tags-message-tag-properties-color
:refname: color
:type: (string, optional)
Tag color in upper case hex format (i.e.: :value:`#000080` for navy blue).
.. _messages.tags.^message^tag^properties.ordinal:
.. api-member::
:name: [``ordinal``]
:refid: messages-tags-message-tag-properties-ordinal
:refname: ordinal
:type: (string, optional)
A custom sort string.
.. _messages.tags.^message^tag^properties.tag:
.. api-member::
:name: [``tag``]
:refid: messages-tags-message-tag-properties-tag
:refname: tag
:type: (string, optional)
Human-readable tag name.
.. api-section-annotation-hack:: -- [Added in TB 121]
Used for filtering messages by tag in various methods. Note that functions using this type may have a partial implementation.
.. api-header::
:label: object
.. _messages.tags.^tags^detail.mode:
.. api-member::
:name: ``mode``
:refid: messages-tags-tags-detail-mode
:refname: mode
:type: (`string`)
Whether :value:`all` of the tag filters must apply, :value:`any` of them, or :value:`none`. The :value:`none` mode ignores the provided filters and selects only messages without any tags.
Supported values:
.. _messages.tags.^tags^detail.mode.all:
.. api-member::
:name: :value:`all`
:refid: messages-tags-tags-detail-mode-all
:refname: all
.. _messages.tags.^tags^detail.mode.any:
.. api-member::
:name: :value:`any`
:refid: messages-tags-tags-detail-mode-any
:refname: any
.. _messages.tags.^tags^detail.mode.none:
.. api-member::
:name: :value:`none`
:refid: messages-tags-tags-detail-mode-none
:refname: none
:annotation: -- [Added in TB 148]
.. _messages.tags.^tags^detail.tags:
.. api-member::
:name: ``tags``
:refid: messages-tags-tags-detail-tags
:refname: tags
:type: (object)
A *dictionary object* with one or more filter condition as *key-value* pairs, the *key* being the tag to filter on, and the *value* being a boolean expression, requesting whether a message must include (:value:`true`) or exclude (:value:`false`) the tag. For a list of available tags, call the :ref:`messages.tags.list` method.