SHIFT API

Messages

API routes for creating and managing messages.

API Reference

Expected JSON POST data:

param addressed_users: list of user ids addressed in message
type addressed_users: list uuid
param addressed_teams: list of team ids addressed in message
type addressed_teams: list uuid
param mentions: Mention information
type mentions: object
param text: Message body
type text: list str
param attachments: Attachment information
type attachments: object

Creates and returns a new message

Note: At least one addressed entity must be provided in the addressed_teams or addressed_users field, and only one team may be specified. Also, if a team is addressed, no users may be addressed. To include an Application Object as a mention, be sure to include the literal string {0} somewhere in the text parameter, which will be replaced with a link to the app object. The mentions parameter must contain the details of the mentioned object, for example:

  "mentions": [{
    "type": "appobject",
    "id": "object-id-here",
    "name": "App Object Name"
  }]

Currently, only one mentioned object per application message is supported on SHIFT. For more information on creating Application Objects, refer to the Application API section in this documentation.

Example 1

Create a message addressed to a team

POST /v1/messages

Request Body:

{
  "text": "Hello, this is a message", 
  "addressed_teams": [
    "8a7644a3-7393-417c-8180-0328749562a0"
  ], 
  "addressed_users": {
    "ids": [], 
    "emails": []
  }
}

JSON response body:

{
  "meta": {}, 
  "data": [
    {
      "addressed_users": [], 
      "attachments": [], 
      "resurface_html": false, 
      "text": "Hello, this is a message", 
      "unread_sidebar": false, 
      "updated_at": 1355247468.133, 
      "addressed_teams": [
        "8a7644a3-7393-417c-8180-0328749562a0"
      ], 
      "id": "cecf22e6-4617-42a9-a68d-d10ff0284311", 
      "subject": null, 
      "author": {
        "first_name": "Testy", 
        "last_name": "Testerson", 
        "relationship": 0, 
        "title": "", 
        "id": "a7ce7e43-0161-4757-ba18-d1800d233e3e", 
        "active": true, 
        "online": false, 
        "images": [], 
        "email": "test@grapheffect.com"
      }, 
      "muted": false, 
      "user_high_fived": false, 
      "sidebars": [], 
      "read": true, 
      "unread_reply": false, 
      "via_app": null, 
      "events": [], 
      "author_type": "user", 
      "tags": [
        "_inbox", 
        "_sent"
      ], 
      "is_muted": false, 
      "subscribed_to": true, 
      "num_high_fives": 0, 
      "user_replied_to_sidebar": false, 
      "num_replies": 0, 
      "created_at": 1355247468.133, 
      "user_replied": false, 
      "mentions": [], 
      "unread_since": null
    }
  ], 
  "time": 0.2297968864440918
}

Example 2

Attempt to create a message without text fails

POST /v1/messages

Request Body:

{
  "addressed_users": [
    "09dadecb-edbc-44c0-a187-1150e98e6df8"
  ]
}

JSON response body:

{
  "errors": [
    {
      "message": "text or attachments cannot be empty", 
      "code": 4004
    }
  ]
}