Skip to content

Rich Text Messages

Chat Message Attachment Guide

Overview

Attachments provide an easy way to include rich or interactive content to a chat conversation. This may be for example buttons or images. Check the the detailed API reference for chat message attachments.

There are three types of attachments that can be send to chat conversation: "generic", "interaction" and "external". With generic attachments you are able to place images, buttons and links to chat messages. Interaction type is for embedding interaction created with Giosg Interaction Designer to chat conversation. External type is used for embedding iframe created outside of Giosg Interaction Designer to chat conversation.

Use cases

Next we will go through a few common use cases of chat message attachments step-by-step.

Chat message with interactive buttons

In this scenario, the user wants the visitor to give feedback from the conversation. The user limits the visitor's answer by providing specific chat buttons, which contain pre-defined texts and values. User has defined that only one button can be selected.

Example request sending a new chat message with button attachments

1
POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "message": "We would like to hear your feedback for this conversation.",
  "attachment_template": "generic",
  "attachments": [
    {
      "text": "Was this conversation helpful?",
      "actions": [
        {
          "text": "Yes",
          "type": "button",
          "value": "yes",
          "style": "success",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "Maybe",
          "type": "button",
          "value": "maybe",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "No",
          "type": "button",
          "value": "no",
          "style": "danger",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        }
      ]
    }
  ]
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
  "id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "type": "msg",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "user",
  "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
  "sender_public_name": "Customer Service",
  "sender_name": "John Smith",
  "message": "We would like to hear your feedback for this conversation.",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachment_template": "generic",
  "attachments": [
    {
      "id": "4ee16b6b-4b4d-11e7-9eaa-f45c89c72de3",
      "text": "Was this conversation helpful?",
      "actions": [
        {
          "id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
          "text": "Yes",
          "type": "button",
          "value": "yes",
          "style": "success",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "id": "68c9a17d-4ab3-11e7-a1c1-f45c89c72de3",
          "text": "Maybe",
          "type": "button",
          "value": "maybe",
          "style": "secondary",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "id": "70a8fb47-4ab3-11e7-b599-f45c89c72de3",
          "text": "No",
          "type": "button",
          "value": "no",
          "style": "danger",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        }
      ]
    }
  ]
}
  1. User and visitor have been chatting. After the chat the user wants feedback from the visitor.

  2. User defines three different buttons to measure customer service satisfaction.

  3. Create an attachment for a chat message.

  4. Send a chat message with the attachment.

  5. Chat message response object contains the attachment with a unique identifier id and the defined data with the actions.

  6. Visitor sees the buttons and selects one of them. In this scenario button: "Yes".

  7. A new chat message of type action is created.

  8. The text field of chosen action is returned in chat message's message field.
  9. The id of original chat message is returned in new chat message's response_to_message_id field.
  10. The value field of chosen action is returned in response_value field.
  11. The id of original chat message attachment is returned in new chat message's response_to_attachment_id field.
  12. Additional information about the chosen action is returned in response_to_action object field.
  13. Visitor sees a confirmation about the selection.
  14. The button that visitor selected is visually highlighted. All the buttons in the attachment, including the one that was selected, are disabled.
  15. By customizing the chat window styling, you may change the visual behavior when an action is selected. For example, you may hide all the non-selected buttons and just leave the selected button visible.
  16. Only one button was selected and then the buttons were disabled.

Example chat message response of selected button

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "Yes",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachment_template": null,
  "attachments": [],
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "4ee16b6b-4b4d-11e7-9eaa-f45c89c72de3",
  "response_to_attachment": {
    "id": "4ee16b6b-4b4d-11e7-9eaa-f45c89c72de3",
    "text": "Was this conversation helpful?",
    "title": null,
    "title_link_url": null,
    "image_url": null,
    "image_link_url": null,
    "link_target": null
  },
  "response_to_action_id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
  "response_to_action": {
    "id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
    "text": "Yes",
    "type": "button",
    "value": "yes",
    "style": "success",
    "is_disabled_on_selection": true,
    "is_disabled_on_visitor_message": false
  },
  "response_value": "yes",
  "response_text": null
}

