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.3/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.3/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.3/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.3/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.3/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.3/conversations?channels=65481		 a channel id none query string false
tag Filter Conversations by the tag assigned to it
e.g v1.3/conversations?tag=pop		 a tag name none query string false
contains_private Whether the conversations contain private messages, for instance Twitter DMs or Facebook messages
e.g v1.3/conversations?contains_private=true		 true, false none query string false
assigned_to Filter Conversations by the user assigned to that Conversation
e.g v1.3/conversations?assigned_to=7563		 a user id none query string false
author Filter Conversations by the Social Media author of the Conversation
e.g v1.3/conversations?author=f:1231323492345234		 an author id none query string false
fields Return additional data about the conversation
e.g v1.3/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 for more information
e.g v1.3/conversations?include=content\&include=notes		 actions, notes, content none query string false
queue_id Filter conversations by Queue ID
e.g v1.3/conversations?queue_id=abc123456		 a queue id value. You can specify this value more than once. none query string false

v1.3/conversations examples

Basic example

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

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

Conversations with additional fields

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

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

Conversations with side loaded aspects

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

# Response
{
    "conversations": [{
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.3/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,
            "imported_date": "2020-03-10T15:02:59.033",
            "imported_delta": 27,
            "created_date": "2020-03-10T15:02:32",
            "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.3/tags/3893"
            }],
            "author": {
                "id": "f:1563548099",
                "url": "https://api.conversocial.com/v1.3/authors/f:100003580627883"
            },
            "channels": [{
                "id": "13",
                "url": "https://api.conversocial.com/v1.3/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.3/12479"
                },
                "value": 0
            },
        },
        {
            "id": "52de6feeaf6670491b9a8d33",
            ...
        }, {
            "id": "52e644b6212fe60745d27bed",
            ...
        }
    ]
}

GET v1.3/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.3/conversations/52d7d44e56c02c17e96fe8b8		 conversation id none URL true
fields Return additional data about the conversation
e.g v1.3/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.3/conversations/52d7d44e56c02c17e96fe8b8?include=content		 actions, notes, content none query string false

v1.3/conversations/:id examples

Single Conversation

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

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

Single Conversation with additional fields

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

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

Single Conversation with side loaded aspect

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

# Response
{
    "conversation": {
        "id": "52d7d44e56c02c17e96fe8b8",
        "url": "https://api.conversocial.com/v1.3/conversations/52d7d44e56c02c17e96fe8b8",
        "content_ids": [
            "566f3334c981b10a988cbb1a"
        ]
    },
    "content": [
        {
            "channels": [
            {
                "url": "https://api.conversocial.com/v1.3/channels/71589",
                "platform_id": "16560043",
                "id": "71589",
                "name": "@careprint"
            }
            ],
            "imported_date": "2020-03-10T15:02:59.268",
            "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.3/authors/t:16560043",
            "id": "t:16560043"
            },
            "sentiment": null,
            "platform_id": "676512738609373187",
            "platform": "twitter",
            "link": null,
            "user": {
            "url": "https://api.conversocial.com/v1.3/users/36616",
            "id": 36616,
            "email": "mrrobotooo@careprint.com"
            },
            "created_date": "2020-03-10T15:02:02",
            "is_by_source": true,
            "imported_delta": 57,
            "type": "tweet",
            "id": "566f3334c981b10a988cbb1a",
            "is_private": true
        },
    }
}

PATCH v1.3/conversations/:id

This method allows for updating two Conversation attributes:

  • status
  • tag_ids

No other attributes can be updated through this API.

Note that in order to use this method, your API key MUST have full 'Manage Conversations' permissions for the conversation's Source.

Parameters

Label Description Values Modifiers Type Required
id The unique id of a conversation
e.g v1.3/conversations/52d7d44e56c02c17e96fe8b8		 conversation id none URL true
fields Return additional data about the conversation
e.g v1.3/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.3/conversations/52d7d44e56c02c17e96fe8b8?include=content		 actions, notes, content none query string false
status A new status for the conversation on_hold, closing none JSON request body true
tag_ids A list of active Tag IDs. Existing list of tags will be overwritten, not merged. Tags must already exist. tag ids none JSON request body true
close_reason A string representing the close reason. The Close Reason must already exist. string none JSON request body true

v1.3/conversations/:id/status examples

Put a Conversation 'On Hold' and set three Tags.

> curl -u username:password \
    -X PATCH \
    -H "Content-Type: application/json" \
    --data '{"status": "on_hold", "tags": [3, 345, 223]}' \
    "https://api.conversocial.com/v1.3/conversations/52d7d44e56c02c17e96fe8b8"

Response

200 OK

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

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.

This does not apply to non-Twitter content.

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