docs.ejabberd.im

Administration 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)

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

Store the database to backup file

Arguments:

  • file :: string : Full path for the destination backup file

Result:

  • res :: string : Raw result string

Examples:

    POST /api/backup
    {
      "file": "/var/lib/ejabberd/database.backup"
    }
    
    HTTP/1.1 200 OK
    "Success"

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)

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

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)

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)

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)

Examples:

    POST /api/check_account
    {
      "user": "peter",
      "host": "myserver.com"
    }
    
    HTTP/1.1 200 OK
    ""

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)

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)

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)

Examples:

    POST /api/clear_cache
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/compile
    {
      "file": "/home/me/srcs/ejabberd/mod_example.erl"
    }
    
    HTTP/1.1 200 OK
    ""

connected_users

List all established sessions

Arguments:

Result:

  • connected_users :: [sessions::string] : List of users sessions

Examples:

    POST /api/connected_users
    {
      
    }
    
    HTTP/1.1 200 OK
    [
      "user1@example.com",
      "user2@example.com"
    ]

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}]

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

Examples:

    POST /api/connected_users_number
    {
      
    }
    
    HTTP/1.1 200 OK
        {"num_sessions": 2}

connected_users_vhost

Get the list of established sessions in a vhost

Arguments:

  • host :: string : Server name

Result:

  • connected_users_vhost :: [sessions::string]

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)

Examples:

    POST /api/convert_to_scram
    {
      "host": "example.com"
    }
    
    HTTP/1.1 200 OK
    ""

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)

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)

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)

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)

Examples:

    POST /api/create_rooms_file
    {
      "file": "/home/ejabberd/rooms.txt"
    }
    
    HTTP/1.1 200 OK
    ""

delete_expired_messages

Delete expired offline messages from database

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/delete_expired_messages
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/delete_mnesia
    {
      "host": "example.com"
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/delete_old_mam_messages
    {
      "type": "all",
      "days": 31
    }
    
    HTTP/1.1 200 OK
    ""

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:

    POST /api/delete_old_messages
    {
      "days": 31
    }
    
    HTTP/1.1 200 OK
    ""

delete_old_push_sessions

Remove push sessions older than DAYS

Arguments:

  • days :: integer

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/delete_old_push_sessions
    {
      "days": 1
    }
    
    HTTP/1.1 200 OK
    ""

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

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

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)

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)

Examples:

    POST /api/destroy_room
    {
      "name": "room1",
      "service": "muc.example.com"
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/destroy_rooms_file
    {
      "file": "/home/ejabberd/rooms.txt"
    }
    
    HTTP/1.1 200 OK
    ""

dump

Dump the database to a text file

Arguments:

  • file :: string : Full path for the text file

Result:

  • res :: string : Raw result string

Examples:

    POST /api/dump
    {
      "file": "/var/lib/ejabberd/database.txt"
    }
    
    HTTP/1.1 200 OK
    "Success"

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)

Examples:

    POST /api/dump_config
    {
      "out": "/tmp/ejabberd.yml"
    }
    
    HTTP/1.1 200 OK
    ""

dump_table

Dump a table to a text file

Arguments:

  • file :: string : Full path for the text file
  • table :: string : Table name

Result:

  • res :: string : Raw result string

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.

Arguments:

  • host :: string : Vhost
  • file :: string : Full path to the destination SQL file

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

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)

Examples:

    POST /api/export_piefxis
    {
      "dir": "/var/lib/ejabberd/"
    }
    
    HTTP/1.1 200 OK
    ""

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)

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)

Examples:

    POST /api/gc
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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)

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)

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
    ""

Get the Erlang cookie of this node

Arguments:

Result:

  • cookie :: string : Erlang cookie used for authentication by ejabberd

Examples:

    POST /api/get_cookie
    {
      
    }
    
    HTTP/1.1 200 OK
        {"cookie": "MWTAVMODFELNLSMYXPPD"}

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

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

Examples:

    POST /api/get_loglevel
    {
      
    }
    
    HTTP/1.1 200 OK
        {"levelatom": "warning"}

get_offline_count

Get the number of unread offline messages

Arguments:

  • user :: string
  • server :: string

Result:

  • value :: integer : Number

Examples:

    POST /api/get_offline_count
    {
      "user": "aaaaa",
      "server": "bbbbb"
    }
    
    HTTP/1.1 200 OK
        {"value": 5}

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}

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

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

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

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

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

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}]

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

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]

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]}]

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

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

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]

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

Examples:

    POST /api/import_dir
    {
      "file": "/var/lib/ejabberd/jabberd14/"
    }
    
    HTTP/1.1 200 OK
    "Success"

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

Examples:

    POST /api/import_file
    {
      "file": "/var/lib/ejabberd/jabberd14.spool"
    }
    
    HTTP/1.1 200 OK
    "Success"

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)