Chat message with clickable image attachments

Visitor is asking for black Nike running shoes. The user gives the visitor links with images for three options.

Example request sending a new chat message with image attachments

1
POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "message": "I recommend these three options.",
  "attachment_template": "generic",
  "attachments": [
    {
      "title": "Nike Free RN",
      "text": "Women's running shoe, 100€",
      "image_url": "http://s3.amazon.com/fjifew932mlfs.png",
      "image_link_url": "http://running-shoes.com/nike-free-rn",
      "link_target": "_blank"
    },
    {
      "title": "Nike Air Zoom",
      "text": "Women's running shoe, 120€",
      "image_url": "http://s3.amazon.com/grmpemg345mgl.png",
      "image_link_url": "http://running-shoes.com/nike-air-zoom",
      "link_target": "_blank"
    },
    {
      "title": "Nike Air Max",
      "text": "Women's running shoe, 140€",
      "image_url": "http://s3.amazon.com/rn3940njdsnak.png",
      "image_link_url": "http://running-shoes.com/nike-air-max",
      "link_target": "_blank"
    }
  ]
}
  1. User and visitor are chatting in an online sports store. The visitor is asking for black Nike running shoes.

  2. User chooses three best options for visitor and sends message with image link attachments.

  3. Send a chat message with the attachments.

  4. Chat message response object contains the attachments with unique identifier ids and the defined data.

  5. Visitor sees the images and selects one of them. In this scenario link: "Nike Air Zoom".

  6. The visitor's choice is recorded to the chat conversation as a new chat message with type action.

  7. The URL of image_link_url is opened to a new tab for the visitor.
  8. Visitor may later also click other attachments, opening the linked web pages. These will also be recorded in the chat conversation.

Example chat message response of selected image

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "Women's running shoe, 100€",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachments": [],
  "attachment_template": null,
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
  "response_to_attachment": {
    "id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
    "title": "Nike Free RN",
    "text": "Women's running shoe, 100€",
    "image_url": "http://s3.amazon.com/fjifew932mlfs.png",
    "image_link_url": "http://running-shoes.com/nike-free-rn",
    "link_target": "_blank"
  },
  "response_to_action_id": null,
  "response_to_action": null,
  "response_value": "http://running-shoes.com/nike-free-rn",
  "response_text": null
}

Chat message with interaction attachment

Visitor is asking for more information about Nike running shoes. The user (or bot) gives the visitor interaction which contains basic information about Nike shoes so visitor doesn't need to find it from the site.

Example request sending a new chat message with interaction attachment

1
POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "message": "Nike running shoes",
  "attachment_template": "interaction",
  "attachments": [
    {
      "title": "Nike running shoe advanced features",
      "interaction_id": "d5a72d0e-9e4f-4818-b2da-4795ff77ca03",
      "parameters": {
        "initial_height": 150,
        "custom_param": true
      }
    }
  ]
}
  1. User and visitor are chatting in an online sports store. The visitor is asking for more information about Nike running shoes.

  2. User chooses to send interaction which describes advanced features of those shoes.

  3. Send a chat message with the attachments.

  4. Chat message response object contains the attachments with unique identifier ids and the defined data.

  5. Visitor sees the attachment and has possibility to request more information about one of the features of the shoes.

  6. The visitor's choice is recorded to the chat conversation as a new chat message with type action.

  7. Fields response_value and response_text can contain any string values when responding to interaction attachment.
  8. response_text is shown in the message history on operator chat window.

Example payload of visitor replying to interaction attachment

1
2
3
4
5
6
7
{
  "type": "action",
  "response_to_message_id": "fe87098f-8213-11e9-9872-f218983fece9",
  "response_to_attachment_id": "fe928428-8213-11e9-80b5-f218983fece9",
  "response_value": "insoles",
  "response_text": "See more information from advanced insole's."
}

