Conversations

Making a request

To make a successful request you must supply either a priority is_priority or a status. This enables efficent sorting and paging.
To see all conversations using the is_priority parameter, you can make successive queries with is_priority=true and is_priority=false
Using the status parameter will return all conversations with that status irrespective of their priority

Paging and Sorting

Links to the next and previous page of conversations will be provided within the response. next_page should be used to page through the results for your query.

warning: Using prev_page will page infinitely through conversations

  "paging": {
    "next_page": "https://api.conversocial.com/v1.1/conversations?sort=-oldest_sort_date&is_priority=false&oldest_sort_date_lte=2017-02-20T11%3A58%3A34&page_size=20&skip=1",
    "prev_page": https://api.conversocial.com/v1.1/conversations?sort=-oldest_sort_date&is_priority=false&oldest_sort_date_lte=2017-02-20T11%3A58%3A34&page_size=20&skip=1"
  }
}

Some sort must be applied to allow paging through results in a logicial order. If no sort is specified, sorting defaults to the oldest_sort_date field.
Paging through conversations is only possible when a single sort-field is specified. Consequently, requests that specify multiple sort fields will not produce links to a next or previous page.
The number of conversations returned in a page can be set using the page_size parameter. However, this is capped at 50, and specifying a page_size higher than this will not produce more results.

Side Loading

Side loading allows additional aspects to be requested along with the returned data. notes, actions and content can be loaded in this manner.
To see the content of the messages that make up a conversation you must include=content which will return an additional array of messages associated with the conversation or conversations in the request. To side-load multiple aspects, specify multiple include parameters e.g. ?include=content&include=notes

GET v1.1/conversations

Returns a list of Conversation objects optionally filtered by parameters
_{This resource supports additional data through the fields parameter}

Parameters