Examples:

    POST /api/import_piefxis
    {
      "file": "/var/lib/ejabberd/example.com.xml"
    }
    
    HTTP/1.1 200 OK
    ""

import_prosody

Import data from Prosody

Note: this method requires ejabberd compiled with optional tools support and package must provide optional luerl dependency.

Arguments:

  • dir :: string : Full path to the Prosody data directory

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/import_prosody
    {
      "dir": "/var/lib/prosody/datadump/"
    }
    
    HTTP/1.1 200 OK
    ""

incoming_s2s_number

Number of incoming s2s connections on the node

Arguments:

Result:

  • s2s_incoming :: integer

Examples:

    POST /api/incoming_s2s_number
    {
      
    }
    
    HTTP/1.1 200 OK
        {"s2s_incoming": 1}

install_fallback

Install the database from a fallback file

Arguments:

  • file :: string : Full path to the fallback file

Result:

  • res :: string : Raw result string

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)

Examples:

    POST /api/join_cluster
    {
      "node": "ejabberd1@machine7"
    }
    
    HTTP/1.1 200 OK
    ""

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)

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

Examples:

    POST /api/kick_user
    {
      "user": "user1",
      "host": "example.com"
    }
    
    HTTP/1.1 200 OK
        {"num_resources": 3}

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)

Examples:

    POST /api/leave_cluster
    {
      "node": "ejabberd1@machine8"
    }
    
    HTTP/1.1 200 OK
    ""

list_cluster

List nodes that are part of the cluster handled by Node

Arguments:

Result:

  • nodes :: [node::string]

Examples:

    POST /api/list_cluster
    {
      
    }
    
    HTTP/1.1 200 OK
    [
      "ejabberd1@machine7",
      "ejabberd1@machine8"
    ]

load

Restore the database from a text file

Arguments:

  • file :: string : Full path to the text file

Result:

  • res :: string : Raw result string

Examples:

    POST /api/load
    {
      "file": "/var/lib/ejabberd/database.txt"
    }
    
    HTTP/1.1 200 OK
    "Success"

man

Generate Unix manpage for current ejabberd version

Arguments:

Result:

  • res :: string : Raw result string

Examples:

    POST /api/man
    {
      
    }
    
    HTTP/1.1 200 OK
    "Success"

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

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

Examples:

    POST /api/mnesia_info
    {
      
    }
    
    HTTP/1.1 200 OK
        {"res": "aaaaa"}

mnesia_table_info

Dump info on Mnesia table state

Arguments:

  • table :: string : Mnesia table name

Result:

  • res :: string

Examples:

    POST /api/mnesia_table_info
    {
      "table": "roster"
    }
    
    HTTP/1.1 200 OK
        {"res": "aaaaa"}

module_check

Check the contributed module repository compliance

Arguments:

  • module :: string : Module name

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/module_check
    {
      "module": "mod_rest"
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/module_install
    {
      "module": "mod_rest"
    }
    
    HTTP/1.1 200 OK
    ""

module_uninstall

Uninstall a contributed module

Arguments:

  • module :: string : Module name

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/module_uninstall
    {
      "module": "mod_rest"
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/module_upgrade
    {
      "module": "mod_rest"
    }
    
    HTTP/1.1 200 OK
    ""

modules_available

List the contributed modules available to install

Arguments:

Result:

  • modules :: [{name::string, summary::string}] : List of tuples with module name and description

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

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)

Examples:

    POST /api/modules_update_specs
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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

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

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)

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)

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

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

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

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}

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}]

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

Examples:

    POST /api/oauth_remove_client
    {
      "client_id": "aaaaa"
    }
    
    HTTP/1.1 200 OK
    "Success"

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

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

Examples:

    POST /api/outgoing_s2s_number
    {
      
    }
    
    HTTP/1.1 200 OK
        {"s2s_outgoing": 1}

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)

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

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)

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}]

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)

Examples:

    POST /api/push_alltoall
    {
      "host": "myserver.com",
      "group": "Everybody"
    }
    
    HTTP/1.1 200 OK
    ""

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)

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)

Examples:

    POST /api/push_roster_all
    {
      "file": "/home/ejabberd/roster.txt"
    }
    
    HTTP/1.1 200 OK
    ""

register

Register a user

Arguments:

  • user :: string : Username
  • host :: string : Local vhost served by ejabberd
  • password :: string : Password

Result:

  • res :: string : Raw result string

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

Examples:

    POST /api/registered_users
    {
      "host": "example.com"
    }
    
    HTTP/1.1 200 OK
    [
      "user1",
      "user2"
    ]

registered_vhosts

List all registered vhosts in SERVER

Arguments:

