Subscribe to only the message events that mention your app or bot
Compatibility: Events API
{
"type": "app_mention",
"user": "U061F7AUR",
"text": "<@U0LAN0Z89> is it everything a river should be?",
"ts": "1515449522.000016",
"channel": "C0LAN2Q65",
"event_ts": "1515449522000016"
}
This app event allows your app to subscribe to message events that directly mention your application or bot user.
Instead of receiving all messages in a channel and having to filter through them for those mentioning your app, as you would when subscribing to message.channels, you'll receive only the messages pertinent to your app.
Messages sent via this subscription arrive as an app_mention event, not as a message as with other message.* event types. However, your app can treat its contents similarly.
Messages sent to your app or bot in direct message conversations are not dispatched via app_mention, whether the app is explicitly mentioned or otherwise. Subscribe to message.im events to receive messages directed to your bot user in direct message conversations.
Workspace apps can't subscribe to this event type yet. Check out our changelog to stay in the loop.
app_mention events are just like other message events sent over the Events API, but their type indicates app_mention.
Whether your app is being sent a mention, has just been invited to a channel, or is receiving a typical mention: the format and shape is the same.
Nevertheless, here's a verbose collection of examples detailing each scenario, as delivered with full Events API envelopes.
When a user mentions your app in channels it is not yet party to, they have the opportunity to invite your app or send it the message as a kind of referral.
If the user decides to send your app a message instead of inviting it, you'll receive an event like this:
{
"token": "ZZZZZZWSxiZZZ2yIvs3peJ",
"team_id": "T061EG9R6",
"api_app_id": "A0MDYCDME",
"event": {
"type": "app_mention",
"user": "U061F7AUR",
"text": "What ever happened to <@U0LAN0Z89>?",
"ts": "1515449438.000011",
"channel": "C0LAN2Q65",
"event_ts": "1515449438000011"
},
"type": "event_callback",
"event_id": "Ev0MDYGDKJ",
"event_time": 1515449438000011,
"authed_users": [
"U0LAN0Z89"
]
}
Your app can't reply to it because it's not in the channel. Consider it for informational purposes only. To determine if your app or bot is part of a channel, use conversations.members or other approaches to monitoring channel memberships.
When your app is directly invited to a channel as a result of being mentioned, you'll receive that inciting message as an app_mention:
{
"token": "ZZZZZZWSxiZZZ2yIvs3peJ",
"team_id": "T061EG9R6",
"api_app_id": "A0MDYCDME",
"event": {
"type": "app_mention",
"user": "W021FGA1Z",
"text": "You can count on <@U0LAN0Z89> for an honorable mention.",
"ts": "1515449483.000108",
"channel": "C0LAN2Q65",
"event_ts": "1515449483000108"
},
"type": "event_callback",
"event_id": "Ev0MDYHUEL",
"event_time": 1515449483000108,
"authed_users": [
"U0LAN0Z89"
]
}
Just as before, you'll need to monitor your app's channel membership separately from this event. Consider subscribing to member_joined_channel events too.
Here's the happiest path: you're already part of a conversation and your app is mentioned. It can respond freely after receiving an event just like this (and remarkably similar to the other two we've reviewed):
{
"token": "ZZZZZZWSxiZZZ2yIvs3peJ",
"team_id": "T061EG9R6",
"api_app_id": "A0MDYCDME",
"event": {
"type": "app_mention",
"user": "U061F7AUR",
"text": "What is the hour of the pearl, <@U0LAN0Z89>?",
"ts": "1515449522.000016",
"channel": "C0LAN2Q65",
"event_ts": "1515449522000016"
},
"type": "event_callback",
"event_id": "Ev0LAN670R",
"event_time": 1515449522000016,
"authed_users": [
"U0LAN0Z89"
]
}
Subscribe to this event via the Events API.
Events of this type will be wrapped in metadata when sent via the Events API.
As an app event, subscriptions require no specific OAuth permission scope.
This event type is compatible only with the Events API.