CreateChannel
Creates a channel to which you can add users and send messages.
Restriction: You can't change a channel's privacy.
Note
The x-amz-chime-bearer
request header is mandatory. Use the
ARN of the AppInstanceUser
or AppInstanceBot
that makes the API call as the value in
the header.
Request Syntax
POST /channels HTTP/1.1
x-amz-chime-bearer: ChimeBearer
Content-type: application/json
{
"AppInstanceArn": "string
",
"ChannelId": "string
",
"ClientRequestToken": "string
",
"ElasticChannelConfiguration": {
"MaximumSubChannels": number
,
"MinimumMembershipPercentage": number
,
"TargetMembershipsPerSubChannel": number
},
"ExpirationSettings": {
"ExpirationCriterion": "string
",
"ExpirationDays": number
},
"MemberArns": [ "string
" ],
"Metadata": "string
",
"Mode": "string
",
"ModeratorArns": [ "string
" ],
"Name": "string
",
"Privacy": "string
",
"Tags": [
{
"Key": "string
",
"Value": "string
"
}
]
}
URI Request Parameters
The request uses the following URI parameters.
- ChimeBearer
-
The ARN of the
AppInstanceUser
orAppInstanceBot
that makes the API call.Length Constraints: Minimum length of 5. Maximum length of 1600.
Pattern:
arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[^/].{0,1023}
Required: Yes
Request Body
The request accepts the following data in JSON format.
- AppInstanceArn
-
The ARN of the channel request.
Type: String
Length Constraints: Minimum length of 5. Maximum length of 1600.
Pattern:
arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[^/].{0,1023}
Required: Yes
- ChannelId
-
An ID for the channel being created. If you do not specify an ID, a UUID will be created for the channel.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
[A-Za-z0-9]([A-Za-z0-9\:\-\_\.\@]{0,62}[A-Za-z0-9])?
Required: No
- ClientRequestToken
-
The client token for the request. An
Idempotency
token.Type: String
Length Constraints: Minimum length of 2. Maximum length of 64.
Pattern:
[-_a-zA-Z0-9]*
Required: Yes
- ElasticChannelConfiguration
-
The attributes required to configure and create an elastic channel. An elastic channel can support a maximum of 1-million users, excluding moderators.
Type: ElasticChannelConfiguration object
Required: No
- ExpirationSettings
-
Settings that control the interval after which the channel is automatically deleted.
Type: ExpirationSettings object
Required: No
- MemberArns
-
The ARNs of the channel members in the request.
Type: Array of strings
Array Members: Minimum number of 1 item. Maximum number of 10 items.
Length Constraints: Minimum length of 5. Maximum length of 1600.
Pattern:
arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[^/].{0,1023}
Required: No
- Metadata
-
The metadata of the creation request. Limited to 1KB and UTF-8.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
Pattern:
.*
Required: No
- Mode
-
The channel mode:
UNRESTRICTED
orRESTRICTED
. Administrators, moderators, and channel members can add themselves and other members to unrestricted channels. Only administrators and moderators can add members to restricted channels.Type: String
Valid Values:
UNRESTRICTED | RESTRICTED
Required: No
- ModeratorArns
-
The ARNs of the channel moderators in the request.
Type: Array of strings
Array Members: Minimum number of 1 item. Maximum number of 10 items.
Length Constraints: Minimum length of 5. Maximum length of 1600.
Pattern:
arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[^/].{0,1023}
Required: No
- Name
-
The name of the channel.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern:
[\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFFFD\u10000-\u10FFFF]*
Required: Yes
- Privacy
-
The channel's privacy level:
PUBLIC
orPRIVATE
. Private channels aren't discoverable by users outside the channel. Public channels are discoverable by anyone in theAppInstance
.Type: String
Valid Values:
PUBLIC | PRIVATE
Required: No
- Tags
-
The tags for the creation request.
Type: Array of Tag objects
Array Members: Minimum number of 1 item. Maximum number of 50 items.
Required: No
Response Syntax
HTTP/1.1 201
Content-type: application/json
{
"ChannelArn": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 201 response.
The following data is returned in JSON format by the service.
- ChannelArn
-
The ARN of the channel.
Type: String
Length Constraints: Minimum length of 5. Maximum length of 1600.
Pattern:
arn:[a-z0-9-\.]{1,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[a-z0-9-\.]{0,63}:[^/].{0,1023}
Errors
For information about the errors that are common to all actions, see Common Errors.
- BadRequestException
-
The input parameters don't match the service's restrictions.
HTTP Status Code: 400
- ConflictException
-
The request could not be processed because of conflict in the current state of the resource.
HTTP Status Code: 409
- ForbiddenException
-
The client is permanently forbidden from making the request.
HTTP Status Code: 403
- ResourceLimitExceededException
-
The request exceeds the resource limit.
HTTP Status Code: 400
- ServiceFailureException
-
The service encountered an unexpected error.
HTTP Status Code: 500
- ServiceUnavailableException
-
The service is currently unavailable.
HTTP Status Code: 503
- ThrottledClientException
-
The client exceeded its request rate limit.
HTTP Status Code: 429
- UnauthorizedClientException
-
The client is not currently authorized to make the request.
HTTP Status Code: 401
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: