> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Creates a new user role

# Create

## Constraints

| Item             | Constraint                                   | Notes                                                       |
| ---------------- | -------------------------------------------- | ----------------------------------------------------------- |
| Role UID         | 100 characters, alpha-dash (a-z, 0-9, -, \_) | CometChat forces the UID to lowercase                       |
| Role name        | 100 characters (UTF8mb4)                     | Supports all languages and emojis                           |
| Role description | 255 characters (UTF8mb4)                     | Describe the role's purpose and permissions                 |
| Metadata         | No limit                                     | Store additional role configuration as JSON key-value pairs |


## OpenAPI

````yaml post /roles
openapi: 3.0.0
info:
  title: Chat APIs
  description: Manage messages, users, groups for a particular app using our Chat API.
  version: '3.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: API Keys
    description: The API keys are used to authorise the APIs
  - name: Roles
    description: The roles are used to give user access rights
  - name: Users
    description: The REST collection for users.
  - name: Auth Tokens
    description: The auth tokens are used to login end users using client SDKs.
  - name: Blocked Users
    description: The REST collections for blocked users.
  - name: Friends
    description: List,add and remove friends by passing UID in path variables
  - name: Groups
    description: The REST collections for groups.
  - name: Banned Users
    description: Ban and Unban user by passing other UID in path variables.
  - name: Group Members
    description: The REST collections for group members.
  - name: Messages
    description: The REST collections for messages.
  - name: Conversations
    description: The REST collections for conversations.
  - name: Restrict Features
    description: Allows Restricting Features
  - name: Metrics
    description: Allows accessing Data Metrics
  - name: Triggers
    description: Allows adding triggers to a webhook.
  - name: Webhooks
    description: Allows accessing Webhooks.
  - name: Notifications
    description: Allows configuring Notifications core.
paths:
  /roles:
    post:
      tags:
        - Roles
      summary: Create
      description: Creates a new user role
      operationId: create-role
      requestBody:
        content:
          application/json:
            schema:
              required:
                - role
                - name
              properties:
                role:
                  description: A unique identifier for the role.
                  type: string
                  default: ''
                name:
                  description: Friendly name of the role.
                  type: string
                  default: ''
                description:
                  description: Description of the role.
                  type: string
                  default: ''
                metadata:
                  description: Addition information about the role as JSON.
                  type: object
                settings:
                  description: >-
                    Role settings that is used for restricting list users/send
                    message. Possible values for listUsers & sendMessagesTo are
                    all and friendsOnly
                  type: object
              type: object
      responses:
        '200':
          description: Created a new Role
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                type: object
              example:
                data:
                  role: manager
                  name: manager
                  description: This role gives an update access
                  metadata:
                    email: managers@gmail.com
                  settings:
                    listUsers: all
                    sendMessagesTo: friendsOnly
                  createdAt: 1638343994
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````