Example chat message response to interaction attachment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachments": [],
  "attachment_template": null,
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
  "response_to_attachment": {
    "id": "52c39ca1-8134-11e9-af1c-f218983fece9",
    "interaction_id": "d5a72d0e-9e4f-4818-b2da-4795ff77ca03",
    "attachment_url": null,
    "parameters": {
      "initial_height": 150,
      "custom_param": true
    },
    "title": "Nike running shoe advanced features",
    "title_link_url": null,
    "text": null,
    "image_url": null,
    "image_link_url": null,
    "link_target": "_blank"
  },
  "response_to_action_id": null,
  "response_to_action": null,
  "response_value": "insoles",
  "response_text": "Visitor selected to see more information from advanced insole's."
}

Chat message with external attachment

Visitor is asking to see a list of the most popular Nike's running shoes. The user (or bot) gives the visitor an attachment with a product card carousel with different running shoes from Nike's online store.

Example request sending a new chat message with external attachment

1
POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "attachment_template": "external",
  "attachments": [
    {
      "attachment_url": "https://somewhere.com/my-interaction",
      "parameters": {
        "initial_height": 400,
        "custom_param": true
      },
      "text": "Shows the most popular running shoes",
      "title": "Shoes list"
    }
  ]
}
  1. User and visitor are chatting in an online sports store. The visitor is asking for a list of running shoes.

  2. User chooses to send interaction which shows a list of the most popular shoes.

  3. Send a chat message with the attachments.

  4. Chat message response object contains the attachments with unique identifier ids and the defined data.

  5. Visitor sees the attachment and has possibility to request more information about one of the of the shoes.

  6. The visitor's choice is sent by the attachment's embedded site to the chat conversation as a new chat message with type action.

  7. Fields response_value and response_text can contain any string values when responding to external attachment.
  8. response_text is shown in the message history on operator chat window.

Example payload of visitor replying to interaction attachment

1
2
3
4
5
6
7
{
  "type": "action",
  "response_to_message_id": "fe87098f-8213-11e9-9872-f218983fece9",
  "response_to_attachment_id": "fe928428-8213-11e9-80b5-f218983fece9",
  "response_value": "Shox R4",
  "response_text": "See more information about Nike Shox R4 shoes."
}

Example chat message response to external attachment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "attachments": [],
  "attachment_template": null,
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "57931251-4b4d-11e7-bf24-f45c89c72de3",
  "response_to_attachment": {
    "id": "52c39ca1-8134-11e9-af1c-f218983fece9",
    "interaction_id": null,
    "attachment_url": "https://somewhere.com/my-interaction",
    "parameters": {
      "initial_height": 400,
      "custom_param": true
    },
    "text": "Shows the most popular running shoes",
    "title": "Shoes list",
    "title_link_url": null,
    "image_url": null,
    "image_link_url": null,
    "link_target": "_blank"
  },
  "response_to_action_id": null,
  "response_to_action": null,
  "response_value": "Shox R4",
  "response_text": "See more information about Nike Shox R4 shoes."
}

Sending messages from external attachment to chat window

With external attachments, the embedded site can also send messages to the giosg chat. This is done using the window.parent.postMessage(message, targetOrigin) method. All messages need to start with EXTERNAL_ATTACHMENT#, followed by the actual message as a json string.

Example message: EXTERNAL_ATTACHMENT#{"type": "size", "height": 300}.

Supported messages are:

  1. Size. Allows you to set the height of the iframe that contains your attachment. Example: {"type": "size", "height": 300}.

  2. Exit. Allows you to hide the interaction from the chat. Example: {"type": "exit"}.

  3. Reply. Allows you to send an action reply message. This requires that you provide both value and text. Example: {"type": "reply", "text": "See more information about Nike Shox R4 shoes.", "value": "Shox R4"}