Label	Description	Values	Modifiers	Type	Required
is\_priority	Whether a conversation has been prioritised by the Conversocial priority engine. Must be supplied if _status_ is not	true, false	none	query string	false
status	The current Conversation status. Must be supplied if is\_priority is not	archived, on\_hold, closing, closed, pending\_approval, unread, assigned	none	query string	false
oldest\_sort\_date	Conversations whose _first_ message (the oldest message) falls between these dates. `oldest_sort_date` must be supplied as a pair. e.g v1.1/conversations?oldest\_sort\_date\_gte=2014-01-01&oldest\_sort\_date\_lte=2015-01-01 `oldest_sort_date` and `newest_sort_date` must be used exclusively	ISO date	gt, gte, lt, lte	query string	false
newest\_sort\_date	Conversations whose _last_ message (the most recent message) falls between these dates. `newest_sort_date` must be supplied as a pair e.g v1.1/conversations?newest\_sort\_date\_gte=2014-01-01&newest\_sort\_date\_lte=2015-01-01 `oldest_sort_date` and `newest_sort_date` must be used exclusively	ISO date	gt, gte, lt, lte	query string	false
channel	The unique __id__ of a channel to retrieve conversations for e.g v1.1/conversations?channels=65481	a [channel](channels/) _id_	none	query string	false
tag	Filter Conversations by the tag assigned to it e.g v1.1/conversations?tag=pop	a [tag](tags/) _name_	none	query string	false
contains\_private	Whether the conversations contain private messages, for instance Twitter DMs or Facebook messages e.g v1.1/conversations?contains\_private=true	true, false	none	query string	false
assigned\_to	Filter Conversations by the user assigned to that Conversation e.g v1.1/conversations?assigned\_to=7563	a [user](users/) _id_	none	query string	false
author	Filter Conversations by the Social Media author of the Conversation e.g v1.1/conversations?author=f:1231323492345234	an [author](authors/) _id_	none	query string	false
fields	Return additional data about the conversation e.g v1.1/conversations?fields=url,reports,id,channels	channels, status, tags, is_priority, contains_private, assigned_to, author, url, handling_times, tags, close_reason	none	query string	false
include	See [side Loading](#sideload) for more information e.g v1.1/conversations?include=content\&include=notes	actions, notes, content	none	query string	false

v1.1/conversations examples

Basic example

> curl -u username:password "https://api.conversocial.com/v1.1/conversations"

# Response
{
    "conversations": [
        {
            "id": "52d7d44e56c02c17e96fe8b8",
            "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
        },
        ...
    ],
    "paging": { ... }
}

Conversations with additional fields

> curl -u username:password "https://api.conversocial.com/v1.1/conversations?fields=status,is_priority,contains_private,tags,author,channels,assigned_to"

# Response
{
    "conversations": [
        {
            "id": "52d7d44e56c02c17e96fe8b8",
            "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
            "status": "assigned",
            "is_priority": false,
            "contains_private": false,
            "tags": [{
                "id": "2",
                "url": "https://api.conversocial.com/v1.1/tags/2",
            }],
            "author": {
                "id": "f:100003580627883",
                "url": "https://api.conversocial.com/v1.1/authors/f:100003580627883"
            },
            "channels": [{
                "id": "13",
                "url": "https://api.conversocial.com/v1.1/channels/13"
            }],
            "assigned_to": {
                "id": "1234",
                "url": "https://api.conversocial.com/v1.1/users/1234"
            },
        },
        ...
    ],
    "paging": { ... }
}

Conversations with side loaded aspects

> curl -u username:password "https://api.conversocial.com/v1.1/conversations?include=content&include=notes&include=actions"

# Response
{
    "conversations": [{
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
        "content_ids": [
            "52d8196956c02c6252bd91ac"
        ],
        "context_ids": [
            "52e644b6212fe60745d27bef",
        ],
        "unarchived_content_ids": [
            "52de6feeaf6670491b9a8d33",
            "52e644b6212fe60745d27bed",
        ]
    }],
    "content": [{
            "id": "52d8196956c02c6252bd91ac",
            "parent": "52d8196956c02c6252bd91a9",
            "type": "message"
            "platform": "facebook",
            "is_private": true,
            "is_priority": false,
            "created_date": "2013-11-18T11:20:24",
            "text": "Hello Mr Clownface. I like your tear.",
            "link": "http://www.facebook.com/315783141441/?sk=messages_inbox&action=read&tid=id.428313893934707",
            "tags": [{
                "id": "3893",
                "url": "https://api.conversocial.com/v1.1/tags/3893"
            }],
            "author": {
                "id": "f:1563548099",
                "url": "https://api.conversocial.com/v1.1/authors/f:100003580627883"
            },
            "channels": [{
                "id": "13",
                "url": "https://api.conversocial.com/v1.1/channels/13"
            }],
            "attachments": [{
                "description": null,
                "media": [{
                    "src": "https://fbcdn-sphotos-h-a.akamaihd.net/hphotos-ak-prn2/...1961121f",
                    "alt": null,
                    "href": "https://fbcdn-sphotos-h-a.akamaihd.net/hphotos-ak-prn2...61121f",
                    "type": null
                }],
                "caption": null,
                "href": "http://www.facebook.com/315783141441/?sk=messages_inbox&action=read&tid=id.428313893934707",
                "properties": [],
                "name": null
            }],
            "sentiment": {
                "created_date": "2014-01-22T10:13:03.387",
                "created_by": {
                    "id": "12479",
                    "url": "https://api.conversocial.com/v1.1/12479"
                },
                "value": 0
            },
        },
        {
            "id": "52de6feeaf6670491b9a8d33",
            ...
        }, {
            "id": "52e644b6212fe60745d27bed",
            ...
        }
    ]
}

GET v1.1/conversations/:id

Returns a specific conversation
_{This resource supports additional data through the fields parameter}

Parameters

Label	Description	Values	Modifiers	Type	Required
id	The unique __id__ of a conversation e.g v1.1/conversations/52d7d44e56c02c17e96fe8b8	conversation id	none	URL	true
fields	Return additional data about the conversation e.g v1.1/conversations/52d7d44e56c02c17e96fe8b8?fields=url,reports,id,channels	channels, status, tags, is_priority, contains_private, assigned_to, author, url, handling_times, tags, close_reason	none	query string	false
include	See side loading for more information e.g v1.1/conversations/52d7d44e56c02c17e96fe8b8?include=content	actions, notes, content	none	query string	false

v1.1/conversations/:id examples

Single Conversation

> curl -u username:password "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8"

# Response
{
    "conversation": {
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
    }
}

Single Conversation with additional fields

> curl -u username:password "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8?fields=channels,assigned_to"

# Response
{
    "conversation": {
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
        "status": "assigned",
        "is_priority": false,
        "contains_private": false,
        "tags": [{
            "id": "2",
            "url": "https://api.conversocial.com/v1.1/tags/2"
        }],
        "author": {
            "id": "f:100003580627883",
            "url": "https://api.conversocial.com/v1.1/authors/f:100003580627883"
        },
         "tags": [{
              "url": "https://api.conversocial.com/v1.1/tags/65602",
              "id": "65602",
              "name": "Valued Customer"
         }]
         "channels": [{
              "url": "https://api.conversocial.com/v1.1/channels/65602",
              "platform_id": "67282069",
              "id": "65602",
              "name": "Thief of time stores"
         }]
        "assigned_to": {
            "id": "1234",
            "url": "https://api.conversocial.com/v1.1/users/1234"
        },
    }
}

Single Conversation with side loaded aspect

> curl -u username:password "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8?include=content"

# Response
{
    "conversation": {
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.1/conversations/52d7d44e56c02c17e96fe8b8",
        "content_ids": [
            "566f3334c981b10a988cbb1a"
        ]
    },
    "content": [
        {
          "channels": [
            {
              "url": "https://api.conversocial.com/v1.1/channels/71589",
              "platform_id": "16560043",
              "id": "71589",
              "name": "@careprint"
            }
          ],
          "attachments": [],
          "parent": "52d7d44e56c02c17e96fe8b8",
          "tags": [],
          "is_priority": false,
          "text": "Thank you very much for your information. We will give you an update within 72 hours. Thank you so very much for your patience.",
          "author": {
            "url": "https://api.conversocial.com/v1.1/authors/t:16560043",
            "id": "t:16560043"
          },
          "sentiment": null,
          "platform_id": "676512738609373187",
          "platform": "twitter",
          "link": null,
          "user": {
            "url": "https://api.conversocial.com/v1.1/users/36616",
            "id": 36616,
            "email": "mrrobotooo@careprint.com"
          },
          "created_date": "2015-12-14T21:23:00.779",
          "is_by_source": true,
          "type": "tweet",
          "id": "566f3334c981b10a988cbb1a",
          "is_private": true
        },
    }
}

Twitter constraints

Due to Twitter API terms and guidelines, items of Twitter content are subject to certain restrictions:

The created_date field is set to a static date of 1970-01-01T00:00:00.
The link field is set to a static value of http://conversocial.com/#this-info-is-unavailable.
The text field is unavailable on items of Twitter content which are from non-source authors.

Outbound Twitter replies are not subject to these constraints as this content is generated via the Conversocial platform.

We have added two additional fields to Twitter content items to help adjust for the restrictions listed above:

An imported_date field is included in place of the created_date field. This is the date at which content was brought into the Conversocial platform.
An imported_delta field is included and represents the time difference in seconds between content creation and import into the Conversocial platform.

This does not apply to non-Twitter content.