Workplace from Meta is going away. You will be able to continue using Workplace until 31 August 2025. Visit our Help Center to find out more.
Overview
With custom integrations for Workplace, it's now possible to build powerful bots that can interact with people in groups and chat.
You can build a bot that automatically posts content into groups, responds to questions with extra information or takes action when mentioned in comments on a post. You can also build bots that can converse with people in Work Chat, providing information in real time, or handling requests with structured conversation elements like quick replies and persistent menus.
To build a bot for your community, you'll need a System Administrator admin role.
If you are not an admin of your Workplace community, you will need to work with an admin in order to build a bot.
Bots as Pages
On Workplace, similar to the Messenger platform, bots are represented as pages. A page is automatically created when you create a custom integration app. People in your Workplace community can discover and interact with your bot through this page
Bot pages are company-public, so any member of a Workplace community can see, tag, and message the bot. However, depending on the permission level you choose when creating your bot, it may not be able to see and interact with all of the content on Workplace.
For example, if your bot has the Read group content permission, it will be able to see content in groups. And if your bot doesn't have the Post to groups permission, it won't be able to reply to content in any group.
Additionally, people will only be able to find and message your bot in Work Chat if it has Message any member permission.
Bots in Groups
In groups, bots can do many of the things that people can do. This means you can build bots that post new content, comment on content with new information and like posts to indicate acknowledgement or approval.
Bots can also @mention people to get their attention, and be @mentioned to kick off a specific workflow or ask a question.
Lastly, bots can subscribe to group and @mention webhooks which provide the ability to monitor content and interact with users in flexible ways.
Bots in Chat
While in groups, bots are able to consume and share information across a group of people asynchronously, bots in chat are best for direct real-time interaction with a single person or defined group of people.
For instance, a chat bot can be used to send important reminders or notifications to someone based on an upcoming event like an interview or a meeting. Work chat bots can also be used to engage with a user in a conversation and take follow up action based on feedback received.
This interaction model is based on the same concepts used by the Messenger Platform. As a result, work chat bots can use features like persistent menus, quick replies, and templates to enrich the user experience.
Bot-to-User Chat
When a bot has the Message Any Member permission, it will be allowed to send a direct message any person on Workplace via their email address or their Workplace ID via the Messenger Send API.
The Message Any Member permission also allows your bot to show up in typeaheads in Workplace chat surfaces.
By subscribing for Page Message webhooks, your bot will also get notified when a user messages your bot, and you can build a conversation flow by combining sending and receiving.
Bot-to-Group Chat
When a bot has Message Any Member & Group Chat Bot permissions it can create, manage and be added to multi-person group chat threads. Bots can create new group threads by specifying a list of recipients, and can rename threads to create chat discussions on specific topics with specific people.
By enabling group chat support, your bot will show up in the Add people typeaheads in an existing group chat thread. It will then receive webhooks for each message sent by people in that thread, and can reply to that thread using its thread ID.
Creating new named threads
To create a new thread with specific recipients, make a POST request to the /me/messages endpoint specifying an array of recipient IDs and an initial message payload as follows:
POST /me/messages
{
"recipient": {
"ids": [<user_ids>]
},
"message": <message_payload>
}You'll get back a response payload that includes a thread ID, which you can use for follow-up messages.
If you use the same endpoint with the same list of recipients again, a new thread will be created. To send follow-up messages to an already-created thread, make a POST request to the /me/messages endpoint using the thread_id in the recipient payload, as follows:
POST /me/messages
{
"recipient": {
"thread_key": <thread_id>
},
"message": <message_payload>
}To rename a thread created by your bot, make a POST request to the /{thread}/threadname edge, as follows:
POST /t_<thread_id>/threadname
{
"name": "new name"
}Note the need to prefix the thread_id with "t_" in the edge path.
You can also add and remove participants from threads by issuing POST or DELETE requests on the /{thread}/participants edge as follows:
POST t_<thread_id>/participants
{
"to": [<user_ids>]
}
DELETE t_<thread_id>/participants
{
"to": [<user_ids>]
}Notice that operations on the /{thread}/participants edge are available for threads created by the integration.
Being mentioned on a thread
When your bot is mentioned on a message our webhooks will send the list of tagged members on that message, as the following payload:
{
"object":"page",
"entry":[{
"id":"746230239054322",
"time":1539281406974,
"messaging":[{
...
"message":{
"mid":"<message id>",
"seq":2192,
"text":"@Edu Gomes @Example Bot What's 2+2?"
},
"mentions":[{
"offset":0,
"length":10,
"id":"100017376437045"
},
{
"offset":11,
"length":12,
"id":"746230239054322"
}]
}]
}]
} Bot Platform Partners
Workplace has a number of bot platform partners who have built support for bots on Workplace. You can see a list of them here. You can use one of these platforms to build a powerful bot without writing a single line of code.
Best Practices
Use The Right Channel
When deciding whether to build group or chat interactions for your bot, it's worth considering where your bot will be most useful.
- If you're building a bot that several people might interact with at once, or a bot that posts content for several people to see, it makes sense to build a bot that posts into groups and responds to comments and mentions on posts in groups.
- If you're building a bot that needs to alert someone about something immediate, something that might require quick follow up, or something that people should interact with in private, you should support conversations in Work Chat for your bot.
A single app can handle both channels. There may be times when, for example, your helpdesk bot takes messages in work chat, and other times when it needs to post in groups and pick up the replies.
Deep linking to bots
Use the link format https://w.m.me/{page-id} to link directly to a chat bot on Workplace. Support is currently available on Workplace Chat when using web, Android and iOS. On mobile platforms where the Workplace Chat app is installed, the link will open directly in the app.
Referral Parameters
A Referral Parameter can also be used to incorporate further information into the link. This could, for example, enable the bot to perform custom actions based on which user the user has clicked to arrive at the bot.
To use the feature, use the link format https://w.m.me/{page-id}?ref={referral_parameter}. This feature is implemented in the same way as the Messenger Platform. Please see the Messenger documentation for details.
The relevant webhook field is messaging_referrals and requires a new subscription. This was previously not an available webhook field for Workplace apps but you’ll now be able to subscribe in the usual way.
The webhook payload is in the same format as Messenger, with the usual differences: Workplace uses app-scoped ids, not page scoped ids. Furthermore, Workplace also provides a community field in the webhook, carrying the community id.
Group Interactions
Once your app is subscribed for webhooks, your bot will get notified when it's mentioned in a group post or comment. It's important for your bot to respond to mentions in a timely fashion. If your bot has to process a request before replying, it's useful to like the comment, to indicate to the person that the bot knows it was mentioned.
Then if you're providing information after being mentioned in a comment, add a threaded reply to keep the rest of the group conversation flowing.
If your bot needs to provide info to the original poster, add a comment on the post itself, so they get notified too.
Chat Interactions
Bot interactions in Work Chat support similar functionality to the Messenger platform. This includes quick-reply buttons and templates that help you implement decision trees in bot conversations.
This makes it much simpler to build useful workflows and reduces the amount of typing people need to do, without the need for sophisticated natural language processing, which makes internationalisation much much simpler if you're building bots for a global workforce.