Conversation API

Users in the Minddistrict platform can engage in conversations. Conversations are a mix of text messages and optional video calls held between two or more participants. Since the conversation contents and functionality are very specific to the Minddistrict platform and likely sensitive in nature, this API will only provide limited metadata for the user’s conversations. This metadata should allow integrating applications (such as “client portals”) with just enough information on the user’s conversations to build up an “inbox”-like UI and to provide a link back to the Minddistrict platform for each conversation.

Discovering conversations

To discover the URLs for accessing the user’s conversations, send a GET request to the URL of a client and look for the @links metadata. (The client endpoint is a convenient central point for discovering all endpoints that are specific to a single user, so you’ll also see links that are not conversations-related). If the user has access, the following links will be available:

Description of the diary links discoverable via a client

Name in client @links

URL for

conversations

Listing metadata on all, or on the selected, conversations for this user.

If the user does not have access to the conversations these links will not be present in the client request response.

Note

While you can probably guess these URLs from their names, we recommend you use the discovery mechanism rather than concatenating strings to generate the URLs your application will access. We do not guarantee that the URL structure will be predictable (e.g. we may choose to serve some resources from different locations for performance reasons), but you can always trust the URLs reported in @links.

Retrieving conversations metadata

Retrieving conversation metadata requires batching parameters to be supplied:

Name

Value

Explanation

Value type

Notes

start

-

Integer

limit

-

Integer

Required
relevant

When present in the request, the endpoint will only return metadata for conversations that have current relevance. When this parameter is left out from the request, metadata for all conversations is returned.

Choice: ongoing call, missed call, unread messages or all

Listing conversations metadata:

GET /api/2/c/c4a1446b21674c82b9cde931b5be1b3e/conversations?limit=10&start=0 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtS8Ua9Pcla5dnUix2uJFPm0HT900z-5Y8-zrdwkYL8si-LAOjmPHwF-9ttGIQZ3emBV9IVe2F03-A7M1h0NTO4VrqQxdsKLhkJauBHDSaJk2un3c8_URGlF5EQ0Hu48G6ZVJhWNJum4hA7XLgzwl2kvbsPezsP7QdvWj91n227SGS4nGA-FmNuUhyE2462bOw2

The response will be the list of conversation metadata objects:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 1552
Content-Type: application/json;charset=UTF-8

{
    "@items": [
        {
            "@links": [],
            "@type": "http://ns.minddistrict.com/conversation/api",
            "@url": "https://customer.minddistrict.com/api/2/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/66fea069c9da4b3a9d30f7cc3a5abe7c",
            "has_call": false,
            "has_missed_call": false,
            "has_ongoing_call": false,
            "last_activity": "2021-03-31T06:48:50",
            "participants": [
                "Tina Turner"
            ],
            "subject": "Watching the news",
            "unread": 1,
            "url": "https://customer.minddistrict.com/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/66fea069c9da4b3a9d30f7cc3a5abe7c"
        },
        {
            "@links": [],
            "@type": "http://ns.minddistrict.com/conversation/api",
            "@url": "https://customer.minddistrict.com/api/2/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/c40b2f06d55440658d89075e9b2c01e9",
            "has_call": true,
            "has_missed_call": false,
            "has_ongoing_call": true,
            "last_activity": "2021-03-31T06:48:50",
            "participants": [
                "Tina Turner"
            ],
            "subject": "Face to face contact",
            "unread": 1,
            "url": "https://customer.minddistrict.com/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/c40b2f06d55440658d89075e9b2c01e9"
        }
    ],
    "@links": [],
    "@paging": {
        "found": 2,
        "limit": 10,
        "start": 0,
        "total": null
    }
}

Conversations metadata items

Conversation metadata items have the following properties:

Name

Value

Explanation

Value type

Notes

subject

Subject

-

String

last_activity

Last activity

-

Date with time

Required
unread

Number of unread messages

-

Integer

Required
has_call

This conversation has had one or more video calls.

Boolean

Required, Read-only
has_ongoing_call

This conversation has a video call right now.

Boolean

Required, Read-only
has_missed_call

This conversation had one or more video calls that the user didn’t pick up.

Boolean

Required, Read-only
url

Web accessible URL for the conversation

-

URL

Required
participants

Other conversation participants

-

List of string

The @type meta information for this object is: http://ns.minddistrict.com/conversation/api.

“Relevant” metadata

An example of using the relevant parameter is requesting metadata for conversations that have unread messages:

Listing conversations metadata with unread messages only:

GET /api/2/c/c4a1446b21674c82b9cde931b5be1b3e/conversations?relevant=unread%20messages&limit=10&start=0 HTTP/1.1
Host: customer.minddistrict.com
Accept: application/json
Authorization: md-token gAAAAABgZBtS8Ua9Pcla5dnUix2uJFPm0HT900z-5Y8-zrdwkYL8si-LAOjmPHwF-9ttGIQZ3emBV9IVe2F03-A7M1h0NTO4VrqQxdsKLhkJauBHDSaJk2un3c8_URGlF5EQ0Hu48G6ZVJhWNJum4hA7XLgzwl2kvbsPezsP7QdvWj91n227SGS4nGA-FmNuUhyE2462bOw2

The response will be the list of conversation metadata objects:

HTTP/1.0 200 Ok
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Content-Length: 850
Content-Type: application/json;charset=UTF-8

{
    "@items": [
        {
            "@links": [],
            "@type": "http://ns.minddistrict.com/conversation/api",
            "@url": "https://customer.minddistrict.com/api/2/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/66fea069c9da4b3a9d30f7cc3a5abe7c",
            "has_call": false,
            "has_missed_call": false,
            "has_ongoing_call": false,
            "last_activity": "2021-03-31T06:48:50",
            "participants": [
                "Tina Turner"
            ],
            "subject": "Watching the news",
            "unread": 1,
            "url": "https://customer.minddistrict.com/c/c4a1446b21674c82b9cde931b5be1b3e/conversations/66fea069c9da4b3a9d30f7cc3a5abe7c"
        }
    ],
    "@links": [],
    "@paging": {
        "found": 1,
        "limit": 10,
        "start": 0,
        "total": null
    }
}

Note

The relevant parameter has several possible values. ongoing call filters on those conversations that have a video call at the time of the metadata request. The missed call value will filter those conversations that have a video call where the user didn’t pick up the call and thus “missed” it. The unread messages value filters those conversations for which the user has one or more unread messages in the conversation. all selects all of those filter values; in other words it applies the combined effect of ongoing call, missed call and unread messages. Leaving out the parameter selects all conversations regardless of current “relevance”.