Conversations

GET /api/conversations/:id
retrieve a single conversation

Success Response Code: 200

Params

Param name Description
id
required

the id of the referenced conversation.


Value: Must be a Integer

Response Fields

id unique id for the conversation Integer
name the user entered custom name for the conversation String
title the user entered custom name for the conversation (see #name) *or* the server generated default conversation name String
private flag if the conversation is private (one-to-one) or a shareable conversation Boolean
unread flag if the current user has read the latest remark in the conversation Boolean
unread_count number of unread messages the user has in the conversation Integer
latest_activity latest_activity the latest remark/image posting activity in the conversation. See {ActivitiesController#show} for response definition Activity
members list of conversation members. See users#show for response definition Array<User>

Example Curl Commands

curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/2.json

Examples

GET 
200
{
  "conversation": {
    "id": 5,
    "name": null,
    "private": true,
    "members": [
      {
        "id": 132,
        "name": "J'øhn120 D'øe118",
        "email": "active'116@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn120",
        "last_name": "D'øe118",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      },
      {
        "id": 133,
        "name": "J'øhn121 D'øe119",
        "email": "active'117@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn121",
        "last_name": "D'øe119",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      }
    ],
    "avatar": {
      "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
      "width": 140,
      "height": 140,
      "is_system_default": true
    },
    "title": "J'øhn121 D'øe119",
    "unread": false,
    "unread_count": 0
  }
}

PUT /api/conversations/:id
update a conversation

Success Response Code: 200

Params

Param name Description
id
required

the id of the referenced conversation


Value: Must be a Integer
conversation
optional

Value: Must be a Hash
conversation[name]
optional

The name of the conversation


Value: Must be a String

Response Fields

id unique id for the conversation Integer
name the user entered custom name for the conversation String
title the user entered custom name for the conversation (see #name) *or* the server generated default conversation name String
private flag if the conversation is private (one-to-one) or a shareable conversation Boolean
unread flag if the current user has read the latest remark in the conversation Boolean
unread_count number of unread messages the user has in the conversation Integer
latest_activity latest_activity the latest remark/image posting activity in the conversation. See {ActivitiesController#show} for response definition Activity
members list of conversation members. See users#show for response definition Array<User>

Example Curl Commands

curl -X PUT -v --basic -H"Content-Type: application/json" -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/2.json -d'{"conversation":{"name":"New Name"}}'

Examples

PUT 
{
  "conversation": {
    "name": "testing"
  }
}
200
{
  "conversation": {
    "id": 7,
    "name": "testing",
    "private": false,
    "members": [
      {
        "id": 136,
        "name": "J'øhn124 D'øe122",
        "email": "active'120@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn124",
        "last_name": "D'øe122",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      },
      {
        "id": 137,
        "name": "J'øhn125 D'øe123",
        "email": "active'121@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn125",
        "last_name": "D'øe123",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      },
      {
        "id": 138,
        "name": "J'øhn126 D'øe124",
        "email": "active'122@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn126",
        "last_name": "D'øe124",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      }
    ],
    "avatar": {
      "url": "https://socialcast.socialcast.test/assets-test/default_conversation_square140-0a73b19cedcd1bd0830c6586d2ebe2ec1a6d5525fe34c4a017d2f09f97c751f5.png",
      "width": 140,
      "height": 140,
      "is_system_default": true
    },
    "title": "testing",
    "unread": false,
    "unread_count": 0
  }
}

GET /api/conversations
get a list of conversations that this user has access to

Success Response Code: 200

Params

Param name Description
unread
optional

only return unread conversations


Value: Must be one of: <code>true</code>, <code>false</code>.
hidden
optional

only return hidden conversationsk


Value: Must be one of: <code>true</code>, <code>false</code>.

Response Fields

conversations conversations array of Conversation results. See #show for response format Array<Conversation>

Example Curl Commands

curl -X GET -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations.json

Examples

GET 
200
{
  "conversations": [
    {
      "id": 5,
      "name": null,
      "private": true,
      "members": [
        {
          "id": 132,
          "name": "J'øhn120 D'øe118",
          "email": "active'116@socialcast.com",
          "cell_phone": null,
          "office_phone": null,
          "first_name": "J'øhn120",
          "last_name": "D'øe118",
          "profile_photo": {
            "height": 140,
            "width": 140,
            "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
            "is_system_default": true
          },
          "inactive": false,
          "terminated": false
        },
        {
          "id": 133,
          "name": "J'øhn121 D'øe119",
          "email": "active'117@socialcast.com",
          "cell_phone": null,
          "office_phone": null,
          "first_name": "J'øhn121",
          "last_name": "D'øe119",
          "profile_photo": {
            "height": 140,
            "width": 140,
            "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
            "is_system_default": true
          },
          "inactive": false,
          "terminated": false
        }
      ],
      "avatar": {
        "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
        "width": 140,
        "height": 140,
        "is_system_default": true
      },
      "title": "J'øhn121 D'øe119",
      "unread": false,
      "unread_count": 0
    }
  ]
}

POST /api/conversations
create a new conversation

Also see create a message in a conversation, add a member to a conversation, remove the authenticated user from a conversation and list the activities from a conversation.

A conversation has private set to true if there is only one other member, otherwise private will be false. If a previously created conversation has the same set of members, a new conversation will not be created. Instead, the remark will be appended to that conversation.

Success Response Code: 201

Params

Param name Description
remark
optional

Value: Must be a Hash
remark[text]
optional

The contents of the initial remark for the conversation


Value: Must be a String
conversation
optional

Value: Must be a Hash
conversation[name]
optional

a name for the conversation being created


Value: Must be a String
conversation[members_emails]
required

space separated list of email addresses to add to the conversation


Value: Must be a String

Response Fields

id unique id for the conversation Integer
name the user entered custom name for the conversation String
title the user entered custom name for the conversation (see #name) *or* the server generated default conversation name String
private flag if the conversation is private (one-to-one) or a shareable conversation Boolean
unread flag if the current user has read the latest remark in the conversation Boolean
unread_count number of unread messages the user has in the conversation Integer
latest_activity latest_activity the latest remark/image posting activity in the conversation. See {ActivitiesController#show} for response definition Activity
members list of conversation members. See users#show for response definition Array<User>

Example Curl Commands

curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations.json -H"Content-Type: application/json" -d'{"conversation":{"members_emails":"bob@socialcast.com jennifer@socialcast.com"},"remark":{"text":"Hi Jennifer and Bob"}}'

Examples

POST 
{
  "conversation": {
    "members_emails": "active'124@socialcast.com"
  },
  "remark": {
    "text": "testing & bläh & stuff 3"
  }
}
201
{
  "conversation": {
    "id": 9,
    "name": null,
    "private": true,
    "members": [
      {
        "id": 139,
        "name": "J'øhn127 D'øe125",
        "email": "active'123@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn127",
        "last_name": "D'øe125",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      },
      {
        "id": 140,
        "name": "J'øhn128 D'øe126",
        "email": "active'124@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn128",
        "last_name": "D'øe126",
        "profile_photo": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      }
    ],
    "latest_activity": {
      "id": 4,
      "verb": "post",
      "actor": {
        "id": 139,
        "displayName": "J'øhn127 D'øe125",
        "firstName": "J'øhn127",
        "image": {
          "height": 140,
          "width": 140,
          "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
          "is_system_default": true
        },
        "inactive": false,
        "terminated": false
      },
      "object": {
        "id": 3,
        "objectType": "note",
        "replied_to_id": null,
        "replied_to_type": null,
        "replied_to_message_id": null,
        "replied_to": null,
        "client_provided_guid": null,
        "content": "testing & bläh & stuff 3",
        "html_body": "<div class=\"markdown-body\"><p>testing &amp; bläh &amp; stuff 3</p></div>",
        "shared_message": null
      },
      "title": "J'øhn127 D'øe125 sent a chat message",
      "published": "2017-03-24T11:29:03-07:00"
    },
    "avatar": {
      "url": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png",
      "width": 140,
      "height": 140,
      "is_system_default": true
    },
    "title": "J'øhn128 D'øe126",
    "unread": false,
    "unread_count": 0
  }
}

POST /api/conversations/:id/acknowledge
Mark messages in a conversation as read

Success Response Code: 204

Params

Param name Description
id
required

the id of the referenced conversation


Value: Must be a Integer

Example Curl Commands

curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/2/acknowledge

POST /api/conversations/acknowledge_all
Mark all remarks in all of this user's conversations as read. This will clear the unread flag on all of their conversations

Success Response Code: 204

Example Curl Commands

curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/acknowledge_all

PUT /api/conversations/:id/hide
Hide a 1:1 conversation. This will hide a 1:1 conversation and remove it from the nav. The conversation will still be available under the hidden filter on the messages page.

Success Response Code: 200

Params

Param name Description
id
required

the id of the conversation to hide


Value: Must be a Integer

Example Curl Commands

curl -X PUT -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/2/hide

Examples

PUT 
{}
302
<html><body>You are being <a href="http://test.host/homepage">redirected</a>.</body></html>
PUT 
{}
302
<html><body>You are being <a href="http://test.host/homepage">redirected</a>.</body></html>

PUT /api/conversations/:id/unhide
This will unhide a 1:1 conversation for a specific user

Success Response Code: 200

Params

Param name Description
id
required

the id of the conversation to unhide


Value: Must be a Integer

Example Curl Commands

curl -X PUT -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/conversations/2/unhide

Examples

PUT 
{}
302
<html><body>You are being <a href="http://test.host/conversations/6/activities">redirected</a>.</body></html>