Getting user messages

User messages are organized in conversations - each storing all messages from user and venue staff.

Listing conversations

GET /communications/conversations/?filter[status]=open&filter[venue]=VENUE_ID&page[number]=1&page[size]=10&sort=-last_message_date

curl \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Accept: application/vnd.api+json" \
  "https://api.socialwifi.com/communications/conversations/?filter\[status\]=open&filter\[venue\]=VENUE_ID&page\[number\]=1&page\[size\]=10&sort=-last_message_date" \
  | jq

Core filters

You have to filter the list either by venue or by project:

Key	Example	Description
project	?filter[project]=22222222-2222-2222-2222-222222222222	List conversations for given project
venue	?filter[venue]=22222222-2222-2222-2222-222222222222	List conversations for given venue

Pagination filters

The list is paginated due to large amount of data it has to pull. If you want the full list you will have to go through multiple requests:

Key	Example
page[number]	page[number]=1
page[size]	page[size]=10

Do not use large page sizes or the endpoint will not return data in time.

Other filters

Key	Example	Description
status	?filter[status]=open	open/closed where closed are conversations archieved in client panel

Response

{
  "data": [
    {
      "type": "conversations",
      "id": "66eddbb7-5a1d-4f90-b005-d5e2c72fcbba",
      "attributes": {
        "abstract": "Hi! Thank you for free WiFi!",
        "author-email": "john.doe@example.com",
        "is-replied": false,
        "last-message-date": "2021-04-08T08:21:46.611915+00:00",
        "read": true,
        "author-name": "John Doe",
        "type": "contact_form_conversation",
        "status": "open",
        "date-started": "2018-08-25T22:11:11+00:00"
      },
      "relationships": {
        "messages": {
          "data": [
            {
              "type": "messages",
              "id": "8307d5cb-f0b9-40e3-9f4f-1af475e6abd7"
            },
          ]
        },
        "venue": {
          "data": {
            "type": "venues",
            "id": "22222222-2222-2222-2222-222222222222"
          }
        },
        "responder-messages": {
          "data": [
            {
              "type": "responder_messages",
              "id": "1b592d29-192b-49c1-b573-f29057095d81"
            },
          ]
        },
        "project": {
          "data": {
            "type": "projects",
            "id": "11111111-1111-1111-1111-111111111111"
          }
        }
      }
    },
    {
      "type": "conversations",
      "id": "be97002c-19d1-4108-beb2-b9c6e9adabe2",
      "attributes": {
        "abstract": "Hi, hi, how ae you?",
        "author-email": "john.doe@example.com",
        "is-replied": true,
        "last-message-date": "2018-08-24T22:11:12+00:00",
        "read": true,
        "author-name": "John Doe",
        "type": "contact_form_conversation",
        "status": "open",
        "date-started": "2018-08-24T22:11:11+00:00"
      },
      "relationships": {
        "messages": {
          "data": [
            {
              "type": "messages",
              "id": "e934f33c-46fc-4507-b7fc-2049fdda3ef7"
            }
          ]
        },
        "venue": {
          "data": {
            "type": "venues",
            "id": "22222222-2222-2222-2222-222222222222"
          }
        },
        "responder-messages": {
          "data": [
            {
              "type": "responder_messages",
              "id": "f2d0991f-1349-4a6b-924c-837954d8fa8a"
            }
          ]
        },
        "project": {
          "data": {
            "type": "projects",
            "id": "11111111-1111-1111-1111-111111111111"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.testing/conversations/?filter[status]=open&filter[venue]=22222222-2222-2222-2222-222222222222&filter[project]=11111111-1111-1111-1111-111111111111&page[size]=2&sort=-last_message_date&page[number]=1",
    "first": "http://api.testing/conversations/?filter[status]=open&filter[venue]=22222222-2222-2222-2222-222222222222&filter[project]=11111111-1111-1111-1111-111111111111&page[size]=2&sort=-last_message_date&page[number]=1",
    "previous": null,
    "next": "http://api.testing/conversations/?filter[status]=open&filter[venue]=22222222-2222-2222-2222-222222222222&filter[project]=11111111-1111-1111-1111-111111111111&page[size]=2&sort=-last_message_date&page[number]=2",
    "last": "http://api.testing/conversations/?filter[status]=open&filter[venue]=22222222-2222-2222-2222-222222222222&filter[project]=11111111-1111-1111-1111-111111111111&page[size]=2&sort=-last_message_date&page[number]=13"
  },
  "meta": {
    "count": 2
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Getting conversation messages

A conversation has messages - messages from the user and responder-messages - messages from venue staff.

To get conversation with all messages use the include filter:

GET /communications/conversations/CONVERSATION_ID/?include=messages%2Cresponder_messages

curl \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Accept: application/vnd.api+json" \
  https://api.socialwifi.com/communications/conversations/CONVERSATION_ID/?include=messages%2Cresponder_messages \
  | jq

Response

{
  "data": {
    "type": "conversations",
    "id": "b1178b91-247c-4518-b0c3-b6aec554c9b7",
    "attributes": {
      "abstract": "I have a problem with the TV in my room.",
      "author-email": "john.doe@example.com",
      "is-replied": true,
      "last-message-date": "2018-08-23T22:11:12+00:00",
      "read": true,
      "author-name": "John Doe",
      "type": "contact_form_conversation",
      "status": "open",
      "date-started": "2018-08-23T22:11:11+00:00"
    },
    "relationships": {
      "messages": {
        "data": [
          {
            "type": "messages",
            "id": "523f7361-d7a2-410e-8a6c-5af161b4edba"
          }
        ]
      },
      "venue": {
        "data": {
          "type": "venues",
          "id": "22222222-2222-2222-2222-222222222222"
        }
      },
      "responder-messages": {
        "data": [
          {
            "type": "responder_messages",
            "id": "d1fbbeae-6197-42bc-81f8-be5a49a85483"
          }
        ]
      },
      "project": {
        "data": {
          "type": "projects",
          "id": "11111111-1111-1111-1111-111111111111"
        }
      }
    }
  },
  "included": [
    {
      "type": "messages",
      "id": "523f7361-d7a2-410e-8a6c-5af161b4edba",
      "attributes": {
        "date-posted": "2018-08-23T22:11:11+00:00",
        "text": "I have a problem with the TV in my room.",
        "read": true,
        "date-of-reading": "2021-04-12T12:30:28.498004+00:00",
        "type": "message"
      },
      "relationships": {
        "conversation": {
          "data": {
            "type": "conversations",
            "id": "b1178b91-247c-4518-b0c3-b6aec554c9b7"
          }
        }
      }
    },
    {
      "type": "responder-messages",
      "id": "d1fbbeae-6197-42bc-81f8-be5a49a85483",
      "attributes": {
        "date-posted": "2018-08-23T22:11:12+00:00",
        "text": "We will fix it as soon as possible!",
        "read": false,
        "date-of-reading": null,
        "type": "responder_message"
      },
      "relationships": {
        "conversation": {
          "data": {
            "type": "conversations",
            "id": "b1178b91-247c-4518-b0c3-b6aec554c9b7"
          }
        },
        "account": {
          "data": {
            "type": "accounts",
            "id": "99999999-9999-9999-9999-999999999999"
          }
        }
      }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Conversations may have subtypes that indicate how they were created:

• contact-form-conversation: created by contact form widget on welcome page
• rating-conversation: created by adding a comment after rating a venue
• rating-request-conversation: created by venue staff requesting feedback to a feedback-less rating