IM Soap API Reference
=======================
A few terms:
ROSTER: your list of buddies
CHAT: an ongoing threaded conversation between you and one or more
other participants. Some chats are 1:1 and some are multi-user (part
of a conference room)
GATEWAY: a service that allows the user to connect to 3rd party IM
services, e.g. the Yahoo! IM service.
ROLE: In MUC chat, this is something you have while you're IN the chat room
- Moderator, None, Participant, Visitor
AFFILIATION: in MUC chat, a description of the rights you have to the room, not
related to being actually "in" the room.
- Owner, Admin, Member, Outcast, None
------------------------------------------
Additional IM error codes (see soap.txt for explanation of error
codes):
im.INVALID_ADDRESS - IM address is invalid (missing @ sign and
not able to find in default domain)
------------------------------------------
IMGetRoster -- get buddy list
-----------
// MY current presence value
[ // 0 or more active chats
// participants in this chat
[]*
]*
Roster data is sent asynchronously from the server (see "Asynchronous Roster Response" below)
in the next notification block.
IMSubscribe -- subscribe to someone's presence / modify subscription
-----------
// If the user specified an alias, the server will resolve the alias
// to a canonical address -- and add the canonical address to the
// Buddy List. The addr returned might be different than the
// requested addr
IMAuthorizeSubscribe -- used to OK another user adding you to their buddy list
-------------------- send this in response to a notification
Optionally, add this user to my buddy list as well
IMSetPresence -- modify your presence state
-------------
[
]+ // if multiple, each must have a different lang
IMSendMessage -- send a new message, optional chat parameter
-------------
To an existing chat:
[
Plaintext Subject
]* // HTML
PLAINTEXT
[
HTML text (xhtml required: balance tags)
]
[]
...OR create a new chat:
[SUBJECT]* // HTML
[BODY] // HTML
[]
**Send a blank message to indicate/stop typing indicator by itself**
IMGetChat -- return the chat history (param = num messages)
---------
// chat unknown (server restart? server flushed it due to idleness?)
// chat known:
// PARTICIPANT
*
[SUBJECT]* // HTML
[PLAINTEXT BODY] // plaintext
[HTML BODY]
IMJoinConferenceRoom
---------------------
-- This API joins specified conference room, creating it if it didn't
already exists.
-- The API returns a CHAT. The ,
, and APIs can be used on that
chat.
-- Use the "threadID" paremeter to to send a
message to this existing chat.
addr: the full address of the room. This should be of the form
ROOMNAME@CONFERENCE_SERVICE - eg
myroom@conference.myhost.com See IMListConferenceRooms
as a way to get a list of CONFERENCE_SERVICEs available
thread: used for converting a 1:1 chat into a MUC
nickname: the "nickname" used for you in the room. All users
in a room are required to have a unique nickname in
that room. If you don't specify one, the server will
use your bare username (the part of your name before
the @ sign) as your nickname. If you get a
"NicknameConflict" response, you will have to try a
different name.
password: used to enter password-protected rooms
request to the room in order to allow
other people to enter the room
STATUS codes:
NewRoomCreated // this is a NEW, LOCKED, ROOM. You must configure it.
// These are all informational, for future use only. You can ignore them
// for now:
EnteringRoomJIDAvailable
AffiliationChange
ShowsUnavailableMembers
DoesNotShowUnavailableMembers
ConfigurationChange
OccupantPresence
LoggingEnabled
LoggingDisabled
NonAnonymous
SemiAnonymous
FullyAnonymous
RoomnickChanged // your nickname is assigned or changed
YouHaveBeenBanned // 301 - you have been banned
NewRoomNickname // 303
KickedFromRoom // 307 -- you have been kicked from room
RemovedForAffiliationChange // 321 - you have been removed b/c your affiliation changed
RemovedForMembersOnly // 322 - room is now members-only, and you aren't a member
RemovedShutdown // 332 - system or conference service is shutting down
ERROR codes:
PasswordRequired - couldn't enter room password required
Banned - room owner has banned you from the room
NoSuchRoom -
NotAllowed - Room doesn't exist, and you're not allowed to create a new one
MustUseReservedRoomnick -
NotAMember - Room is invite-only, and you aren't a member
NicknameConflict - Someone else is already using your nickname
MaxUsers - Room has reached capacity
Unknown
**also look for notification: **
IMGetChatConfiguration
-----------------------
Get all configuration information about the specified chat. Note that
1:1 chats will have almost no configuration while MUC chats have many config
thread: a threadId from a chat you have already joined (see IMJoinChat)
addr: a direct address for the conference room (e.g. roomname@conference.domain.com)
requestOwnerConfig: if TRUE, then attempt to get the "owner's" config for the room, all values private or public.
you can only get the owner's config for a room you have joined (thread specified)
you can only get the owner's config if you are an owner of the room
ERROR_CODES:
not_allowed: you requested the owner config information but you are not an owner of this room
no_response_from_remote: the conference service did not respond to our requests
not_a_conference_room: the requested conference room doesn't exist, or you don't have permission to access it in that way
[VALUE]*
[
[VALUE]+
]*
isMUC: if TRUE then this is a chatroom, otherwise it is a 1:1 chat
Config Vars:
------------
open boolean room is unlocked and may be entered?
creationdate string date this room was created
publicroom boolean room is hidden from RoomList
moderated boolean chat is moderated
persistent boolean room not deleted if server restarts
membersonly boolean only members may join, only admins can invite
nonanonymous boolean if TRUE, then users are not anonymous
semianonymous boolean no idea what this means
passwordprotect boolean is a password required to join
password string the password for the room (make sure you set
passwordprotect to be '1' if you want the password
enabled)
numoccupants integer number of people currently in the room
maxusers integer max # users allowed
longname string natural language name of room - this is the
'name' returned for the room via
description string short description of room
subject string current subject in room
subjectmodifyable boolean can the subject be modified by participants?
allowinvites boolean allow Occupants to invite others
presencebroadcast MULTI-string list of Roles which get presence updates
whois MULTI-string list of Affiliations who may discover real JIDs of Occupants
owners MULTI-string list of room owners (can change config)
admins MULTI-string list of users with ADMIN affiliation
enablelogging boolean log room conversations
reservednick boolean only login with registered nickname?
canchangenick boolean allow occupants to change nicknames
allowregister boolean allow users to register with the room
FUTRUE - either don't work, or I haven't verified they work...but they're in the XMPP spec
------
getmemberlist MULTI-string list of Roles/Affiliations that may retrieve member list
contactid string - extended - roominfo_contactjid = contact address for room
logs_url string - extended - roominfo_logs - URL for archived discussions from room
IMModifyChat -- add/remove users from multi-user chat, adjust save preferences, etc
------------
[VALUE]*
[[VALUE]*]*
--- see IMGetChatConfiguration for list of supported variables
RESPONSES:
// chat unknown (server restart? server flushed it due to idleness?)
// use to join/create a MUC
// you do not have permission to modify this chat (not owner/admin)
// successful
IMGetPrivacyList -- request the privacy list
-----------------
// gets default list if
// no name specified
// response in 'privacy' notification below
IMSetPrivacyList -- sets the list
-------------------
// use default list if no name specified
[
// Entries are evaluated by the server in increasing order (1 then 2 then 3 ...)
//
// EG, this will allow 'foo@bar.com' but block all others @bar.com:
//
IMGatewayList - gateways to external IM services
--------------
[ ] ]
connectedState is one of:
bad_auth -- auth is bad, will not try to reconnect
intentionally_offline -- user's local im presence is "offline" so not connected
disabled -- the user's account has been disabled, we will not try to reconnect
(this is probably b/c we detected the user logged into the service
directly from another location)
online
shutdown -- shutting down
start -- just created, will attempt first connect soon
trying_to_connect -- connection attempt in progress
NOT_IMPLEMENTED_YET: booted_by_other_login -- will not retry connect: someone has connected to our account has connected from another place
IMGatewayRegister
-----------------
// tell the service to try a reconnect right now, also re-enable if the service was in the disabled state
IMSetIdle
-----------------
-- idleTime is number of seconds since last user action. Client should
make a best-effort to calculate this, but is free to return "0" if
unsupported.
-- Throws ServiceException.SESSION_REQUIRED if there is no session
referenced (a session MUST be active for this API to be used)
When calculating presence, the sever will look at the "idle" values of
all active web client sessions. If all sessions are "idle" then the
server will update the user's status to "away".
The web client must be careful to unset the "idle" status when the
user comes back, otherwise the user's presence will be stuck in the
"Away" state and the user won't understand why.
============================================
CONFERENCE APIS
- A "conference service" can host one or more Conferences. A user
can join a Conference (thereby creating a "Chat")
============================================
See: IMJoinConferenceRoomRequest
See: IMModifyChatRequest
See: IMGetChatConfiguration
IMListConferenceServices
-------------------------
- List all the known conference services within our cloud
List all the known conference services (MUC servers)
IMListConferenceRooms
----------------------
- List all the rooms currently active in a given conference service
List all the available conference rooms on the requested server.
Rooms can be joined via the API.
============================================================
IM NOTIFICATIONS
============================================================
//
// In soap header block (see soap.txt):
//
[
...
[]
[]
[]
[
[
// Asynchronous Roster Response
[]* // see "subscribed" notification below
[]* // see "unsubscribed" notification below
...
]?
'ask' means we are pending a response to our request to subscribe/unsubscribe
---> EG: (subscription="none" ask="subscribe") means we're waiting
for a response to subscribe, but we haven't received one yet
[
// subscription is ACTIVE (you are receiving their presence)
]*
[
// subscription is NOT ACTIVE (you are NOT currently receiving their presence information)
]*
[
// NEW MESSAGE RECEIVED:
[SUBJECT]
[BODY]
[]
]*
[
// Presence update for a specific user
]*
[
// User wants to add you to their buddy list (see above)
]*
[
// specified user entered the chat
]*
[
// presence update for chat user
]*
[
// specified user left the chat
]*
[
// specified chat has been closed
]*
[
// An invitation to join a group chat:
INVITATION_MESSAGE
]*
[
// interop gateway has succeeded/failed to connect us, see above for more info
] />
]*
[
// your account has connected to the interop service from another location
]
[
// privacy (block/allow) list
[
]
]
]?
]
MESSAGE_ERROR_CONDITIONS:
forbidden
internal_server_error
item_not_found - user not found (usually NOT sent
jid_malformed - address is malformed
not_acceptable - server didn't like your message
(e.g. bad-word filter rejected it)
not_allowed - you're not allowed to send a message there
payment_required
recipient_unavailable - that user is temporarily unavailable
redirect - that user is at a different address
remote_server_not_found - could not contact the user's domain
remote_server_timeout
resource_constraint - the system is too busy right now
service_unavailable - messages are not accepted by the service
undefined_condition