API Reference¶
This section describes API commands of ejabberd 24.10. If you are using an old ejabberd release, please refer to the corresponding archived version of this page in the Archive. The commands that changed in this version are marked with 🟤.
abort_delete_old_mam_messages¶
added in 22.05
Abort currently running delete old MAM messages operation
Arguments:
- host :: string : Name of host where operation should be aborted
Result:
- status :: string : Status text
Module: mod_mam
Examples:
abort_delete_old_messages¶
added in 22.05
Abort currently running delete old offline messages operation
Arguments:
- host :: string : Name of host where operation should be aborted
Result:
- status :: string : Status text
Examples:
add_rosteritem¶
updated in 24.02
Add an item to a user's roster (supports ODBC)
Arguments:
- localuser :: string : User name
- localhost :: string : Server name
- user :: string : Contact user name
- host :: string : Contact server name
- nick :: string : Nickname
- groups :: [group::string] : Groups
- subs :: string : Subscription
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_admin_extra
Examples:
POST /api/add_rosteritem
{
"localuser": "user1",
"localhost": "myserver.com",
"user": "user2",
"host": "myserver.com",
"nick": "User 2",
"groups": [
"Friends",
"Team 1"
],
"subs": "both"
}
HTTP/1.1 200 OK
""
backup¶
Backup the Mnesia database to a binary file
Arguments:
- file :: string : Full path for the destination backup file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
ban_account¶
improved in 24.06
Ban an account
This command kicks the account sessions, sets a random password, and stores ban details in the account private storage. This command requires mod_private to be enabled. Check also get_ban_details API and _unban_account
_ API.
Arguments:
- user :: string : User name to ban
- host :: string : Server name
- reason :: string : Reason for banning user
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_admin_extra
Examples:
POST /api/ban_account
{
"user": "attacker",
"host": "myserver.com",
"reason": "Spaming other users"
}
HTTP/1.1 200 OK
""
bookmarks_to_pep¶
Export private XML storage bookmarks to PEP
Arguments:
- user :: string : Username
- host :: string : Server
Result:
- res :: string : Raw result string
Tags: private
Module: mod_private
Examples:
POST /api/bookmarks_to_pep
{
"user": "bob",
"host": "example.com"
}
HTTP/1.1 200 OK
"Bookmarks exported"
change_password¶
Change the password of an account
Arguments:
- user :: string : User name
- host :: string : Server name
- newpass :: string : New password for user
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: accounts
Module: mod_admin_extra
Examples:
POST /api/change_password
{
"user": "peter",
"host": "myserver.com",
"newpass": "blank"
}
HTTP/1.1 200 OK
""
change_room_option¶
Change an option in a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
- option :: string : Option name
- value :: string : Value to assign
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/change_room_option
{
"name": "room1",
"service": "conference.example.com",
"option": "members_only",
"value": "true"
}
HTTP/1.1 200 OK
""
check_account¶
Check if an account exists or not
Arguments:
- user :: string : User name to check
- host :: string : Server to check
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: accounts
Module: mod_admin_extra
Examples:
check_password¶
Check if a password is correct
Arguments:
- user :: string : User name to check
- host :: string : Server to check
- password :: string : Password to check
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: accounts
Module: mod_admin_extra
Examples:
POST /api/check_password
{
"user": "peter",
"host": "myserver.com",
"password": "secret"
}
HTTP/1.1 200 OK
""
check_password_hash¶
Check if the password hash is correct
Allows hash methods from the Erlang/OTP crypto application.
Arguments:
- user :: string : User name to check
- host :: string : Server to check
- passwordhash :: string : Password's hash value
- hashmethod :: string : Name of hash method
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: accounts
Module: mod_admin_extra
Examples:
POST /api/check_password_hash
{
"user": "peter",
"host": "myserver.com",
"passwordhash": "5ebe2294ecd0e0f08eab7690d2a6ee69",
"hashmethod": "md5"
}
HTTP/1.1 200 OK
""
clear_cache¶
Clear database cache on all nodes
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
compile¶
Recompile and reload Erlang source code file
Arguments:
- file :: string : Filename of erlang source file to compile
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: erlang
Module: mod_admin_extra
Examples:
connected_users¶
List all established sessions
Arguments:
Result:
- connected_users :: [sessions::string] : List of users sessions
Tags: session
Examples:
connected_users_info¶
List all established sessions and their information
Arguments:
Result:
- connected_users_info :: [{jid::string, connection::string, ip::string, port::integer, priority::integer, node::string, uptime::integer, status::string, resource::string, statustext::string}]
Tags: session
Module: mod_admin_extra
Examples:
POST /api/connected_users_info
{
}
HTTP/1.1 200 OK
[
{
"jid": "user1@myserver.com/tka",
"connection": "c2s",
"ip": "127.0.0.1",
"port": 42656,
"priority": 8,
"node": "ejabberd@localhost",
"uptime": 231,
"status": "dnd",
"resource": "tka",
"statustext": ""
}
]
connected_users_number¶
Get the number of established sessions
Arguments:
Result:
- num_sessions :: integer
Tags: session, statistics
Examples:
connected_users_vhost¶
Get the list of established sessions in a vhost
Arguments:
- host :: string : Server name
Result:
- connected_users_vhost :: [sessions::string]
Tags: session
Module: mod_admin_extra
Examples:
POST /api/connected_users_vhost
{
"host": "myexample.com"
}
HTTP/1.1 200 OK
[
"user1@myserver.com/tka",
"user2@localhost/tka"
]
convert_to_scram¶
Convert the passwords of users to SCRAM
Arguments:
- host :: string : Vhost which users' passwords will be scrammed
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: sql
Examples:
convert_to_yaml¶
Convert the input file from Erlang to YAML format
Arguments:
- in :: string : Full path to the original configuration file
- out :: string : And full path to final file
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: config
Examples:
POST /api/convert_to_yaml
{
"in": "/etc/ejabberd/ejabberd.cfg",
"out": "/etc/ejabberd/ejabberd.yml"
}
HTTP/1.1 200 OK
""
create_room¶
Create a MUC room name@service in host
Arguments:
- name :: string : Room name
- service :: string : MUC service
- host :: string : Server host
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/create_room
{
"name": "room1",
"service": "conference.example.com",
"host": "example.com"
}
HTTP/1.1 200 OK
""
create_room_with_opts¶
Create a MUC room name@service in host with given options
The syntax of affiliations
is: Type:JID,Type:JID
. The syntax of subscribers
is: JID:Nick:Node:Node2:Node3,JID:Nick:Node
.
Arguments:
- name :: string : Room name
- service :: string : MUC service
- host :: string : Server host
- options :: [{name::string, value::string}] : List of options
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_muc_admin
Examples:
POST /api/create_room_with_opts
{
"name": "room1",
"service": "conference.example.com",
"host": "localhost",
"options": [
{
"name": "members_only",
"value": "true"
},
{
"name": "affiliations",
"value": "owner:bob@example.com,member:peter@example.com"
},
{
"name": "subscribers",
"value": "bob@example.com:Bob:messages:subject,anne@example.com:Anne:messages"
}
]
}
HTTP/1.1 200 OK
""
create_rooms_file¶
Create the rooms indicated in file
Provide one room JID per line. Rooms will be created after restart.
Arguments:
- file :: string : Path to the text file with one room JID per line
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc
Module: mod_muc_admin
Examples:
delete_expired_messages¶
Delete expired offline messages from database
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Examples:
delete_expired_pubsub_items¶
added in 21.12
Delete expired PubSub items
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: purge
Module: mod_pubsub
Examples:
delete_mnesia¶
Delete elements in Mnesia database for a given vhost
Arguments:
- host :: string : Vhost which content will be deleted in Mnesia database
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: mnesia
Examples:
delete_old_mam_messages¶
Delete MAM messages older than DAYS
Valid message TYPEs: chat
, groupchat
, all
.
Arguments:
- type :: string : Type of messages to delete (
chat
,groupchat
,all
) - days :: integer : Days to keep messages
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_mam
Examples:
delete_old_mam_messages_batch¶
added in 22.05
Delete MAM messages older than DAYS
Valid message TYPEs: chat
, groupchat
, all
.
Arguments:
- host :: string : Name of host where messages should be deleted
- type :: string : Type of messages to delete (
chat
,groupchat
,all
) - days :: integer : Days to keep messages
- batch_size :: integer : Number of messages to delete per batch
- rate :: integer : Desired rate of messages to delete per minute
Result:
- res :: string : Raw result string
Module: mod_mam
Examples:
POST /api/delete_old_mam_messages_batch
{
"host": "localhost",
"type": "all",
"days": 31,
"batch_size": 1000,
"rate": 10000
}
HTTP/1.1 200 OK
"Removal of 5000 messages in progress"
delete_old_mam_messages_status¶
added in 22.05
Status of delete old MAM messages operation
Arguments:
- host :: string : Name of host where messages should be deleted
Result:
- status :: string : Status test
Module: mod_mam
Examples:
POST /api/delete_old_mam_messages_status
{
"host": "localhost"
}
HTTP/1.1 200 OK
"Operation in progress, delete 5000 messages"
delete_old_messages¶
Delete offline messages older than DAYS
Arguments:
- days :: integer : Number of days
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Examples:
delete_old_messages_batch¶
added in 22.05
Delete offline messages older than DAYS
Arguments:
- host :: string : Name of host where messages should be deleted
- days :: integer : Days to keep messages
- batch_size :: integer : Number of messages to delete per batch
- rate :: integer : Desired rate of messages to delete per minute
Result:
- res :: string : Raw result string
Examples:
POST /api/delete_old_messages_batch
{
"host": "localhost",
"days": 31,
"batch_size": 1000,
"rate": 10000
}
HTTP/1.1 200 OK
"Removal of 5000 messages in progress"
delete_old_messages_status¶
added in 22.05
Status of delete old offline messages operation
Arguments:
- host :: string : Name of host where messages should be deleted
Result:
- status :: string : Status test
Examples:
POST /api/delete_old_messages_status
{
"host": "localhost"
}
HTTP/1.1 200 OK
"Operation in progress, delete 5000 messages"
delete_old_pubsub_items¶
added in 21.12
Keep only NUMBER of PubSub items per node
Arguments:
- number :: integer : Number of items to keep per node
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: purge
Module: mod_pubsub
Examples:
delete_old_push_sessions¶
Remove push sessions older than DAYS
Arguments:
- days :: integer
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: purge
Module: mod_push
Examples:
delete_old_users¶
Delete users that didn't log in last days, or that never logged
To protect admin accounts, configure this for example:
Arguments:
- days :: integer : Last login age in days of accounts that should be removed
Result:
- res :: string : Raw result string
Module: mod_admin_extra
Examples:
POST /api/delete_old_users
{
"days": 30
}
HTTP/1.1 200 OK
"Deleted 2 users: ["oldman@myserver.com", "test@myserver.com"]"
delete_old_users_vhost¶
Delete users that didn't log in last days in vhost, or that never logged
To protect admin accounts, configure this for example:
Arguments:
- host :: string : Server name
- days :: integer : Last login age in days of accounts that should be removed
Result:
- res :: string : Raw result string
Module: mod_admin_extra
Examples:
POST /api/delete_old_users_vhost
{
"host": "myserver.com",
"days": 30
}
HTTP/1.1 200 OK
"Deleted 2 users: ["oldman@myserver.com", "test@myserver.com"]"
delete_rosteritem¶
Delete an item from a user's roster (supports ODBC)
Arguments:
- localuser :: string : User name
- localhost :: string : Server name
- user :: string : Contact user name
- host :: string : Contact server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/delete_rosteritem
{
"localuser": "user1",
"localhost": "myserver.com",
"user": "user2",
"host": "myserver.com"
}
HTTP/1.1 200 OK
""
destroy_room¶
Destroy a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc_room
Module: mod_muc_admin
Examples:
destroy_rooms_file¶
Destroy the rooms indicated in file
Provide one room JID per line.
Arguments:
- file :: string : Path to the text file with one room JID per line
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc
Module: mod_muc_admin
Examples:
dump¶
Dump the Mnesia database to a text file
Arguments:
- file :: string : Full path for the text file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
dump_config¶
Dump configuration in YAML format as seen by ejabberd
Arguments:
- out :: string : Full path to output file
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: config
Examples:
dump_table¶
Dump a Mnesia table to a text file
Arguments:
- file :: string : Full path for the text file
- table :: string : Table name
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
POST /api/dump_table
{
"file": "/var/lib/ejabberd/table-muc-registered.txt",
"table": "muc_registered"
}
HTTP/1.1 200 OK
"Success"
export2sql¶
Export virtual host information from Mnesia tables to SQL file
Configure the modules to use SQL, then call this command. After correctly exported the database of a vhost, you may want to delete from mnesia with the delete_mnesia API.
Arguments:
- host :: string : Vhost
- file :: string : Full path to the destination SQL file
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: mnesia
Examples:
POST /api/export2sql
{
"host": "example.com",
"file": "/var/lib/ejabberd/example.com.sql"
}
HTTP/1.1 200 OK
""
export_piefxis¶
Export data of all users in the server to PIEFXIS files (XEP-0227)
Arguments:
- dir :: string : Full path to a directory
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: mnesia
Examples:
export_piefxis_host¶
Export data of users in a host to PIEFXIS files (XEP-0227)
Arguments:
- dir :: string : Full path to a directory
- host :: string : Vhost to export
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: mnesia
Examples:
POST /api/export_piefxis_host
{
"dir": "/var/lib/ejabberd/",
"host": "example.com"
}
HTTP/1.1 200 OK
""
gc¶
added in 20.01
Force full garbage collection
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
gen_html_doc_for_commands¶
Generates html documentation for ejabberd_commands
Arguments:
- file :: string : Path to file where generated documentation should be stored
- regexp :: string : Regexp matching names of commands or modules that will be included inside generated document
- examples :: string : Comma separated list of languages (chosen from
java
,perl
,xmlrpc
,json
) that will have example invocation include in markdown document
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: documentation
Examples:
POST /api/gen_html_doc_for_commands
{
"file": "/home/me/docs/api.html",
"regexp": "mod_admin",
"examples": "java,json"
}
HTTP/1.1 200 OK
""
gen_markdown_doc_for_commands¶
Generates markdown documentation for ejabberd_commands
Arguments:
- file :: string : Path to file where generated documentation should be stored
- regexp :: string : Regexp matching names of commands or modules that will be included inside generated document, or
runtime
to get commands registered at runtime - examples :: string : Comma separated list of languages (chosen from
java
,perl
,xmlrpc
,json
) that will have example invocation include in markdown document
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: documentation
Examples:
POST /api/gen_markdown_doc_for_commands
{
"file": "/home/me/docs/api.html",
"regexp": "mod_admin",
"examples": "java,json"
}
HTTP/1.1 200 OK
""
gen_markdown_doc_for_tags¶
added in 21.12
Generates markdown documentation for ejabberd_commands
Arguments:
- file :: string : Path to file where generated documentation should be stored
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: documentation
Examples:
get_ban_details¶
added in 24.06
Get ban details about an account
Check ban_account API.
Arguments:
- user :: string : User name to unban
- host :: string : Server name
Result:
- ban_details :: [{name::string, value::string}]
Module: mod_admin_extra
Examples:
POST /api/get_ban_details
{
"user": "attacker",
"host": "myserver.com"
}
HTTP/1.1 200 OK
[
{
"name": "reason",
"value": "Spamming other users"
},
{
"name": "bandate",
"value": "2024-04-22T09:16:47.975312Z"
},
{
"name": "lastdate",
"value": "2024-04-22T08:39:12Z"
},
{
"name": "lastreason",
"value": "Connection reset by peer"
}
]
get_cookie¶
Get the Erlang cookie of this node
Arguments:
Result:
- cookie :: string : Erlang cookie used for authentication by ejabberd
Tags: erlang
Module: mod_admin_extra
Examples:
get_last¶
Get last activity information
Timestamp is UTC and XEP-0082 format, for example: 2017-02-23T22:25:28.063062Z ONLINE
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- last_activity :: {timestamp::string, status::string} : Last activity timestamp and status
Tags: last
Module: mod_admin_extra
Examples:
POST /api/get_last
{
"user": "user1",
"host": "myserver.com"
}
HTTP/1.1 200 OK
{
"timestamp": "2017-06-30T14:32:16.060684Z",
"status": "ONLINE"
}
get_loglevel¶
Get the current loglevel
Arguments:
Result:
- levelatom :: string : Tuple with the log level number, its keyword and description
Tags: logs
Examples:
get_mam_count 🟤¶
added in 24.10
Get number of MAM messages in a local user archive
Arguments:
- user :: string
- host :: string
Result:
- value :: integer : Number
Tags: mam
Module: mod_mam
Examples:
get_master¶
added in 24.06
Get master node of the clustered Mnesia tables
If there is no master, returns none
.
Arguments:
Result:
- nodename :: string
Tags: cluster
Examples:
get_offline_count¶
Get the number of unread offline messages
Arguments:
- user :: string
- host :: string
Result:
- value :: integer : Number
Tags: offline
Module: mod_admin_extra
Examples:
get_presence¶
Retrieve the resource with highest priority, and its presence (show and status message) for a given user.
The jid
value contains the user JID with resource.
The show
value contains the user presence flag. It can take limited values:
available
chat
(Free for chat)away
dnd
(Do not disturb)xa
(Not available, extended away)unavailable
(Not connected)
status
is a free text defined by the user client.
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- presence :: {jid::string, show::string, status::string}
Tags: session
Module: mod_admin_extra
Examples:
POST /api/get_presence
{
"user": "peter",
"host": "myexample.com"
}
HTTP/1.1 200 OK
{
"jid": "user1@myserver.com/tka",
"show": "dnd",
"status": "Busy"
}
get_room_affiliation¶
Get affiliation of a user in MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
- jid :: string : User JID
Result:
- affiliation :: string : Affiliation of the user
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_affiliation
{
"name": "room1",
"service": "conference.example.com",
"jid": "user1@example.com"
}
HTTP/1.1 200 OK
"member"
get_room_affiliations¶
Get the list of affiliations of a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- affiliations :: [{username::string, domain::string, affiliation::string, reason::string}] : The list of affiliations with username, domain, affiliation and reason
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_affiliations
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
{
"username": "user1",
"domain": "example.com",
"affiliation": "member",
"reason": "member"
}
]
get_room_history¶
added in 23.04
Get history of messages stored inside MUC room state
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- history :: [{timestamp::string, message::string}]
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_history
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
{
"timestamp": "aaaaa",
"message": "bbbbb"
},
{
"timestamp": "ccccc",
"message": "ddddd"
}
]
get_room_occupants¶
Get the list of occupants of a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- occupants :: [{jid::string, nick::string, role::string}] : The list of occupants with JID, nick and affiliation
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_occupants
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
{
"jid": "user1@example.com/psi",
"nick": "User 1",
"role": "owner"
}
]
get_room_occupants_number¶
Get the number of occupants of a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- occupants :: integer : Number of room occupants
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_occupants_number
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
7
get_room_options¶
Get options from a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- options :: [{name::string, value::string}] : List of room options tuples with name and value
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_room_options
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
{
"name": "members_only",
"value": "true"
}
]
get_roster¶
improved in 23.10
Get list of contacts in a local user roster
subscription
can be: none
, from
, to
, both
.
pending
can be: in
, out
, none
.
Arguments:
- user :: string
- host :: string
Result:
- contacts :: [{jid::string, nick::string, subscription::string, pending::string, groups::[group::string]}]
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/get_roster
{
"user": "aaaaa",
"host": "bbbbb"
}
HTTP/1.1 200 OK
[
{
"jid": "aaaaa",
"nick": "bbbbb",
"subscription": "ccccc",
"pending": "ddddd",
"groups": [
"eeeee",
"fffff"
]
},
{
"jid": "ggggg",
"nick": "hhhhh",
"subscription": "iiiii",
"pending": "jjjjj",
"groups": [
"kkkkk",
"lllll"
]
}
]
get_roster_count¶
added in 24.06
Get number of contacts in a local user roster
Arguments:
- user :: string
- host :: string
Result:
- value :: integer : Number
Tags: roster
Module: mod_admin_extra
Examples:
get_subscribers¶
List subscribers of a MUC conference
Arguments:
- name :: string : Room name
- service :: string : MUC service
Result:
- subscribers :: [jid::string] : The list of users that are subscribed to that room
Module: mod_muc_admin
Examples:
POST /api/get_subscribers
{
"name": "room1",
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
"user2@example.com",
"user3@example.com"
]
get_user_rooms¶
Get the list of rooms where this user is occupant
Arguments:
- user :: string : Username
- host :: string : Server host
Result:
- rooms :: [room::string]
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/get_user_rooms
{
"user": "tom",
"host": "example.com"
}
HTTP/1.1 200 OK
[
"room1@conference.example.com",
"room2@conference.example.com"
]
get_user_subscriptions¶
added in 21.04
Get the list of rooms where this user is subscribed
Arguments:
- user :: string : Username
- host :: string : Server host
Result:
- rooms :: [{roomjid::string, usernick::string, nodes::[node::string]}]
Module: mod_muc_admin
Examples:
POST /api/get_user_subscriptions
{
"user": "tom",
"host": "example.com"
}
HTTP/1.1 200 OK
[
{
"roomjid": "room1@conference.example.com",
"usernick": "Tommy",
"nodes": [
"mucsub:config"
]
}
]
get_vcard¶
Get content from a vCard field
Some vcard field names in get
/set_vcard
are:
- FN - Full Name
- NICKNAME - Nickname
- BDAY - Birthday
- TITLE - Work: Position
- ROLE - Work: Role
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string : User name
- host :: string : Server name
- name :: string : Field name
Result:
- content :: string : Field content
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/get_vcard
{
"user": "user1",
"host": "myserver.com",
"name": "NICKNAME"
}
HTTP/1.1 200 OK
"User 1"
get_vcard2¶
Get content from a vCard subfield
Some vcard field names and subnames in get
/set_vcard2
are:
- N FAMILY - Family name
- N GIVEN - Given name
- N MIDDLE - Middle name
- ADR CTRY - Address: Country
- ADR LOCALITY - Address: City
- TEL HOME - Telephone: Home
- TEL CELL - Telephone: Cellphone
- TEL WORK - Telephone: Work
- TEL VOICE - Telephone: Voice
- EMAIL USERID - E-Mail Address
- ORG ORGNAME - Work: Company
- ORG ORGUNIT - Work: Department
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string : User name
- host :: string : Server name
- name :: string : Field name
- subname :: string : Subfield name
Result:
- content :: string : Field content
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/get_vcard2
{
"user": "user1",
"host": "myserver.com",
"name": "N",
"subname": "FAMILY"
}
HTTP/1.1 200 OK
"Schubert"
get_vcard2_multi¶
Get multiple contents from a vCard field
Some vcard field names and subnames in get
/set_vcard2
are:
- N FAMILY - Family name
- N GIVEN - Given name
- N MIDDLE - Middle name
- ADR CTRY - Address: Country
- ADR LOCALITY - Address: City
- TEL HOME - Telephone: Home
- TEL CELL - Telephone: Cellphone
- TEL WORK - Telephone: Work
- TEL VOICE - Telephone: Voice
- EMAIL USERID - E-Mail Address
- ORG ORGNAME - Work: Company
- ORG ORGUNIT - Work: Department
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string
- host :: string
- name :: string
- subname :: string
Result:
- contents :: [value::string]
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/get_vcard2_multi
{
"user": "aaaaa",
"host": "bbbbb",
"name": "ccccc",
"subname": "ddddd"
}
HTTP/1.1 200 OK
[
"aaaaa",
"bbbbb"
]
halt¶
added in 23.10
Halt ejabberd abruptly with status code 1
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
help¶
Get list of commands, or help of a command (only ejabberdctl)
This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend.
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: ejabberdctl
Examples:
import_dir¶
Import users data from jabberd14 spool dir
Arguments:
- file :: string : Full path to the jabberd14 spool directory
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
import_file¶
Import user data from jabberd14 spool file
Arguments:
- file :: string : Full path to the jabberd14 spool file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
import_piefxis¶
Import users data from a PIEFXIS file (XEP-0227)
Arguments:
- file :: string : Full path to the PIEFXIS file
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: mnesia
Examples:
import_prosody¶
Import data from Prosody
Note: this requires ejabberd to be compiled with ./configure --enable-lua
(which installs the luerl
library).
Arguments:
- dir :: string : Full path to the Prosody data directory
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Examples:
incoming_s2s_number¶
Number of incoming s2s connections on the node
Arguments:
Result:
- s2s_incoming :: integer
Tags: statistics, s2s
Examples:
install_fallback¶
Install Mnesia database from a binary backup file
The binary backup file is installed as fallback: it will be used to restore the database at the next ejabberd start. This means that, after running this command, you have to restart ejabberd. This command requires less memory than restore API.
Arguments:
- file :: string : Full path to the fallback file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
POST /api/install_fallback
{
"file": "/var/lib/ejabberd/database.fallback"
}
HTTP/1.1 200 OK
"Success"
join_cluster¶
improved in 24.06
Join our local node into the cluster handled by Node
Arguments:
- node :: string : Nodename of the node to join
Result:
- res :: string : Raw result string
Tags: cluster
Examples:
join_cluster_here¶
added in 24.06
Join a remote Node here, into our cluster
Arguments:
- node :: string : Nodename of the node to join here
Result:
- res :: string : Raw result string
Tags: cluster
Examples:
kick_session¶
Kick a user session
Arguments:
- user :: string : User name
- host :: string : Server name
- resource :: string : User's resource
- reason :: string : Reason for closing session
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: session
Module: mod_admin_extra
Examples:
POST /api/kick_session
{
"user": "peter",
"host": "myserver.com",
"resource": "Psi",
"reason": "Stuck connection"
}
HTTP/1.1 200 OK
""
kick_user¶
modified in 24.06
Disconnect user's active sessions
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- res :: string : Raw result string
Examples:
leave_cluster¶
Remove and shutdown Node from the running cluster
This command can be run from any running node of the cluster, even the node to be removed. In the removed node, this command works only when using ejabberdctl, not mod_http_api or other code that runs inside the same ejabberd node that will leave.
Arguments:
- node :: string : Nodename of the node to kick from the cluster
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: cluster
Examples:
list_certificates¶
Lists all ACME certificates
Arguments:
Result:
- certificates :: [{domain::string, file::string, used::string}]
Tags: acme
Examples:
POST /api/list_certificates
{
}
HTTP/1.1 200 OK
[
{
"domain": "aaaaa",
"file": "bbbbb",
"used": "ccccc"
},
{
"domain": "ddddd",
"file": "eeeee",
"used": "fffff"
}
]
list_cluster¶
List running nodes that are part of this cluster
Arguments:
Result:
- nodes :: [node::string]
Tags: cluster
Examples:
list_cluster_detailed¶
added in 24.06
List nodes (both running and known) and some stats
Arguments:
Result:
- nodes :: [{name::string, running::string, status::string, online_users::integer, processes::integer, uptime_seconds::integer, master_node::string}]
Tags: cluster
Examples:
POST /api/list_cluster_detailed
{
}
HTTP/1.1 200 OK
[
{
"name": "ejabberd@localhost",
"running": "true",
"status": "The node ejabberd is started. Status...",
"online_users": 7,
"processes": 348,
"uptime_seconds": 60,
"master_node": "none"
}
]
load¶
Restore Mnesia database from a text dump file
Restore immediately. This is not recommended for big databases, as it will consume much time, memory and processor. In that case it's preferable to use backup API and install_fallback API.
Arguments:
- file :: string : Full path to the text file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
man¶
added in 20.01
Generate Unix manpage for current ejabberd version
Arguments:
Result:
- res :: string : Raw result string
Tags: documentation
Examples:
mnesia_change_nodename¶
Change the erlang node name in a backup file
Arguments:
- oldnodename :: string : Name of the old erlang node
- newnodename :: string : Name of the new node
- oldbackup :: string : Path to old backup file
- newbackup :: string : Path to the new backup file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
POST /api/mnesia_change_nodename
{
"oldnodename": "ejabberd@machine1",
"newnodename": "ejabberd@machine2",
"oldbackup": "/var/lib/ejabberd/old.backup",
"newbackup": "/var/lib/ejabberd/new.backup"
}
HTTP/1.1 200 OK
"Success"
mnesia_info¶
Dump info on global Mnesia state
Arguments:
Result:
- res :: string
Tags: mnesia
Examples:
mnesia_info_ctl¶
renamed in 24.02
Show information of Mnesia system (only ejabberdctl)
This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend.
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: ejabberdctl, mnesia
Examples:
mnesia_table_info¶
Dump info on Mnesia table state
Arguments:
- table :: string : Mnesia table name
Result:
- res :: string
Tags: mnesia
Examples:
module_check¶
Check the contributed module repository compliance
Arguments:
- module :: string : Module name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: modules
Examples:
module_install¶
Compile, install and start an available contributed module
Arguments:
- module :: string : Module name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: modules
Examples:
module_uninstall¶
Uninstall a contributed module
Arguments:
- module :: string : Module name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: modules
Examples:
module_upgrade¶
Upgrade the running code of an installed module
In practice, this uninstalls and installs the module
Arguments:
- module :: string : Module name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: modules
Examples:
modules_available¶
List the contributed modules available to install
Arguments:
Result:
- modules :: [{name::string, summary::string}] : List of tuples with module name and description
Tags: modules
Examples:
POST /api/modules_available
{
}
HTTP/1.1 200 OK
{
"mod_cron": "Execute scheduled commands",
"mod_rest": "ReST frontend"
}
modules_installed¶
List the contributed modules already installed
Arguments:
Result:
- modules :: [{name::string, summary::string}] : List of tuples with module name and description
Tags: modules
Examples:
POST /api/modules_installed
{
}
HTTP/1.1 200 OK
{
"mod_cron": "Execute scheduled commands",
"mod_rest": "ReST frontend"
}
modules_update_specs¶
Update the module source code from Git
A connection to Internet is required
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: modules
Examples:
muc_online_rooms¶
List existing rooms
Ask for a specific host, or global
to use all vhosts.
Arguments:
- service :: string : MUC service, or
global
for all
Result:
- rooms :: [room::string] : List of rooms
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/muc_online_rooms
{
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
"room1@conference.example.com",
"room2@conference.example.com"
]
muc_online_rooms_by_regex¶
List existing rooms filtered by regexp
Ask for a specific host, or global
to use all vhosts.
Arguments:
- service :: string : MUC service, or
global
for all - regex :: string : Regex pattern for room name
Result:
- rooms :: [{jid::string, public::string, participants::integer}] : List of rooms with summary
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/muc_online_rooms_by_regex
{
"service": "conference.example.com",
"regex": "^prefix"
}
HTTP/1.1 200 OK
[
{
"jid": "room1@conference.example.com",
"public": "true",
"participants": 10
},
{
"jid": "room2@conference.example.com",
"public": "false",
"participants": 10
}
]
muc_register_nick¶
Register a nick to a User JID in a MUC service
Arguments:
- nick :: string : Nick
- jid :: string : User JID
- service :: string : Service
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/muc_register_nick
{
"nick": "Tim",
"jid": "tim@example.org",
"service": "conference.example.org"
}
HTTP/1.1 200 OK
""
muc_unregister_nick¶
Unregister the nick registered by that account in the MUC service
Arguments:
- jid :: string : User JID
- service :: string : MUC service
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/muc_unregister_nick
{
"jid": "tim@example.org",
"service": "conference.example.org"
}
HTTP/1.1 200 OK
""
num_resources¶
Get the number of resources of a user
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- resources :: integer : Number of active resources for a user
Tags: session
Module: mod_admin_extra
Examples:
oauth_add_client_implicit¶
Add OAuth client_id with implicit grant type
Arguments:
- client_id :: string
- client_name :: string
- redirect_uri :: string
Result:
- res :: string : Raw result string
Tags: oauth
Examples:
POST /api/oauth_add_client_implicit
{
"client_id": "aaaaa",
"client_name": "bbbbb",
"redirect_uri": "ccccc"
}
HTTP/1.1 200 OK
"Success"
oauth_add_client_password¶
Add OAuth client_id with password grant type
Arguments:
- client_id :: string
- client_name :: string
- secret :: string
Result:
- res :: string : Raw result string
Tags: oauth
Examples:
POST /api/oauth_add_client_password
{
"client_id": "aaaaa",
"client_name": "bbbbb",
"secret": "ccccc"
}
HTTP/1.1 200 OK
"Success"
oauth_issue_token¶
updated in 24.02
Issue an OAuth optionredir token for the given jid
Arguments:
- jid :: string : Jid for which issue token
- ttl :: integer : Time to live of generated token in seconds
- scopes :: [scope::string] : List of scopes to allow
Result:
- result :: {token::string, scopes::[scope::string], expires_in::string}
Examples:
POST /api/oauth_issue_token
{
"jid": "user@server.com",
"ttl": 3600,
"scopes": [
"connected_users_number",
"muc_online_rooms"
]
}
HTTP/1.1 200 OK
{
"token": "aaaaa",
"scopes": [
"bbbbb",
"ccccc"
],
"expires_in": "ddddd"
}
oauth_list_tokens¶
List OAuth tokens, user, scope, and seconds to expire (only Mnesia)
List OAuth tokens, their user and scope, and how many seconds remain until expirity
Arguments:
Result:
- tokens :: [{token::string, user::string, scope::string, expires_in::string}]
Tags: oauth
Examples:
POST /api/oauth_list_tokens
{
}
HTTP/1.1 200 OK
[
{
"token": "aaaaa",
"user": "bbbbb",
"scope": "ccccc",
"expires_in": "ddddd"
},
{
"token": "eeeee",
"user": "fffff",
"scope": "ggggg",
"expires_in": "hhhhh"
}
]
oauth_remove_client¶
Remove OAuth client_id
Arguments:
- client_id :: string
Result:
- res :: string : Raw result string
Tags: oauth
Examples:
oauth_revoke_token¶
changed in 22.05
Revoke authorization for an OAuth token
Arguments:
- token :: string
Result:
- res :: string : Raw result string
Tags: oauth
Examples:
outgoing_s2s_number¶
Number of outgoing s2s connections on the node
Arguments:
Result:
- s2s_outgoing :: integer
Tags: statistics, s2s
Examples:
print_sql_schema¶
added in 24.02
Print SQL schema for the given RDBMS (only ejabberdctl)
This command is exclusive for the ejabberdctl command-line script, don't attempt to execute it using any other API frontend.
Arguments:
- db_type :: string : Database type: pgsql | mysql | sqlite
- db_version :: string : Your database version: 16.1, 8.2.0...
- new_schema :: string : Use new schema: 0, false, 1 or true
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: ejabberdctl, sql
Examples:
POST /api/print_sql_schema
{
"db_type": "pgsql",
"db_version": "16.1",
"new_schema": "true"
}
HTTP/1.1 200 OK
""
privacy_set¶
Send a IQ set privacy stanza for a local account
Arguments:
- user :: string : Username
- host :: string : Server name
- xmlquery :: string : Query XML element
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: stanza
Module: mod_admin_extra
Examples:
POST /api/privacy_set
{
"user": "user1",
"host": "myserver.com",
"xmlquery": "<query xmlns='jabber:iq:privacy'>..."
}
HTTP/1.1 200 OK
""
private_get¶
Get some information from a user private storage
Arguments:
- user :: string : User name
- host :: string : Server name
- element :: string : Element name
- ns :: string : Namespace
Result:
- res :: string
Tags: private
Module: mod_admin_extra
Examples:
POST /api/private_get
{
"user": "user1",
"host": "myserver.com",
"element": "storage",
"ns": "storage:rosternotes"
}
HTTP/1.1 200 OK
"aaaaa"
private_set¶
Set to the user private storage
Arguments:
- user :: string : User name
- host :: string : Server name
- element :: string : XML storage element
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: private
Module: mod_admin_extra
Examples:
POST /api/private_set
{
"user": "user1",
"host": "myserver.com",
"element": "<storage xmlns='storage:rosternotes'/>"
}
HTTP/1.1 200 OK
""
process_rosteritems¶
List/delete rosteritems that match filter
Explanation of each argument:
action
: what to do with each rosteritem that matches all the filtering optionssubs
: subscription typeasks
: pending subscriptionusers
: the JIDs of the local usercontacts
: the JIDs of the contact in the roster
Mnesia backend:
Allowed values in the arguments:
action
=list
|delete
subs
=any
| SUB[:SUB]*asks
=any
| ASK[:ASK]*users
=any
| JID[:JID]*contacts
=any
| JID[:JID]*
where
- SUB =
none
|from
|to
|both
- ASK =
none
|out
|in
- JID = characters valid in a JID, and can use the globs:
*
,?
,!
and[...]
This example will list roster items with subscription none
, from
or to
that have any ask property, of local users which JID is in the virtual host example.org
and that the contact JID is either a bare server name (without user part) or that has a user part and the server part contains the word icq
:
list none:from:to any *@example.org *:*@*icq*
SQL backend:
Allowed values in the arguments:
action
=list
|delete
subs
=any
| SUBasks
=any
| ASKusers
= JIDcontacts
= JID
where
- SUB =
none
|from
|to
|both
- ASK =
none
|out
|in
- JID = characters valid in a JID, and can use the globs:
_
and%
This example will list roster items with subscription to
that have any ask property, of local users which JID is in the virtual host example.org
and that the contact JID's server part contains the word icq
:
list to any %@example.org %@%icq%
Arguments:
- action :: string
- subs :: string
- asks :: string
- users :: string
- contacts :: string
Result:
- response :: [{user::string, contact::string}]
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/process_rosteritems
{
"action": "aaaaa",
"subs": "bbbbb",
"asks": "ccccc",
"users": "ddddd",
"contacts": "eeeee"
}
HTTP/1.1 200 OK
[
{
"user": "aaaaa",
"contact": "bbbbb"
},
{
"user": "ccccc",
"contact": "ddddd"
}
]
push_alltoall¶
Add all the users to all the users of Host in Group
Arguments:
- host :: string : Server name
- group :: string : Group name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: roster
Module: mod_admin_extra
Examples:
push_roster¶
Push template roster from file to a user
The text file must contain an erlang term: a list of tuples with username, servername, group and nick. For example:
[{"user1", "localhost", "Workers", "User 1"},
{"user2", "localhost", "Workers", "User 2"}].
If there are problems parsing UTF8 character encoding, provide the corresponding string with the <<"STRING"/utf8>>
syntax, for example:
[{"user2", "localhost", "Workers", <<"User 2"/utf8>>}]
.
Arguments:
- file :: string : File path
- user :: string : User name
- host :: string : Server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/push_roster
{
"file": "/home/ejabberd/roster.txt",
"user": "user1",
"host": "localhost"
}
HTTP/1.1 200 OK
""
push_roster_all¶
Push template roster from file to all those users
The text file must contain an erlang term: a list of tuples with username, servername, group and nick. Example:
[{"user1", "localhost", "Workers", "User 1"},
{"user2", "localhost", "Workers", "User 2"}].
Arguments:
- file :: string : File path
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: roster
Module: mod_admin_extra
Examples:
register¶
Register a user
Arguments:
- user :: string : Username
- host :: string : Local vhost served by ejabberd
- password :: string : Password
Result:
- res :: string : Raw result string
Tags: accounts
Examples:
POST /api/register
{
"user": "bob",
"host": "example.com",
"password": "SomEPass44"
}
HTTP/1.1 200 OK
"Success"
registered_users¶
List all registered users in HOST
Arguments:
- host :: string : Local vhost
Result:
- users :: [username::string] : List of registered accounts usernames
Tags: accounts
Examples:
registered_vhosts¶
List all registered vhosts in SERVER
Arguments:
Result:
- vhosts :: [vhost::string] : List of available vhosts
Tags: server
Examples:
reload_config¶
Reload config file in memory
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: config
Examples:
remove_mam_for_user¶
Remove mam archive for user
Arguments:
- user :: string : Username
- host :: string : Server
Result:
- res :: string : Raw result string
Tags: mam
Module: mod_mam
Examples:
POST /api/remove_mam_for_user
{
"user": "bob",
"host": "example.com"
}
HTTP/1.1 200 OK
"MAM archive removed"
remove_mam_for_user_with_peer¶
Remove mam archive for user with peer
Arguments:
- user :: string : Username
- host :: string : Server
- with :: string : Peer
Result:
- res :: string : Raw result string
Tags: mam
Module: mod_mam
Examples:
POST /api/remove_mam_for_user_with_peer
{
"user": "bob",
"host": "example.com",
"with": "anne@example.com"
}
HTTP/1.1 200 OK
"MAM archive removed"
reopen_log¶
Reopen maybe the log files after being renamed
Has no effect on ejabberd main log files, only on log files generated by some modules. This can be useful when an external tool is used for log rotation. See Log Files.
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: logs
Examples:
request_certificate¶
Requests certificates for all or some domains
Domains can be all
, or a list of domains separared with comma characters
Arguments:
- domains :: string : Domains for which to acquire a certificate
Result:
- res :: string : Raw result string
Tags: acme
Examples:
POST /api/request_certificate
{
"domains": "example.com,domain.tld,conference.domain.tld"
}
HTTP/1.1 200 OK
"Success"
resource_num¶
Resource string of a session number
Arguments:
- user :: string : User name
- host :: string : Server name
- num :: integer : ID of resource to return
Result:
- resource :: string : Name of user resource
Tags: session
Module: mod_admin_extra
Examples:
restart¶
Restart ejabberd gracefully
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
restart_module¶
Stop an ejabberd module, reload code and start
Arguments:
- host :: string : Server name
- module :: string : Module to restart
Result:
- res :: integer : Returns integer code:
0
: code reloaded, module restarted1
: error: module not loaded2
: code not reloaded, but module restarted
Tags: erlang
Module: mod_admin_extra
Examples:
restore¶
Restore the Mnesia database from a binary backup file
This restores immediately from a binary backup file the internal Mnesia database. This will consume a lot of memory if you have a large database, you may prefer install_fallback API.
Arguments:
- file :: string : Full path to the backup file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
revoke_certificate¶
Revokes the selected ACME certificate
Arguments:
- file :: string : Filename of the certificate
Result:
- res :: string : Raw result string
Tags: acme
Examples:
rooms_empty_destroy¶
modified in 24.06
Destroy the rooms that have no messages in archive
The MUC service argument can be global
to get all hosts.
Arguments:
- service :: string : MUC service, or
global
for all
Result:
- res :: string : Raw result string
Module: mod_muc_admin
Examples:
POST /api/rooms_empty_destroy
{
"service": "conference.example.com"
}
HTTP/1.1 200 OK
"Destroyed rooms: 2"
rooms_empty_list¶
List the rooms that have no messages in archive
The MUC service argument can be global
to get all hosts.
Arguments:
- service :: string : MUC service, or
global
for all
Result:
- rooms :: [room::string] : List of empty rooms
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/rooms_empty_list
{
"service": "conference.example.com"
}
HTTP/1.1 200 OK
[
"room1@conference.example.com",
"room2@conference.example.com"
]
rooms_unused_destroy¶
Destroy the rooms that are unused for many days in the service
The room recent history is used, so it's recommended to wait a few days after service start before running this. The MUC service argument can be global
to get all hosts.
Arguments:
- service :: string : MUC service, or
global
for all - days :: integer : Number of days
Result:
- rooms :: [room::string] : List of unused rooms that has been destroyed
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/rooms_unused_destroy
{
"service": "conference.example.com",
"days": 31
}
HTTP/1.1 200 OK
[
"room1@conference.example.com",
"room2@conference.example.com"
]
rooms_unused_list¶
List the rooms that are unused for many days in the service
The room recent history is used, so it's recommended to wait a few days after service start before running this. The MUC service argument can be global
to get all hosts.
Arguments:
- service :: string : MUC service, or
global
for all - days :: integer : Number of days
Result:
- rooms :: [room::string] : List of unused rooms
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/rooms_unused_list
{
"service": "conference.example.com",
"days": 31
}
HTTP/1.1 200 OK
[
"room1@conference.example.com",
"room2@conference.example.com"
]
rotate_log¶
Rotate maybe log file of some module
Has no effect on ejabberd main log files, only on log files generated by some modules.
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: logs
Examples:
send_direct_invitation¶
updated in 24.02
Send a direct invitation to several destinations
Since ejabberd 20.12, this command is asynchronous: the API call may return before the server has send all the invitations.
password
and message
can be set to none
.
Arguments:
- name :: string : Room name
- service :: string : MUC service
- password :: string : Password, or
none
- reason :: string : Reason text, or
none
- users :: [jid::string] : List of users JIDs
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_muc_admin
Examples:
POST /api/send_direct_invitation
{
"name": "room1",
"service": "conference.example.com",
"password": "",
"reason": "Check this out!",
"users": [
"user2@localhost",
"user3@example.com"
]
}
HTTP/1.1 200 OK
""
send_message¶
Send a message to a local or remote bare of full JID
When sending a groupchat message to a MUC room, from
must be the full JID of a room occupant, or the bare JID of a MUC service admin, or the bare JID of a MUC/Sub subscribed user.
Arguments:
- type :: string : Message type:
normal
,chat
,headline
,groupchat
- from :: string : Sender JID
- to :: string : Receiver JID
- subject :: string : Subject, or empty string
- body :: string : Body
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: stanza
Module: mod_admin_extra
Examples:
POST /api/send_message
{
"type": "headline",
"from": "admin@localhost",
"to": "user1@localhost",
"subject": "Restart",
"body": "In 5 minutes"
}
HTTP/1.1 200 OK
""
send_stanza¶
Send a stanza; provide From JID and valid To JID
Arguments:
- from :: string : Sender JID
- to :: string : Destination JID
- stanza :: string : Stanza
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: stanza
Module: mod_admin_extra
Examples:
POST /api/send_stanza
{
"from": "admin@localhost",
"to": "user1@localhost",
"stanza": "<message><ext attr='value'/></message>"
}
HTTP/1.1 200 OK
""
send_stanza_c2s¶
Send a stanza from an existing C2S session
user
@host
/resource
must be an existing C2S session. As an alternative, use send_stanza API instead.
Arguments:
- user :: string : Username
- host :: string : Server name
- resource :: string : Resource
- stanza :: string : Stanza
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: stanza
Module: mod_admin_extra
Examples:
POST /api/send_stanza_c2s
{
"user": "admin",
"host": "myserver.com",
"resource": "bot",
"stanza": "<message to='user1@localhost'><ext attr='value'/></message>"
}
HTTP/1.1 200 OK
""
set_last¶
Set last activity information
Timestamp is the seconds since 1970-01-01 00:00:00 UTC
. For example value see date +%s
Arguments:
- user :: string : User name
- host :: string : Server name
- timestamp :: integer : Number of seconds since epoch
- status :: string : Status message
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: last
Module: mod_admin_extra
Examples:
POST /api/set_last
{
"user": "user1",
"host": "myserver.com",
"timestamp": 1500045311,
"status": "GoSleeping"
}
HTTP/1.1 200 OK
""
set_loglevel¶
Set the loglevel
Possible loglevels: none
, emergency
, alert
, critical
,
error
, warning
, notice
, info
, debug
.
Arguments:
- loglevel :: string : Desired logging level
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: logs
Examples:
set_master¶
Set master node of the clustered Mnesia tables
If nodename
is set to self
, then this node will be set as its own master.
Arguments:
- nodename :: string : Name of the erlang node that will be considered master of this node
Result:
- res :: string : Raw result string
Tags: cluster
Examples:
set_nickname¶
Set nickname in a user's vCard
Arguments:
- user :: string : User name
- host :: string : Server name
- nickname :: string : Nickname
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/set_nickname
{
"user": "user1",
"host": "myserver.com",
"nickname": "User 1"
}
HTTP/1.1 200 OK
""
set_presence¶
updated in 24.02
Set presence of a session
Arguments:
- user :: string : User name
- host :: string : Server name
- resource :: string : Resource
- type :: string : Type:
available
,error
,probe
... - show :: string : Show:
away
,chat
,dnd
,xa
. - status :: string : Status text
- priority :: integer : Priority, provide this value as an integer
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_admin_extra
Examples:
POST /api/set_presence
{
"user": "user1",
"host": "myserver.com",
"resource": "tka1",
"type": "available",
"show": "away",
"status": "BB",
"priority": 7
}
HTTP/1.1 200 OK
""
set_room_affiliation¶
Change an affiliation in a MUC room
Arguments:
- name :: string : Room name
- service :: string : MUC service
- jid :: string : User JID
- affiliation :: string : Affiliation to set
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/set_room_affiliation
{
"name": "room1",
"service": "conference.example.com",
"jid": "user2@example.com",
"affiliation": "member"
}
HTTP/1.1 200 OK
""
set_vcard¶
Set content in a vCard field
Some vcard field names in get
/set_vcard
are:
- FN - Full Name
- NICKNAME - Nickname
- BDAY - Birthday
- TITLE - Work: Position
- ROLE - Work: Role
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string : User name
- host :: string : Server name
- name :: string : Field name
- content :: string : Value
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/set_vcard
{
"user": "user1",
"host": "myserver.com",
"name": "URL",
"content": "www.example.com"
}
HTTP/1.1 200 OK
""
set_vcard2¶
Set content in a vCard subfield
Some vcard field names and subnames in get
/set_vcard2
are:
- N FAMILY - Family name
- N GIVEN - Given name
- N MIDDLE - Middle name
- ADR CTRY - Address: Country
- ADR LOCALITY - Address: City
- TEL HOME - Telephone: Home
- TEL CELL - Telephone: Cellphone
- TEL WORK - Telephone: Work
- TEL VOICE - Telephone: Voice
- EMAIL USERID - E-Mail Address
- ORG ORGNAME - Work: Company
- ORG ORGUNIT - Work: Department
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string : User name
- host :: string : Server name
- name :: string : Field name
- subname :: string : Subfield name
- content :: string : Value
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/set_vcard2
{
"user": "user1",
"host": "myserver.com",
"name": "TEL",
"subname": "NUMBER",
"content": "123456"
}
HTTP/1.1 200 OK
""
set_vcard2_multi¶
Set multiple contents in a vCard subfield
Some vcard field names and subnames in get
/set_vcard2
are:
- N FAMILY - Family name
- N GIVEN - Given name
- N MIDDLE - Middle name
- ADR CTRY - Address: Country
- ADR LOCALITY - Address: City
- TEL HOME - Telephone: Home
- TEL CELL - Telephone: Cellphone
- TEL WORK - Telephone: Work
- TEL VOICE - Telephone: Voice
- EMAIL USERID - E-Mail Address
- ORG ORGNAME - Work: Company
- ORG ORGUNIT - Work: Department
For a full list of vCard fields check XEP-0054: vcard-temp
Arguments:
- user :: string
- host :: string
- name :: string
- subname :: string
- contents :: [value::string]
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: vcard
Module: mod_admin_extra
Examples:
POST /api/set_vcard2_multi
{
"user": "aaaaa",
"host": "bbbbb",
"name": "ccccc",
"subname": "ddddd",
"contents": [
"eeeee",
"fffff"
]
}
HTTP/1.1 200 OK
""
srg_add¶
added in 24.06
Add/Create a Shared Roster Group (without details)
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
srg_add_displayed¶
added in 24.06
Add a group to displayed_groups of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
- add :: string : Group to add to displayed_groups
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_add_displayed
{
"group": "group3",
"host": "myserver.com",
"add": "group1"
}
HTTP/1.1 200 OK
""
srg_create¶
updated in 24.02
Create a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
- label :: string : Group name
- description :: string : Group description
- display :: [group::string] : List of groups to display
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group, v1
Module: mod_admin_extra
Examples:
POST /api/srg_create
{
"group": "group3",
"host": "myserver.com",
"label": "Group3",
"description": "Third group",
"display": [
"group1",
"group2"
]
}
HTTP/1.1 200 OK
""
srg_del_displayed¶
added in 24.06
Delete a group from displayed_groups of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
- del :: string : Group to delete from displayed_groups
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_del_displayed
{
"group": "group3",
"host": "myserver.com",
"del": "group1"
}
HTTP/1.1 200 OK
""
srg_delete¶
Delete a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
srg_get_displayed¶
added in 24.06
Get displayed groups of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- display :: [group::string] : List of groups to display
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_get_displayed
{
"group": "group3",
"host": "myserver.com"
}
HTTP/1.1 200 OK
[
"group1",
"group2"
]
srg_get_info¶
Get info of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- informations :: [{key::string, value::string}] : List of group information, as key and value
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_get_info
{
"group": "group3",
"host": "myserver.com"
}
HTTP/1.1 200 OK
[
{
"key": "name",
"value": "Group 3"
},
{
"key": "displayed_groups",
"value": "group1"
}
]
srg_get_members¶
Get members of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- members :: [member::string] : List of group identifiers
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_get_members
{
"group": "group3",
"host": "myserver.com"
}
HTTP/1.1 200 OK
[
"user1@localhost",
"user2@localhost"
]
srg_list¶
List the Shared Roster Groups in Host
Arguments:
- host :: string : Server name
Result:
- groups :: [id::string] : List of group identifiers
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
srg_set_info¶
added in 24.06
Set info of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
- key :: string : Information key: label, description
- value :: string : Information value
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_set_info
{
"group": "group3",
"host": "myserver.com",
"key": "label",
"value": "Family"
}
HTTP/1.1 200 OK
""
srg_user_add¶
Add the JID user@host to the Shared Roster Group
Arguments:
- user :: string : Username
- host :: string : User server name
- group :: string : Group identifier
- grouphost :: string : Group server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_user_add
{
"user": "user1",
"host": "myserver.com",
"group": "group3",
"grouphost": "myserver.com"
}
HTTP/1.1 200 OK
""
srg_user_del¶
Delete this JID user@host from the Shared Roster Group
Arguments:
- user :: string : Username
- host :: string : User server name
- group :: string : Group identifier
- grouphost :: string : Group server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_user_del
{
"user": "user1",
"host": "myserver.com",
"group": "group3",
"grouphost": "myserver.com"
}
HTTP/1.1 200 OK
""
stats¶
Get some statistical value for the whole ejabberd server
Allowed statistics name
are: registeredusers
, onlineusers
, onlineusersnode
, uptimeseconds
, processes
.
Arguments:
- name :: string : Statistic name
Result:
- stat :: integer : Integer statistic value
Tags: statistics
Module: mod_admin_extra
Examples:
stats_host¶
Get some statistical value for this host
Allowed statistics name
are: registeredusers
, onlineusers
.
Arguments:
- name :: string : Statistic name
- host :: string : Server JID
Result:
- stat :: integer : Integer statistic value
Tags: statistics
Module: mod_admin_extra
Examples:
status¶
Get status of the ejabberd server
Arguments:
Result:
- res :: string : Raw result string
Tags: server
Examples:
POST /api/status
{
}
HTTP/1.1 200 OK
"The node ejabberd@localhost is started with status: startedejabberd X.X is running in that node"
status_list¶
List of logged users with this status
Arguments:
- status :: string : Status type to check
Result:
- users :: [{user::string, host::string, resource::string, priority::integer, status::string}]
Tags: session
Module: mod_admin_extra
Examples:
POST /api/status_list
{
"status": "dnd"
}
HTTP/1.1 200 OK
[
{
"user": "peter",
"host": "myserver.com",
"resource": "tka",
"priority": 6,
"status": "Busy"
}
]
status_list_host¶
List of users logged in host with their statuses
Arguments:
- host :: string : Server name
- status :: string : Status type to check
Result:
- users :: [{user::string, host::string, resource::string, priority::integer, status::string}]
Tags: session
Module: mod_admin_extra
Examples:
POST /api/status_list_host
{
"host": "myserver.com",
"status": "dnd"
}
HTTP/1.1 200 OK
[
{
"user": "peter",
"host": "myserver.com",
"resource": "tka",
"priority": 6,
"status": "Busy"
}
]
status_num¶
Number of logged users with this status
Arguments:
- status :: string : Status type to check
Result:
- users :: integer : Number of connected sessions with given status type
Tags: session, statistics
Module: mod_admin_extra
Examples:
status_num_host¶
Number of logged users with this status in host
Arguments:
- host :: string : Server name
- status :: string : Status type to check
Result:
- users :: integer : Number of connected sessions with given status type
Tags: session, statistics
Module: mod_admin_extra
Examples:
stop¶
Stop ejabberd gracefully
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
stop_kindly¶
Inform users and rooms, wait, and stop the server
Provide the delay in seconds, and the announcement quoted, for example:
ejabberdctl stop_kindly 60 \"The server will stop in one minute.\"
Arguments:
- delay :: integer : Seconds to wait
- announcement :: string : Announcement to send, with quotes
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: server
Examples:
stop_s2s_connections¶
Stop all s2s outgoing and incoming connections
Arguments:
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Tags: s2s
Examples:
subscribe_room¶
updated in 24.02
Subscribe to a MUC conference
Arguments:
- user :: string : User JID
- nick :: string : a user's nick
- room :: string : the room to subscribe
- nodes :: [node::string] : list of nodes
Result:
- nodes :: [node::string] : The list of nodes that has subscribed
Module: mod_muc_admin
Examples:
POST /api/subscribe_room
{
"user": "tom@localhost",
"nick": "Tom",
"room": "room1@conference.localhost",
"nodes": [
"urn:xmpp:mucsub:nodes:messages",
"urn:xmpp:mucsub:nodes:affiliations"
]
}
HTTP/1.1 200 OK
[
"urn:xmpp:mucsub:nodes:messages",
"urn:xmpp:mucsub:nodes:affiliations"
]
subscribe_room_many¶
updated in 24.02
Subscribe several users to a MUC conference
This command accepts up to 50 users at once (this is configurable with the mod_muc_admin option subscribe_room_many_max_users
)
Arguments:
- users :: [{jid::string, nick::string}] : Users JIDs and nicks
- room :: string : the room to subscribe
- nodes :: [node::string] : nodes separated by commas:
,
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_muc_admin
Examples:
POST /api/subscribe_room_many
{
"users": [
{
"jid": "tom@localhost",
"nick": "Tom"
},
{
"jid": "jerry@localhost",
"nick": "Jerry"
}
],
"room": "room1@conference.localhost",
"nodes": [
"urn:xmpp:mucsub:nodes:messages",
"urn:xmpp:mucsub:nodes:affiliations"
]
}
HTTP/1.1 200 OK
""
unban_account¶
added in 24.06
Revert the ban from an account: set back the old password
Check ban_account API.
Arguments:
- user :: string : User name to unban
- host :: string : Server name
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_admin_extra
Examples:
unban_ip¶
Remove banned IP addresses from the fail2ban table
Accepts an IP address with a network mask. Returns the number of unbanned addresses, or a negative integer if there were any error.
Arguments:
- address :: string : IP address, optionally with network mask.
Result:
- unbanned :: integer : Amount of unbanned entries, or negative in case of error.
Tags: accounts
Module: mod_fail2ban
Examples:
unregister¶
Unregister a user
This deletes the authentication and all the data associated to the account (roster, vcard...).
Arguments:
- user :: string : Username
- host :: string : Local vhost served by ejabberd
Result:
- res :: string : Raw result string
Tags: accounts
Examples:
unsubscribe_room¶
Unsubscribe from a MUC conference
Arguments:
- user :: string : User JID
- room :: string : the room to subscribe
Result:
- res :: integer : Status code (
0
on success,1
otherwise)
Module: mod_muc_admin
Examples:
POST /api/unsubscribe_room
{
"user": "tom@localhost",
"room": "room1@conference.localhost"
}
HTTP/1.1 200 OK
""
update 🟤¶
improved in 24.10
Update the given module
To update all the possible modules, use all
.
Arguments:
- module :: string
Result:
- res :: string : Raw result string
Tags: server
Examples:
update_list¶
List modified modules that can be updated
Arguments:
Result:
- modules :: [module::string]
Tags: server
Examples:
user_resources¶
List user's connected resources
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- resources :: [resource::string]
Tags: session
Examples:
POST /api/user_resources
{
"user": "user1",
"host": "example.com"
}
HTTP/1.1 200 OK
[
"tka1",
"Gajim",
"mobile-app"
]
user_sessions_info¶
Get information about all sessions of a user
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- sessions_info :: [{connection::string, ip::string, port::integer, priority::integer, node::string, uptime::integer, status::string, resource::string, statustext::string}]
Tags: session
Module: mod_admin_extra
Examples: