Docs
Tutorials
Developer Program
Your apps

Notifications Metadata

Notifications metadata is a way for apps to provide metadata about system events that are happening across apps and send it to Slack along with the messages they post into Slack.

Notification metadata can convert your unstructured messages to structured events that your customers can leverage to automate their work.

Sending Metadata to Slack along with Notifications

  1. Decide what metadata you want to associate with a message. For each event, you will need to include two keys at the top level event_type and a payload inside metadata. Within the payload you can define any custom property that you would like to include.

  2. Send a message to Slack with the new metadata parameter in chat.postMessage

    POST /api/chat.postMessage
    Authorization: Bearer xoxb-6050345600-60510457-…

{
    "channel": "C23456",
    "text": "New task Added by @sam - Redesign homepage",
    "metadata": {
        "event_type": "task_created",
        "event_payload": {
            "id": "TK-2132",
            "summary": "New issue with the display of mobile element",
            "description": "An end user has found a problem with the new mobile container for data entry. It was reproduced in the current version of IOS.",
            "priority": "HIGH",
            "resource_ type": "TASK"
        }
    }
}

Schema Design

Check out our Metadata Event Schema Design doc.

Consuming Metadata from Slack

While Slack users can leverage workflows to consume metadata, it’s also possible for an app to consume metadata programmatically without a workflow.

To begin with, metadata can be consumed along with message objects. Along with metadata, we’re also adding app_id in messages so that you can identify which app has sent that metadata. There are two ways to consume message objects:

  1. Events API: You can subscribe to message.* events. If a message has metadata associated with it, it will be available in the event payload.
{
    "event": {
        "type": "message",
        "channel": "C024BE91L",
        "user": "U2147483697",
        "text": "New task Added by @sam - Redesign homepage",
        "app_id": "A01234",
        "metadata": {
            "event_type": "task_added",
            "event_payload": {
                "id": "11223",
                "title": "Redesign homepage",
                "creator": "sam@acme-corp.com",
                "created_at": "1610561787",
                "priority": "high",
                "status": "triage"
            }
        },
        "ts": "1355517523.000005",
        "event_ts": "1355517523.000005",
        "channel_type": "channel"
    }
}
  1. Web API conversations.history: You can read metadata when you fetch a conversation’s history using conversations.history API. When calling the API you must pass in an additional parameter to receive back all the Metadata, include_all_metadata=true. This is how that call would look like:

Example Request

    GET /api/conversations.history?channel=C1234224&include_all_metadata=true
    HOST: slack.com
    Authorization: Bearer xoxb-16501860787-17163410960-...

Example Success Response:

{
    "ok": true,
    "messages": [{
            "type": "message",
            "user": "U012AB3CDE",
            "text": "New task Added by @sam - Redesign homepage",
            "app_id": "A01234",
            "metadata": {
                "event_type": "task_added",
                "event_payload": {
                    "id": "11223",
                    "title": "Redesign homepage",
                    "creator": "sam@acme-corp.com",
                    "created_at": "1610561787",
                    "priority": "high",
                    "status": "triage"
                }
            },
            "ts": "1512085950.000216"
        },
        {
            "type": "message",
            "user": "U061F7AUR",
            "text": "I'm going to start working on :point_up: task",
            "ts": "1512104434.000490"
        }
    ],
    "has_more": true,
    "pin_count": 0,
    "response_metadata": {
        "next_cursor": "bmV4dF90czoxNTEyMDg1ODYxMDAwNTQz"
    }
}
  1. Granular Metadata subscription via Events API

We are adding the ability within your Slack app setup to subscribe to specific events from specific apps. You will also have the ability to subscribe to a specific type of event for all apps that send Metadata.

Metadata Subscribe