POST /api/messages

create a new message

POST /api/streams/:stream_id/messages

create a new message for the specified stream

POST /api/external_systems/:external_system_id/messages

create a new external system message from an authorized admin user

Also see polls#create to create a poll for poll_id.

Success Response Code: 201

Params

Param name Description
external_system_id
optional

ID of the external system to create the message for


Value: Must be a Integer
message
optional

Value: Must be a Hash
message[body]
required

message's body


Value: Must be a String
message[url]
optional

external URL for this message


Value: Must be a String
message[attachment]
optional

file to attach to the message


Value: Must be a File
message[attachment_ids]
optional

array of existing attachment ids to attach to the message


Value: Must be an array of Integer
message[group_id]
optional

submit this message to a group


Value: Must be a Integer
message[player_url]
optional

embed a flash player hosted at this URL. If player_url is specified, thumbnail_url must also be specified


Value: Must be a String
message[thumbnail_url]
optional

display the image located at this URL before embedding the flash player


Value: Must be a String
message[player_params]
optional

pass these FlashVars to the embedded flash player


Value: Must be a String
message[shared_message_id]
optional

id of the message to be shared. Note that the message to be shared should have shareable=true in its API response


Value: Must be a Integer
message[poll_id]
optional

pass the ID of a poll to associate the poll with this message


Value: Must be a Integer

Response Fields

id id of the message Integer
user the user who created the message User
title message's title String
body message's body String
action text to construct a sentence from the title (e.g. "asked a question") String
verb text to construct a sentence with the user's name (e.g. "User thanked") String
message_type a description of the type of message posted (e.g. "status_message", "chat") String
icon url for the icon image for this message_type String
url url to interact with this message String
permalink_url message's permalink page String
external_url external URL for shared links, bookmarks, etc. String
created_at time the message was created DateTime
updated_at time the message was last updated DateTime
likes likes attached to this message Array<Like>
likes_count number of likes for this message Integer
commentable can the current user create comments on this message Boolean
comments comments attached to this message Array<Comment>
comments_count number of comments for this message Integer
external_resources url links associated with this message, which can include oembed data. Array<ExternalResource>
extensions extensions associated with this message, which can include group, thanks, challenges, project or town_hall data Array<Extension>
recipients users and groups that are @ mentioned, or groups that are referenced by group_id Array<User or Group>
shareable can this message be shared. There are some restrictions on which messages can be shared based on message type and visibility. See shared_message_id parameter for create Message and Remark Boolean
share_count number of times the message has been shared publicly Integer
shared_message shared message referenced by this message. Contains all Message response fields except likes, comments, shared_message Hash
client_provided_guid the client-provided unique identifier for the message, if any. Used for duplicate detection/post aggregation etc. String

Example Curl Commands

curl -X POST -v --basic -u "emily@socialcast.com:demo" "https://demo.socialcast.com/api/messages.json" -H "Content-Type: application/json" -d '{"message":{"body":"New message!"}}'
curl -X POST -v --basic -u "emily@socialcast.com:demo" "https://demo.socialcast.com/api/streams/239/messages.json" -H "Content-Type: application/json" -d '{"message":{"body":"New message!"}}'
curl -X POST -v --basic -u "admin@socialcast.com:adminpassword" "https://demo.socialcast.com/api/external_systems/1/messages.json" -H "Content-Type: application/json" -d '{"message":{"body":"New message!"}}'
#creating a poll for a message
curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/polls.json -H"Content-Type: application/json" -d'{"poll":{"question":"Hands up, who likes me?","poll_answers_attributes":{"1":{"answer":"YES!"},"2":{"answer":"You are OK"},"3":{"answer":"Absolutely not"}}}}'
#binding the created poll to a message
curl -X POST -v --basic -u "emily@socialcast.com:demo" https://demo.socialcast.com/api/messages.json -H "Content-Type: application/json" -d '{"message":{"poll_id":"5", "body":"creating a message with poll"}}'
curl -X POST -v --basic -u "emily@socialcast.com:demo" "https://demo.socialcast.com/api/messages.json" -F message[attachment]=@path/to/file
curl -X POST -v --basic -u "emily@socialcast.com:demo" "https://demo.socialcast.com/api/messages.json" -H "Content-Type: application/json" -d '{"message":{"attachment":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABMAAAASCAYAAAC5DOVpAAAAAXNSR0IArs4c6QAAAthJREFUOBGNVMtrE2EQ/+3m0byqSfqypg21pqaoxdSqFUFQqWgpKkXQgwgexJsV/wMvorcelILiwYMgeKm0IPRgxUuhtYpIC7aNStNXNDbppnltms3nfFt32aSKDizfb2Z+Mzs7M98KKJO+wXAHM7EBMBwpc/1TFYyMm0Oz18CER2SzGu3/i00ase9luJfwc3p0G/dVmEWcafGird6J5WQecqHIzX8UNfDW8Bc/A3tDDAtneR0WnKYEqXwBJ3e70dXiQZPHBr+7AnOrOXQHvchuKFjLKSVJRa4xVrxHh13zXD1Yi66AG3trnfDYzZqZsAVNbhtONLtxo3MnxJImAeLt4RkfY7isRxjAAfq0kbkEYukCValgcCqG1jqHyigUmYG5Cc0KM/VQbSV9ejIRRai+EvNSFvFMAa8+r8JpNWF+TUZEkjEfl/EpmkJ5PjNjLFT+igv7qnHI58LTySiuhOrg27Y53LNBj2q72FaFw34XHo+vIEMVa8J7VqMp/AzVu3C0sRISNdduMeuJuM9F1e3f4cRMLINmGsgpGo5RRNqrlNHQ5LWpamQti0b31nVr2F6Br/Gcymn+zdXiRYgsoin8XEluIJFVqOFFpGQFSbmgu/mO8YozeUarUaQKs7qPA6qMTRgt4wsSXocTCFQ5kKPgZx9+6O633yRMRdNo9zkwubSOkdm47uNANMv2UTpjRut7ItY4N/dr9mdGr258IYl1qnRPtQMcl4vYf6kxS9t/1+hI04Q+LqfxbnFdHf/kYgpfEznEUhsIr2Yx/T2NSEI2hnA8pO7wnRfT1lWbdYz+FB0ag+8VT8qlga6Rr9JG1UiqbrOIyFHPDCIxQWnXLwS/CYWiOEYEv4GkQ6tJQF7ZuvVEyDNB6H54PjCq3k0e0X8uuKSYzZ0QUDIQLdtfEkVRLB7niThPT8aVgZ5d0WgucIwJuE5qycpwv0EkQcB9WRZbH/QG9Zf/Ag14Go6USGO+AAAAAElFTkSuQmCC"}}'

Examples

POST 
{
  "message": {
    "title": "from mike"
  }
}
201
{
  "message": {
    "id": 18,
    "user": {
      "id": 46,
      "first_name": "J'øhn41",
      "last_name": "D'øe41",
      "name": "J'øhn41 D'øe41",
      "html_name": "J&#39;øhn41 D&#39;øe41",
      "url": "https://socialcast.socialcast.test/users/46-j%C3%B8hn41d%C3%B8e41",
      "avatars": {
        "is_system_default": true,
        "id": null,
        "square16": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square16-3b951350d61d203ece2fa5dd274fa7bd35275e132c17310d9006514f8839c857.png",
        "square30": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square30-6db66ac25c338d1e548a68465e2723ff63367c2aafbcc01db24c83964056b892.png",
        "square45": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square45-16865426333e244c59076d4f2475b711ed1ff9d12c97f4cf354f373a0170a1fd.png",
        "square70": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square70-1708999e8f1fea583408d7fc64b2177f853e4123bea2ffcf35f4839c8697e0ba.png",
        "square140": "https://socialcast.socialcast.test/assets-test/v6/avatars/default_user_square140-7da7e1d98b33ef152280b1f653cfd80e2db24b01b625a72abc320673eea5af53.png"
      },
      "username": "Jøhn41Døe41",
      "active": true,
      "terminated": false,
      "inactive": false,
      "role": "member",
      "type": "User",
      "title": null,
      "out_of_office": false,
      "out_of_office_on": null,
      "back_in_office_on": null,
      "company_login": null
    },
    "title": "from mike",
    "body": "",
    "html_body": "<div class=\"markdown-body\"></div>",
    "action": "",
    "verb": null,
    "message_type": "status_message",
    "icon": null,
    "url": "https://socialcast.socialcast.test/api/messages/18",
    "permalink_url": "https://socialcast.socialcast.test/messages/18",
    "external_url": null,
    "created_at": "2017-04-23T03:15:32+00:00",
    "updated_at": "2017-04-23T03:15:32+00:00",
    "attachments": [],
    "media_files": [],
    "contains_url_only": null,
    "external_resources": [],
    "tags": [],
    "last_interacted_at": 1492917332,
    "group": {},
    "category_id": null,
    "recipients": [],
    "thumbnail_url": null,
    "player_url": null,
    "player_params": null,
    "likable": false,
    "ratable": false,
    "rating": null,
    "ratings_average": null,
    "ratings_count": null,
    "editable": true,
    "deletable": true,
    "watchable": false,
    "watch": null,
    "flag": null,
    "source": {
      "name": "API",
      "url": "https://socialcast.socialcast.test/api",
      "formal_name": "Socialcast API",
      "id": "api"
    },
    "poll": null,
    "embed": null,
    "hidden": null,
    "subscribed": null,
    "groups": [],
    "extensions": [],
    "new_group_id": null,
    "new_group_archived_at": null,
    "days_of_stickiness": 0,
    "sticky_for_current_user": false,
    "shareable": false,
    "share_count": 0,
    "client_provided_guid": null,
    "comments_count": 0,
    "comments": [],
    "likes": [],
    "likes_count": 0,
    "shared_message": null,
    "commentable": true,
    "in_origin_stream": true
  }
}