OpenAPI Specification
openapi: 3.1.0
info:
title: Sendbird Platform Channels Users API
description: The Sendbird Platform API provides server-side access to manage users, channels, messages, and moderation for in-app chat applications built on Sendbird. Supports group channels, open channels, direct messages, push notifications, and webhooks for real-time communication features.
version: 3.0.0
termsOfService: https://sendbird.com/terms-of-service/
contact:
name: Sendbird Support
url: https://sendbird.com/contact-us/
license:
name: Proprietary
url: https://sendbird.com/terms-of-service/
servers:
- url: https://api-{application_id}.sendbird.com/v3
description: Sendbird Platform API (replace {application_id} with your app ID)
variables:
application_id:
default: YOUR_APP_ID
description: Your Sendbird application ID
security:
- apiTokenAuth: []
tags:
- name: Users
description: Operations for managing Sendbird users.
paths:
/users:
get:
operationId: listUsers
summary: List Users
description: Retrieves a list of users registered in the Sendbird application. Supports pagination and filtering by nickname.
tags:
- Users
parameters:
- name: token
in: query
description: Pagination token for the next page.
schema:
type: string
- name: limit
in: query
description: Maximum number of users to return (1-100).
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: active_mode
in: query
description: Filter by user active mode.
schema:
type: string
enum:
- activated
- deactivated
- all
default: all
- name: show_bot
in: query
description: Whether to include bot users in results.
schema:
type: boolean
default: false
- name: user_ids
in: query
description: Comma-separated list of user IDs to filter.
schema:
type: string
- name: nickname
in: query
description: Filter users by nickname (partial match).
schema:
type: string
- name: nickname_startswith
in: query
description: Filter users whose nickname starts with this value.
schema:
type: string
responses:
'200':
description: A list of users.
content:
application/json:
schema:
type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
next:
type: string
description: Pagination token for the next page.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createUser
summary: Create a User
description: Creates a new user in the Sendbird application. The user_id must be unique within the application.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- user_id
- nickname
- profile_url
properties:
user_id:
type: string
description: Unique user ID.
nickname:
type: string
description: Display nickname of the user.
profile_url:
type: string
description: URL of the user profile image.
issue_access_token:
type: boolean
description: Whether to generate an access token for the user.
default: false
metadata:
type: object
description: Custom metadata key-value pairs.
additionalProperties:
type: string
responses:
'200':
description: User created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{user_id}:
get:
operationId: getUser
summary: Get a User
description: Retrieves information about a specific user.
tags:
- Users
parameters:
- $ref: '#/components/parameters/user_id'
responses:
'200':
description: User details.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
summary: Update a User
description: Updates information of a specific user.
tags:
- Users
parameters:
- $ref: '#/components/parameters/user_id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
nickname:
type: string
description: Updated nickname.
profile_url:
type: string
description: Updated profile image URL.
metadata:
type: object
description: Updated metadata.
additionalProperties:
type: string
responses:
'200':
description: User updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteUser
summary: Delete a User
description: Deletes a specific user from the Sendbird application.
tags:
- Users
parameters:
- $ref: '#/components/parameters/user_id'
responses:
'200':
description: User deleted successfully.
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
User:
type: object
properties:
user_id:
type: string
description: Unique identifier of the user.
nickname:
type: string
description: Display nickname.
profile_url:
type: string
description: Profile image URL.
is_online:
type: boolean
description: Whether the user is currently online.
is_active:
type: boolean
description: Whether the user account is active.
last_seen_at:
type: integer
description: Unix timestamp of last activity.
access_token:
type: string
description: Access token for the user (returned when issue_access_token is true).
metadata:
type: object
description: Custom metadata.
additionalProperties:
type: string
created_at:
type: integer
description: Unix timestamp when the user was created.
Error:
type: object
properties:
error:
type: boolean
description: Indicates an error occurred.
code:
type: integer
description: Sendbird error code.
message:
type: string
description: Human-readable error message.
parameters:
user_id:
name: user_id
in: path
required: true
description: Unique identifier of the user.
schema:
type: string
responses:
NotFound:
description: Not found. The requested resource does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Unauthorized. API token is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
apiTokenAuth:
type: apiKey
in: header
name: Api-Token
description: Sendbird API token obtained from the Sendbird Dashboard.