Managing tags

This section describes what tags are, which are available, and how to use them.

What are tags?

Tags are labels you can attach to and remove from conversations and messages. On the message level you can also specify to which participant(s) the tag applies to.

Currently you can use the following two tags:

• message_read (or read): To mark the message(s) as read and which participant(s) have read the message(s).
• no_reply_needed: To mark the conversation as no reply needed in case the conversation does not require any response from any participant.

Who sees what?

If you set up a tag, it shows up in your messaging interface only. This means that tags enable you to inform properties whether, for example, the message is already read by the property or that a conversation no longer requires a reply. To emphasise, the tags in this section do not show up on the guest side.

What can you do with tags?

You can either use the dedicated endpoints for each tag (attaching and removing), which we recommend, or use the configurable endpoint that enables you to set the tags up yourself.

→ To tag a conversation as no reply needed, see tagging a conversation as no reply needed.
→ To remove the no_reply_needed tag, see removing the no reply needed tag.
→ To tag messages as read, see tagging messages as read.
→ To remove the message_read tag, see removing the message read tag.

Retrieving tags

GET
https://supply-xml.booking.com/messaging/properties/{property_id}/tags

The GET /properties/{property_id}/tags request enables you to retrieve all the available tags, including information on how to use each.

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YZ/T6pHZy8K7wEoZsU9NOQYJDChBVgP4fH9Bq7NcY4SbU1Ag/EbPXntZYYnnn5lcHR/ew0pgz0pw"
    },
    "errors": [],
    "warnings": [],
    "data": {
        "tags": [
            {
                "usage": "internal, can only be retrieved with conversation",
                "tag": "pending_none",
                "description": "Conversation does not need a reply from any of the participants"
            },
            {
                "usage": " You can add this tag to and remove it from conversations using a dedicated endpoint. For more detailed information, see the documentation.",
                "description": "The conversation does not require a reply from any of the participants,",
                "tag": "no_reply_needed"
            },
            {
                "usage": "You can add this tag to and remove it from messages using a dedicated endpoint. For more detailed information, see the documentation.",
                "tag": "read",
                "description": "A participant has read the message."
            },
            {
                "tag": "delivered",
                "description": "Message has been delivered",
                "usage": "internal, can only be retrieved with conversation"
            },
            {
                "tag": "replied",
                "description": "Message has been replied to by participant",
                "usage": "internal, can only be retrieved with conversation"
            },
            {
                "usage": "internal, can only be retrieved with conversation",
                "tag": "pending_guest",
                "description": "Conversation needs reply from guest"
            },
            {
                "tag": "pending_property",
                "description": "Conversation needs reply from property",
                "usage": "internal, can only be retrieved with conversation"
            },
            {
                "usage": "internal, can only be retrieved with conversation",
                "description": "Message has been sent",
                "tag": "sent"
            }
        ]
    }
}

Response body elements

The following table describes the response elements:

Tagging a conversation as no reply needed

PUT https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags/no_reply_needed

The PUT /properties/{property_id}/conversations/{conversation_id}/tags/no_reply_needed request enables you to directly tag a conversation as no reply needed.

→ If you want to remove the tag, see removing the no reply needed tag.

Path parameters

The following table describes the path parameters you must add:

Response body example

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YaTyRj25f/2waH4F5BtL0NKrW3FqoZ+th18vbM/yHSuXx70j9WHWGVrI722rbVcB34S2muv+oaTK"
    },
    "data": {
        "tag": "no_reply_needed",
        "is_set": true
    },
    "warnings": [],
    "errors": []
}

Response body elements

The following table describes the response elements:

Removing the no reply needed tag

DELETE https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags/no_reply_needed

The DELETE /properties/{property_id}/conversations/{conversation_id}/tags/no_reply_needed request enables you to directly remove the no_reply_needed tag from a conversation.

Path parameters

The following table describes the path parameters you must add:

Response body example

The following is a successful request body example:

{
    "data": {
        "is_set": false,
        "tag": "no_reply_needed"
    },
    "errors": [],
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YSs/tamw9Yvt4Ue6PTNzksHMMKT/1d9rl+beop+69SW6Se44sharH3Qok1aomt4ONpSb4OkShiI+"
    }
}

Response body elements

The following table describes the response elements:

Tagging messages as read

PUT https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags/message_read

The PUT /properties/{property_id}/conversations/{conversation_id}/tags/message_read request enables you to directly tag one or multiple messages as read. You must also specify to which participant(s) the tag applies to.

→ If you want to remove a tag, see removing the message read tag.

Path parameters

The following table describes the path parameters you must add:

Request body parameters

The following table describes the request body parameters you must add:

Request body example

The following is a successful request body example:

{
    "message_ids": [ 
      "d5e90400-3010-11eb-b0d2-b1907cf0cc44"
    ],
    "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960"
  }

Response body example

The following is a successful response body example:

{
    "errors": [],
    "data": {
        "tag": "read",
        "is_set": true
    },
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY2a4pMH7yUf8vg+S0DYMTptupqdQtpH9gmRydqd9LlQyoTh4a1xUOva2lRmOngIZDrM612NZqlr"
    }
}

Response body elements

The following table describes the response elements:

Removing the message read tag

DELETE https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags/message_read

The DELETE /properties/{property_id}/conversations/{conversation_id}/tags/message_read request enables you to directly remove the message_read tag from one or more messages. You can also specify for which participants you want to remove the tag for.

Path parameters

The following table describes the path parameters you must add:

Request body parameters

The following table describes the request body parameters you must add:

Request body example

The following is a successful request body example:

{
    "message_ids": [ 
      "d5e90400-3010-11eb-b0d2-b1907cf0cc44"
    ],
    "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960"
  }

Response body example

The following is a successful response body example:

{
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY2a4pMH7yUf6VIaXx97zh7qxI5J14m0qku/3uEJSNjl9zFc9XMlCcAVCqvrlw5QIrbVQqzhbjQK"
    },
    "warnings": [],
    "data": {
        "tag": "read",
        "is_set": false
    }
}

Response body elements

The following table describes the response elements:

Setting tags

POST https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags

The POST /properties/{property_id}/conversations/{conversation_id}/tags request enables you to set tags to conversations, messages, or participants. You have to specify which tag you want to set.

To set the read tag, you must specify all request body parameters

To set the no_reply_needed tag, you must only specify the tag.

→ If you want to remove a tag, see removing tags.

Path parameters

The following table describes the path parameters you must add:

Request body parameters

The following table describes the request body parameters you can add:

Request body example

The following is a successful request body example:

{
    "message_ids": [ 
      "d5e90400-3010-11eb-b0d2-b1907cf0cc44"
    ],
    "tag": "read",
    "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960"
  }

Response body example

The following is a successful response body example:

{
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YbTDHm6UfFUcKbwM9glsIeb6pHvv53bkKkVjAIDhHaAvLg/faRlu70V14kUF8H32NGOPDGGi7Ber"
    },
    "warnings": [],
    "data": {
        "tag": "read",
        "is_set": true
    }
}

Response body elements

The following table describes the response elements:

The following table describes the request body parameters you must add:

Removing tags

DELETE https://supply-xml.booking.com/messaging/properties/{property_id}/conversations/{conversation_id}/tags

The DELETE /properties/{property_id}/conversations/{conversation_id}/tags request enables you to remove tags from conversations, messages, or participants. You have to specify which tag you want to remove.

To remove the read tag, you must specify all request body parameters

To remove the no_reply_needed tag, you must only specify the tag request body parameter.

Path parameters

The following table describes the path parameters you must add:

Request body parameters

The following table describes the request body parameters you must add:

Request body example

The following is a successful request body example:

{
    "message_ids": [ 
      "d5e90400-3010-11eb-b0d2-b1907cf0cc44"
    ],
    "tag": "no_reply_needed",
    "participant_id": "5fe782b1-6545-55b7-8b75-588945b5f960"
  }

Response body example

The following is a successful response body example:

{
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YbTDHm6UfFUcgE4kGgqDuWJehFUu8nCzbK7IDWS3x2ejUGodVbqheoMWzJnvG3nXc69gZBPY79wP"
    },
    "data": {
        "is_set": false,
        "tag": "no_reply_needed"
    },
    "warnings": []
}

Response body elements

The following table describes the response elements: