POST /api/conversations

create a new conversation

Also see create a message in 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'117@socialcast.com"
  },
  "remark": {
    "text": "testing & bläh & stuff 2"
  }
}
201
{
  "conversation": {
    "id": 6,
    "name": null,
    "private": true,
    "members": [
      {
        "id": 131,
        "name": "J'øhn119 D'øe117",
        "email": "active'116@socialcast.com",
        "cell_phone": null,
        "office_phone": null,
        "first_name": "J'øhn119",
        "last_name": "D'øe117",
        "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": 132,
        "name": "J'øhn120 D'øe118",
        "email": "active'117@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
      }
    ],
    "latest_activity": {
      "id": 2,
      "verb": "post",
      "actor": {
        "id": 131,
        "displayName": "J'øhn119 D'øe117",
        "firstName": "J'øhn119",
        "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": 2,
        "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 2",
        "html_body": "<div class=\"markdown-body\"><p>testing &amp; bläh &amp; stuff 2</p></div>",
        "shared_message": null
      },
      "title": "J'øhn119 D'øe117 sent a chat message",
      "published": "2017-05-28T02:18:27-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'øhn120 D'øe118",
    "unread": false,
    "unread_count": 0
  }
}