Result:

  • vhosts :: [vhost::string] : List of available vhosts

Examples:

    POST /api/registered_vhosts
    {
      
    }
    
    HTTP/1.1 200 OK
    [
      "example.com",
      "anon.example.com"
    ]

reload_config

Reload config file in memory

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/reload_config
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

remove_mam_for_user

Remove mam archive for user

Arguments:

  • user :: string : Username
  • host :: string : Server

Result:

  • res :: string : Raw result string

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

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

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/reopen_log
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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

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)

Examples:

    POST /api/restart
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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

Examples:

    POST /api/restart_module
    {
      "host": "myserver.com",
      "module": "mod_admin_extra"
    }
    
    HTTP/1.1 200 OK
        {"res": 0}

restore

Restore the database from backup file

Arguments:

  • file :: string : Full path to the backup file

Result:

  • res :: string : Raw result string

Examples:

    POST /api/restore
    {
      "file": "/var/lib/ejabberd/database.backup"
    }
    
    HTTP/1.1 200 OK
    "Success"

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

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

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

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

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)

Examples:

    POST /api/rotate_log
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

send_direct_invitation

Send a direct invitation to several destinations

Since ejabberd 20.10, 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)

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)

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)

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)

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)

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)

Examples:

    POST /api/set_loglevel
    {
      "loglevel": "debug"
    }
    
    HTTP/1.1 200 OK
    ""

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

Examples:

    POST /api/set_master
    {
      "nodename": "ejabberd@machine7"
    }
    
    HTTP/1.1 200 OK
    "Success"

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)

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)

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)

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)

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)

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)

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
  • name :: string : Group name
  • description :: string : Group description
  • display :: string : Groups to display

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/srg_create
    {
      "group": "group3",
      "host": "myserver.com",
      "name": "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)

Examples:

    POST /api/srg_delete
    {
      "group": "group3",
      "host": "myserver.com"
    }
    
    HTTP/1.1 200 OK
    ""

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

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

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

Examples:

    POST /api/srg_list
    {
      "host": "myserver.com"
    }
    
    HTTP/1.1 200 OK
    [
      "group1",
      "group2"
    ]

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)

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)

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

Examples:

    POST /api/stats
    {
      "name": "registeredusers"
    }
    
    HTTP/1.1 200 OK
        {"stat": 6}

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

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

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}]

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}]

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

Examples:

    POST /api/status_num
    {
      "status": "dnd"
    }
    
    HTTP/1.1 200 OK
        {"users": 23}

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

Examples:

    POST /api/status_num_host
    {
      "host": "myserver.com",
      "status": "dnd"
    }
    
    HTTP/1.1 200 OK
        {"users": 23}

stop

Stop ejabberd gracefully

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/stop
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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)

Examples:

    POST /api/stop_kindly
    {
      "delay": 60,
      "announcement": "Server will stop now."
    }
    
    HTTP/1.1 200 OK
    ""

stop_s2s_connections

Stop all s2s outgoing and incoming connections

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/stop_s2s_connections
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

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

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.

Examples:

    POST /api/unban_ip
    {
      "address": "::FFFF:127.0.0.1/128"
    }
    
    HTTP/1.1 200 OK
        {"unbanned": 3}

unregister

Unregister a user

Arguments:

  • user :: string : Username
  • host :: string : Local vhost served by ejabberd

Result:

  • res :: string : Raw result string

Examples:

    POST /api/unregister
    {
      "user": "bob",
      "host": "example.com"
    }
    
    HTTP/1.1 200 OK
    "Success"

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)

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

Examples:

    POST /api/update
    {
      "module": "mod_vcard"
    }
    
    HTTP/1.1 200 OK
    "Success"

update_list

List modified modules that can be updated

Arguments:

Result:

  • modules :: [module::string]

Examples:

    POST /api/update_list
    {
      
    }
    
    HTTP/1.1 200 OK
    [
      "mod_configure",
      "mod_vcard"
    ]

update_sql

Convert SQL DB to the new format

Arguments:

Result:

  • res :: integer : Status code (0 on success, 1 otherwise)

Examples:

    POST /api/update_sql
    {
      
    }
    
    HTTP/1.1 200 OK
    ""

user_resources

List user's connected resources

Arguments:

  • user :: string : User name
  • host :: string : Server name

Result:

  • resources :: [resource::string]

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}]

Examples:

    POST /api/user_sessions_info
    {
      "user": "peter",
      "host": "myserver.com"
    }
    
    HTTP/1.1 200 OK
    [
      {
        "connection": "c2s",
        "ip": "127.0.0.1",
        "port": 42656,
        "priority": 8,
        "node": "ejabberd@localhost",
        "uptime": 231,
        "status": "dnd",
        "resource": "tka",
        "statustext": ""
      }
    ]