API Reference¶
add_rosteritem¶
Add an item to a user's roster (supports ODBC)
Group can be several groups separated by ; for example: "g1;g2;g3"
Arguments:
- localuser :: string : User name
- localhost :: string : Server name
- user :: string : Contact user name
- host :: string : Contact server name
- nick :: string : Nickname
- group :: string : Group
- subs :: string : Subscription
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/add_rosteritem
{
"localuser": "user1",
"localhost": "myserver.com",
"user": "user2",
"host": "myserver.com",
"nick": "User 2",
"group": "Friends",
"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¶
Ban an account: kick sessions and set random password
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)
Tags: accounts
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": "muc.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 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": "muc.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
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)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/create_room_with_opts
{
"name": "room1",
"service": "muc.example.com",
"host": "localhost",
"options": [
{
"name": "members_only",
"value": "true"
}
]
}
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)
Tags: purge
Examples:
delete_expired_pubsub_items¶
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)
Tags: purge
Module: mod_mam
Examples:
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)
Tags: purge
Examples:
delete_old_pubsub_items¶
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: access_rules: protect_old_users: - allow: admin - deny: all
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: access_rules: delete_old_users: - deny: admin - allow: all
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 command.
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¶
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
- 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¶
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_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_offline_count¶
Get the number of unread offline messages
Arguments:
- user :: string
- server :: 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": "muc.example.com",
"jid": "user1@example.com"
}
HTTP/1.1 200 OK
{"affiliation": "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": "muc.example.com"
}
HTTP/1.1 200 OK
[
{
"username": "user1",
"domain": "example.com",
"affiliation": "member",
"reason": "member"
}
]
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": "muc.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": "muc.example.com"
}
HTTP/1.1 200 OK
{"occupants": 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": "muc.example.com"
}
HTTP/1.1 200 OK
[
{
"name": "members_only",
"value": "true"
}
]
get_roster¶
Get roster of a local user
Arguments:
- user :: string
- server :: string
Result:
- contacts :: [{jid::string, nick::string, subscription::string, ask::string, group::string}]
Tags: roster
Module: mod_admin_extra
Examples:
POST /api/get_roster
{
"user": "aaaaa",
"server": "bbbbb"
}
HTTP/1.1 200 OK
[
{
"jid": "aaaaa",
"nick": "bbbbb",
"subscription": "ccccc",
"ask": "ddddd",
"group": "eeeee"
},
{
"jid": "fffff",
"nick": "ggggg",
"subscription": "hhhhh",
"ask": "iiiii",
"group": "jjjjj"
}
]
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
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/get_subscribers
{
"name": "room1",
"service": "muc.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@muc.example.com",
"room2@muc.example.com"
]
get_user_subscriptions¶
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]}]
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/get_user_subscriptions
{
"user": "tom",
"host": "example.com"
}
HTTP/1.1 200 OK
[
{
"roomjid": "room1@muc.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 at https://xmpp.org/extensions/xep-0054.html
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
{"content": "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 at https://xmpp.org/extensions/xep-0054.html
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
{"content": "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 at https://xmpp.org/extensions/xep-0054.html
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"
]
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 compiled with --enable-lua and include the optional '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'.
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¶
Join this node into the cluster handled by Node
This command works only with ejabberdctl, not mod_http_api or other code that runs inside the same ejabberd node that will be joined.
Arguments:
- node :: string : Nodename of the node to join
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
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¶
Disconnect user's active sessions
Arguments:
- user :: string : User name
- host :: string : Server name
Result:
- num_resources :: integer : Number of resources that were kicked
Tags: session
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 nodes that are part of the cluster handled by Node
Arguments:
Result:
- nodes :: [node::string]
Tags: cluster
Examples:
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' and 'install_fallback'.
Arguments:
- file :: string : Full path to the text file
Result:
- res :: string : Raw result string
Tags: mnesia
Examples:
man¶
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_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 ('global' to get 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": "muc.example.com"
}
HTTP/1.1 200 OK
[
"room1@muc.example.com",
"room2@muc.example.com"
]
muc_online_rooms_by_regex¶
List existing rooms ('global' to get all vhosts) by regex
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": "muc.example.com",
"regex": "^prefix"
}
HTTP/1.1 200 OK
[
{
"jid": "room1@muc.example.com",
"public": "true",
"participants": 10
},
{
"jid": "room2@muc.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": "muc.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": "muc.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:
POST /api/num_resources
{
"user": "peter",
"host": "myserver.com"
}
HTTP/1.1 200 OK
{"resources": 5}
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¶
Issue an oauth token for the given jid
Arguments:
- jid :: string : Jid for which issue token
- ttl :: integer : Time to live of generated token in seconds
- scopes :: string : List of scopes to allow, separated by ';'
Result:
- result :: {token::string, scopes::string, expires_in::string}
Tags: oauth
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",
"expires_in": "ccccc"
}
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¶
Revoke authorization for a token (only Mnesia)
Arguments:
- token :: string
Result:
- tokens :: [{token::string, user::string, scope::string, expires_in::string}] : List of remaining tokens
Tags: oauth
Examples:
POST /api/oauth_revoke_token
{
"token": "aaaaa"
}
HTTP/1.1 200 OK
[
{
"token": "aaaaa",
"user": "bbbbb",
"scope": "ccccc",
"expires_in": "ddddd"
},
{
"token": "eeeee",
"user": "fffff",
"scope": "ggggg",
"expires_in": "hhhhh"
}
]
outgoing_s2s_number¶
Number of outgoing s2s connections on the node
Arguments:
Result:
- s2s_outgoing :: integer
Tags: statistics s2s
Examples:
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
{"res": "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 options - subs: subscription type - asks: pending subscription - users: the JIDs of the local user - contacts: the JIDs of the contact in the roster
*** Mnesia:
Allowed values in the arguments: ACTION = list | delete SUBS = SUB[:SUB] | any SUB = none | from | to | both ASKS = ASK[:ASK] | any ASK = none | out | in USERS = JID[:JID] | any CONTACTS = JID[:JID] | any 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:
Allowed values in the arguments: ACTION = list | delete SUBS = any | none | from | to | both ASKS = any | none | out | in USERS = JID CONTACTS = JID 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. Example: [{<<"user1">>, <<"localhost">>, <<"Workers">>, <<"User 1">>}, {<<"user2">>, <<"localhost">>, <<"Workers">>, <<"User 2">>}]. When using UTF8 character encoding add /utf8 to certain string. Example: [{<<"user2">>, <<"localhost">>, <<"Workers"/utf8>>, <<"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 the log files after being renamed
This can be useful when an external tool is used for log rotation. See https://docs.ejabberd.im/admin/guide/troubleshooting/#log_files
Arguments:
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: logs
Examples:
request_certificate¶
Requests certificates for all or the specified domains: all | domain1,domain2,...
Arguments:
- domains :: string : Domains for which to acquire a certificate
Result:
- res :: string : Raw result string
Tags: acme
Examples:
POST /api/request_certificate
{
"domains": "all | 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:
POST /api/resource_num
{
"user": "peter",
"host": "myserver.com",
"num": 2
}
HTTP/1.1 200 OK
{"resource": "Psi"}
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 restarted
- 1: error: module not loaded
- 2: code not reloaded, but module restarted
Tags: erlang
Module: mod_admin_extra
Examples:
POST /api/restart_module
{
"host": "myserver.com",
"module": "mod_admin_extra"
}
HTTP/1.1 200 OK
{"res": 0}
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'.
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¶
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:
- rooms :: [room::string] : List of empty rooms that have been destroyed
Tags: muc
Module: mod_muc_admin
Examples:
POST /api/rooms_empty_destroy
{
"service": "muc.example.com"
}
HTTP/1.1 200 OK
[
"room1@muc.example.com",
"room2@muc.example.com"
]
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": "muc.example.com"
}
HTTP/1.1 200 OK
[
"room1@muc.example.com",
"room2@muc.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": "muc.example.com",
"days": 31
}
HTTP/1.1 200 OK
[
"room1@muc.example.com",
"room2@muc.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": "muc.example.com",
"days": 31
}
HTTP/1.1 200 OK
[
"room1@muc.example.com",
"room2@muc.example.com"
]
rotate_log¶
Rotate the log files
Arguments:
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: logs
Examples:
send_direct_invitation¶
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 also be: none. Users JIDs are separated with :
Arguments:
- name :: string : Room name
- service :: string : MUC service
- password :: string : Password, or none
- reason :: string : Reason text, or none
- users :: string : Users JIDs separated with : characters
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/send_direct_invitation
{
"name": "room1",
"service": "muc.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 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: 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
Arguments:
- loglevel :: string : Desired logging level: none | emergency | alert | critical | error | warning | notice | info | debug
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: logs
Examples:
set_master¶
Set master node of the clustered Mnesia tables
If you provide as nodename "self", 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¶
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 :: string : Priority, provide this value as an integer
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: session
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": "muc.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 at https://xmpp.org/extensions/xep-0054.html
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 at https://xmpp.org/extensions/xep-0054.html
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 at https://xmpp.org/extensions/xep-0054.html
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_create¶
Create a Shared Roster Group
If you want to specify several group identifiers in the Display argument, put \ " around the argument and separate the identifiers with \ \ n For example: ejabberdctl srg_create group3 myserver.com name desc \"group1\ngroup2\"
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
- label :: string : Group name
- description :: string : Group description
- display :: string : Groups to display
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: shared_roster_group
Module: mod_admin_extra
Examples:
POST /api/srg_create
{
"group": "group3",
"host": "myserver.com",
"label": "Group3",
"description": "Third group",
"display": "group1\\ngroup2"
}
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_info¶
Get info of a Shared Roster Group
Arguments:
- group :: string : Group identifier
- host :: string : Group server name
Result:
- information :: [{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_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 statistical value: 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 statistical value for this host: registeredusers onlineusers
Arguments:
- name :: string : Statistic name
- host :: string : Server JID
Result:
- stat :: integer : Integer statistic value
Tags: statistics
Module: mod_admin_extra
Examples:
POST /api/stats_host
{
"name": "registeredusers",
"host": "example.com"
}
HTTP/1.1 200 OK
{"stat": 6}
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¶
Subscribe to a MUC conference
Arguments:
- user :: string : User JID
- nick :: string : a user's nick
- room :: string : the room to subscribe
- nodes :: string : nodes separated by commas: ,
Result:
- nodes :: [node::string] : The list of nodes that has subscribed
Tags: muc_room
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"
]
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
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)
Tags: muc_room
Module: mod_muc_admin
Examples:
POST /api/unsubscribe_room
{
"user": "tom@localhost",
"room": "room1@conference.localhost"
}
HTTP/1.1 200 OK
""
update¶
Update the given module, or use the keyword: 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:
update_sql¶
Convert PostgreSQL DB to the new format
Arguments:
Result:
- res :: integer : Status code (0 on success, 1 otherwise)
Tags: sql
Module: mod_admin_update_sql
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: