Sample - Slack Web API
POST/usergroups.create

Create a User Group

Creates a User Group for the current team. Supply a unique name, and optionally configure its mention handle, description, default channels, and user count behavior. The response returns the created User Group with its generated identity and configuration.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 5 body fields
tokenstringrequired
Authentication token with the `usergroups:write` scope.

Form-encoded User Group configuration; name identifies the new User Group.

channelsstringoptional
A comma separated string of encoded channel IDs for which the User Group uses as a default.
descriptionstringoptional
A short description of the User Group.
handlestringoptional
A mention handle. Must be unique among channels, users and User Groups.
include_countbooleanoptional
Include the number of users in each User Group.
namestringrequired
A name for the User Group. Must be unique among User Groups.

2 status codes
200Returns an object with `ok` set to true and a `usergroup` object containing the created User Group's identity, name, handle, description, and configuration.
okbooleanrequired
Allowed:true
usergroupobjectrequired
defaultReturns an error object with `ok` set to false and an `error` value describing why the User Group could not be created.
callstackstringoptional
Note: PHP callstack is only visible in dev/qa
errorstringrequired
Allowed:permission_deniednot_authedinvalid_authaccount_inactivetoken_revokedno_permissionorg_login_requireduser_is_botuser_is_restrictedinvalid_arg_nameinvalid_array_arginvalid_charset
okbooleanrequired
Allowed:false

Error handling

Supply token with the usergroups:write scope and provide name. The name must be unique among User Groups, and handle must be unique among channels, users, and User Groups.