NAV

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.

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

POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages
{
  "message": "We would like to hear your feedback for this conversation.",
  "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

{
  "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,
  "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.
    • Create an attachment for a chat message.
    • Send a chat message with the attachment.
    • Chat message response object contains the attachment with a unique identifier id and the defined data with the actions.
  3. Visitor sees the buttons and selects one of them. In this scenario button: “Yes”.
    • A new chat message of type action is created.
    • The text field of chosen action is returned in chat message’s message field.
    • The id of original chat message is returned in new chat message’s response_to_message_id field.
    • The value field of chosen action is returned in response_value field.
    • The id of original chat message attachment is returned in new chat message’s response_to_attachment_id field.
    • Additional information about the chosen action is returned in response_to_action object field.
    • Visitor sees a confirmation about the selection.
    • The button that visitor selected is visually highlighted. All the buttons in the attachment, including the one that was selected, are disabled.
    • 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.
    • Only one button was selected and then the buttons were disabled.

Example chat message response of selected button

{
  "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,
  "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"
}

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

POST https://service.giosg.com/api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages
{
  "message": "I recommend these three options.",
  "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. Visitor sees the images and selects one of them. In this scenario link: “Nike Air Zoom”.
    • The visitor’s choice is recorded to the chat conversation as a new chat message with type action.
    • The URL of image_link_url is opened to a new tab for the visitor.
    • 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

{
  "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": [],
  "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"
}