{ "openapi": "3.1.0", "info": { "title": "ICQ Web API", "version": "1.0.0", "summary": "Build your own ICQ client: sign in, chat, presence and buddy lists over plain HTTP.", "description": "The public Web API of the open-oscar-server (github.com/mk6i/open-oscar-server) as it runs at https://jimm.online/webapi. Every response is wrapped in {\"response\": {\"statusCode\", \"statusText\", \"data\"}} — read statusCode from the envelope, it is not always the HTTP status. Guide: https://jimm.online/en/developers", "license": { "name": "MIT", "identifier": "MIT" } }, "externalDocs": { "description": "Guide and live console", "url": "https://jimm.online/en/developers" }, "servers": [ { "url": "https://jimm.online/webapi" } ], "tags": [ { "name": "auth", "description": "Sign-in. Trade a UIN and password for a token. The password travels once; the token does the rest." }, { "name": "session", "description": "Session & events. Going online, long-polling the event stream, and signing off." }, { "name": "im", "description": "Messaging. Sending messages, the typing indicator and this session’s history." }, { "name": "presence", "description": "Presence & profile. Your own status, x-status and profile, and other people’s presence." }, { "name": "buddylist", "description": "Buddy list. The buddy list lives on the server: groups, buddies, nicknames. Every change arrives as a buddylist event in all your sessions." }, { "name": "preference", "description": "Preferences & privacy. Server-side account preferences and the allow and block lists." }, { "name": "directory", "description": "Member directory. The member directory: search by UIN or name, and directory profiles." }, { "name": "expressions", "description": "Buddy icons. Fetching and uploading buddy icons." } ], "paths": { "/auth/clientLogin": { "post": { "operationId": "clientLogin", "tags": [ "auth" ], "summary": "Sign in with a UIN and password", "description": "Checks a UIN and password and returns the token `token.a`, which startSession takes. The body is a plain `application/x-www-form-urlencoded` form: the server does not read JSON and answers 400. You can keep the token instead of the password; by default it lives 24 hours.\n\n- **330** — Wrong UIN or password (`statusDetailCode: 3011`, HTTP 401).\n\n- **460** — UIN or password missing (HTTP 400).\n\n- **462** — Bad `tokenType` (HTTP 400).", "parameters": [], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "token": { "a": "AAAAAGdQ…base64url…", "expiresIn": "86400" }, "loginId": "123456789", "screenName": "123456789", "sessionSecret": "q1w2e3…", "hostTime": 1761130000, "tokenExpiresIn": 86400 } } } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "s": { "type": "string", "description": "The UIN (or `username`).", "examples": [ "123456789" ] }, "pwd": { "type": "string", "description": "The password (or `password`).", "examples": [ "secret" ] }, "devId": { "type": "string", "description": "Your client’s name. Shows up in the server log; defaults to `WebAIM`.", "examples": [ "my-client" ] }, "tokenType": { "type": "string", "description": "Token lifetime: `shortterm` (24 h, the default), `longterm` (365 days) or a number of seconds.", "examples": [ "shortterm" ] }, "f": { "type": "string", "enum": [ "json", "xml", "amf3" ], "description": "Response format. A POST sends it in the body.", "examples": [ "json" ] } }, "required": [ "s", "pwd" ] } } } } } }, "/auth/getInfo": { "get": { "operationId": "getInfo", "tags": [ "auth" ], "summary": "Check a token", "description": "Tells whether a saved token is still good and whose it is. Handy at client start-up: anything but 200 means ask for the password again.\n\n- **401** — Token refused: expired, damaged or not from clientLogin.\n\n- **330** — The sign-in is older than `reqAuthFreshness` allows.", "parameters": [ { "name": "a", "in": "query", "required": true, "description": "The token from clientLogin.", "schema": { "type": "string" }, "example": "AAAAAGdQ…base64url…" }, { "name": "reqAuthFreshness", "in": "query", "required": false, "description": "Maximum age of the sign-in, in seconds (default 86400). Older means 330.", "schema": { "type": "integer" }, "example": "86400" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "userData": { "loginId": "123456789", "displayName": "123456789" } } } } } } } } } }, "/aim/startSession": { "get": { "operationId": "startSession", "tags": [ "session" ], "summary": "Go online", "description": "Opens a session and puts you online, so your contacts see you arrive. Returns `aimsid`, which every other method takes. `events` lists what you want to hear about. The starting state (buddy list, your own info) comes right in the response and again as the first events of the stream. Offline messages arrive as `offlineIM` events and are deleted from the server as they go, so keep them yourself. Stop polling and the session closes after 150 seconds.\n\n- **401** — Token missing or expired.\n\n- **503** — The server could not open a session.", "parameters": [ { "name": "a", "in": "query", "required": true, "description": "The token from clientLogin.", "schema": { "type": "string" }, "example": "AAAAAGdQ…base64url…" }, { "name": "events", "in": "query", "required": false, "description": "Comma-separated events to subscribe to. Defaults to `buddylist,presence,im,sentIM`.", "schema": { "type": "string" }, "example": "im,offlineIM,sentIM,typing,presence,buddylist,myInfo,sessionEnded" }, { "name": "clientName", "in": "query", "required": false, "description": "Your client’s name.", "schema": { "type": "string" }, "example": "MyClient" }, { "name": "clientVersion", "in": "query", "required": false, "description": "Your client’s version.", "schema": { "type": "string" }, "example": "1.0" }, { "name": "timeout", "in": "query", "required": false, "description": "Default long-poll timeout, **in seconds** (60).", "schema": { "type": "integer" }, "example": "60" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "aimsid": "0123456789abcdef.123456789", "ts": 1761130000, "fetchTimeout": 60000, "timeToNextFetch": 500, "fetchBaseURL": "https://jimm.online/webapi/aim/fetchEvents?aimsid=0123456789abcdef.123456789&seqNum=0", "myInfo": { "aimId": "123456789", "displayId": "123456789", "friendly": "123456789", "state": "online", "userType": "icq", "bot": false, "service": "icq", "capabilities": [], "buddyIcon": "https://jimm.online/webapi/expressions/get?t=123456789&type=buddyIcon" }, "events": { "buddylist": { "groups": [ { "name": "Друзья", "id": 1, "buddies": [ { "aimId": "987654321", "displayId": "987654321", "friendly": "Вася", "state": "online", "statusMsg": "на связи", "onlineTime": 1761120000, "userType": "icq", "service": "icq", "buddyIcon": "https://jimm.online/webapi/expressions/get?t=987654321&type=buddyIcon", "bot": false } ] } ] } }, "wellKnownUrls": { "webApiBase": "https://jimm.online/webapi/", "fetchBaseURL": "https://jimm.online/webapi/aim/fetchEvents" } } } } } } } } } }, "/aim/fetchEvents": { "get": { "operationId": "fetchEvents", "tags": [ "session" ], "summary": "Fetch events (long-poll)", "description": "The client’s main loop. The request waits until there are events newer than `seqNum` or `timeout` runs out, then returns them as a batch (possibly empty). Make the next request with `seqNum = lastSeqNum` after `timeToNextFetch` ms. Every call keeps the session alive. The server keeps up to the last 1000 events.\n\n- **401** — The session is closed or expired. Start over with startSession.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "seqNum", "in": "query", "required": false, "description": "The last event number you saw; 0 for everything.", "schema": { "type": "integer" }, "example": "0" }, { "name": "timeout", "in": "query", "required": false, "description": "How long to wait, **in milliseconds**, 60000 at most.", "schema": { "type": "integer" }, "example": "60000" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "events": [ { "type": "im", "seqNum": 7, "timestamp": 1761130042, "eventData": { "source": { "aimId": "987654321", "displayId": "987654321", "friendly": "Вася", "userType": "icq", "state": "online" }, "message": "Привет! Как дела?", "msgId": "9c2e41d07a3b55f1", "timestamp": 1761130042, "imf": "plain", "autoresponse": false } } ], "lastSeqNum": 7, "timeToNextFetch": 500, "fetchBaseURL": "https://jimm.online/webapi/aim/fetchEvents?aimsid=0123456789abcdef.123456789&seqNum=7" } } } } } } } } }, "/aim/endSession": { "get": { "operationId": "endSession", "tags": [ "session" ], "summary": "Sign off", "description": "Closes the session; your contacts see you leave. In a browser, `navigator.sendBeacon` from `pagehide` works well.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/aim/startOSCARSession": { "get": { "operationId": "startOSCARSession", "tags": [ "session" ], "summary": "Address and cookie for native OSCAR", "description": "For a full OSCAR-over-TCP client: sign in over HTTP, then connect straight to BOS with the returned `host`, `port` and `cookie`, skipping the in-protocol password step.\n\n- **401** — Token missing or expired.", "parameters": [ { "name": "a", "in": "query", "required": true, "description": "The token from clientLogin.", "schema": { "type": "string" }, "example": "AAAAAGdQ…base64url…" }, { "name": "useTLS", "in": "query", "required": false, "description": "Ask for the TLS port. Falls back to plain if the server has none.", "schema": { "type": "boolean" }, "example": "false" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "host": "icq.jimm.online", "port": 5190, "cookie": "AAAAAGdQ…base64…" } } } } } } } } }, "/im/sendIM": { "get": { "operationId": "sendIM", "tags": [ "im" ], "summary": "Send a message", "description": "Accepts GET or a POSTed form. From a browser prefer GET: it is a “simple” request and needs no CORS preflight. Pass `offlineIM=true` so a message to someone who is offline is stored and delivered when they sign in. It changes nothing for an online recipient, so it is safe to always send. Your own sessions get a copy as a `sentIM` event.\n\n- **602** — Not delivered: the recipient is offline and no `offlineIM`, their offline box is full, or you blocked them. HTTP is still 200 — read `statusCode`.\n\n- **430** — Too fast. Wait `Retry-After` seconds.\n\n- **400** — Missing `t` or `message`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": true, "description": "Recipient’s UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "message", "in": "query", "required": true, "description": "The text. Up to ~4000 bytes.", "schema": { "type": "string" }, "example": "Привет! 👋" }, { "name": "offlineIM", "in": "query", "required": false, "description": "Store it if the recipient is offline.", "schema": { "type": "boolean" }, "example": "true" }, { "name": "autoResponse", "in": "query", "required": false, "description": "`1` marks an auto-reply (an away message).", "schema": { "type": "string" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "msgId": "5f1c0e2a-9b3d-4c11-8000-0a1b2c3d4e5f", "state": "delivered", "timestamp": 1761130050 } } } } } } } } }, "/im/setTyping": { "get": { "operationId": "setTyping", "tags": [ "im" ], "summary": "Typing indicator", "description": "Tells the other side you are typing. Sent only if their client asked for typing notices; otherwise the server quietly answers HTTP 200 with an empty body, which is not an error. Don’t send more than once every couple of seconds.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": true, "description": "The other side’s UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "typingStatus", "in": "query", "required": false, "description": "`typing`, `typed` (paused) or `none` (cleared).", "schema": { "type": "string", "enum": [ "typing", "typed", "none" ] }, "example": "typing" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/imlog/fetchStoredIMs": { "get": { "operationId": "fetchStoredIMs", "tags": [ "im" ], "summary": "This session’s history", "description": "Messages with one person that went through **this** session. The server keeps no history across sessions: sign in again and the list starts empty. Keep permanent history on the client.\n\n- **400** — Missing `to`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "to", "in": "query", "required": true, "description": "The other side’s UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "nToGet", "in": "query", "required": false, "description": "How many to return.", "schema": { "type": "integer" }, "example": "50" }, { "name": "sortOrder", "in": "query", "required": false, "description": "`asc` or `desc`.", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "desc" }, { "name": "startTime", "in": "query", "required": false, "description": "Not before (unix time).", "schema": { "type": "integer" } }, { "name": "endTime", "in": "query", "required": false, "description": "Not after (unix time).", "schema": { "type": "integer" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "msgs": [ { "sender": "987654321", "message": "Привет!", "msgId": "9c2e41d07a3b55f1", "date": 1761130042 } ] } } } } } } } } }, "/presence/get": { "get": { "operationId": "getPresence", "tags": [ "presence" ], "summary": "Presence of people or the whole list", "description": "With `bl=1`, the whole buddy list with live presence. With `t`, the presence of given people (up to 32), whether or not they are on your list — good for a preview card before adding someone.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": false, "description": "UINs, comma-separated (or repeat `t`). Up to 32.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "bl", "in": "query", "required": false, "description": "`1` returns the whole buddy list by group.", "schema": { "type": "string" } }, { "name": "profileMsg", "in": "query", "required": false, "description": "`1` adds the profile text.", "schema": { "type": "string" }, "example": "1" }, { "name": "mdir", "in": "query", "required": false, "description": "Add directory data (name, city).", "schema": { "type": "boolean" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "users": [ { "aimId": "987654321", "displayId": "987654321", "friendly": "Вася", "state": "online", "statusMsg": "на связи", "onlineTime": 1761120000, "userType": "icq", "service": "icq", "buddyIcon": "https://jimm.online/webapi/expressions/get?t=987654321&type=buddyIcon" } ] } } } } } } } } }, "/presence/setState": { "get": { "operationId": "setState", "tags": [ "presence" ], "summary": "Change status", "description": "The main status: online, away, do not disturb, occupied, invisible. Away can carry an away message.\n\n- **400** — Unknown status.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "view", "in": "query", "required": true, "description": "The new status (or `state`).", "schema": { "type": "string", "enum": [ "online", "away", "dnd", "occupied", "invisible" ] }, "example": "away" }, { "name": "awayMsg", "in": "query", "required": false, "description": "Away message (for `away`).", "schema": { "type": "string" }, "example": "Скоро вернусь" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "aimId": "123456789", "displayId": "123456789", "state": "away", "awayMsg": "Скоро вернусь", "statusMsg": "", "userType": "icq", "onlineTime": 1761130000 } } } } } } } } }, "/presence/setStatus": { "get": { "operationId": "setStatus", "tags": [ "presence" ], "summary": "Status text and x-status", "description": "Sets the line under your name and the mood icon (x-status). A parameter changes only if present: `mood=` with an empty value clears the x-status, no `mood` at all leaves it alone. Mood codes are in the reference.\n\n- **400** — Unknown `mood` or text too long.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "statusMsg", "in": "query", "required": false, "description": "Status text. Empty clears it.", "schema": { "type": "string" }, "example": "Пишу свой ICQ-клиент" }, { "name": "mood", "in": "query", "required": false, "description": "X-status code. Empty clears it.", "schema": { "type": "string" }, "example": "0icqmood9" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/presence/getProfile": { "get": { "operationId": "getProfile", "tags": [ "presence" ], "summary": "A user’s profile", "description": "Profile text (“about me”). Without `sn`, your own.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "sn", "in": "query", "required": false, "description": "Whose profile.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "screenName": "987654321", "profile": "Сижу в аське с 2003 года", "lastUpdated": 0 } } } } } } } } }, "/presence/setProfile": { "get": { "operationId": "setProfile", "tags": [ "presence" ], "summary": "Update your profile", "description": "Replaces your profile text. Up to 4 KB.\n\n- **400** — Over 4 KB.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "profile", "in": "query", "required": true, "description": "The new text.", "schema": { "type": "string" }, "example": "Сижу в аське с 2003 года" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/addBuddy": { "get": { "operationId": "addBuddy", "tags": [ "buddylist" ], "summary": "Add a buddy", "description": "Adds someone to a group (`Buddies` by default), creating the group if needed. An empty `data` means success; otherwise `data.resultCode` says why, e.g. `alreadyExists`.\n\n- **400** — Missing `buddy`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "buddy", "in": "query", "required": true, "description": "The UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "group", "in": "query", "required": false, "description": "The group.", "schema": { "type": "string" }, "example": "Друзья" }, { "name": "preAuthorized", "in": "query", "required": false, "description": "Pre-authorize this person to add you.", "schema": { "type": "boolean" } }, { "name": "authorizationMsg", "in": "query", "required": false, "description": "Authorization request text.", "schema": { "type": "string" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/removeBuddy": { "get": { "operationId": "removeBuddy", "tags": [ "buddylist" ], "summary": "Remove a buddy", "description": "Removes a buddy from one group, or from all with `allGroups=1`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "buddy", "in": "query", "required": true, "description": "The UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "group", "in": "query", "required": false, "description": "Which group.", "schema": { "type": "string" }, "example": "Друзья" }, { "name": "allGroups", "in": "query", "required": false, "description": "Remove from every group.", "schema": { "type": "boolean" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/moveBuddy": { "get": { "operationId": "moveBuddy", "tags": [ "buddylist" ], "summary": "Move a buddy", "description": "Moves a buddy to another group and/or before another buddy.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "buddy", "in": "query", "required": true, "description": "The UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "group", "in": "query", "required": true, "description": "Current group.", "schema": { "type": "string" }, "example": "Друзья" }, { "name": "newGroup", "in": "query", "required": false, "description": "New group.", "schema": { "type": "string" }, "example": "Работа" }, { "name": "beforeBuddy", "in": "query", "required": false, "description": "Place before this UIN.", "schema": { "type": "string" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/setBuddyAttribute": { "get": { "operationId": "setBuddyAttribute", "tags": [ "buddylist" ], "summary": "Buddy nickname", "description": "Your private name for a buddy (only you see it). Comes back as `friendly`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": true, "description": "The UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "friendly", "in": "query", "required": false, "description": "The nickname. Empty clears it.", "schema": { "type": "string" }, "example": "Вася" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/addGroup": { "get": { "operationId": "addGroup", "tags": [ "buddylist" ], "summary": "Create a group", "description": "Creates a group. Calling it twice is harmless.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "group", "in": "query", "required": true, "description": "The name.", "schema": { "type": "string" }, "example": "Работа" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/renameGroup": { "get": { "operationId": "renameGroup", "tags": [ "buddylist" ], "summary": "Rename a group", "description": "Renames a group.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "oldGroup", "in": "query", "required": true, "description": "Current name.", "schema": { "type": "string" }, "example": "Работа" }, { "name": "newGroup", "in": "query", "required": true, "description": "New name.", "schema": { "type": "string" }, "example": "Коллеги" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/removeGroup": { "get": { "operationId": "removeGroup", "tags": [ "buddylist" ], "summary": "Remove a group", "description": "Removes a group.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "group", "in": "query", "required": true, "description": "The name.", "schema": { "type": "string" }, "example": "Коллеги" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/buddylist/setGroupAttribute": { "get": { "operationId": "setGroupAttribute", "tags": [ "buddylist" ], "summary": "Collapse or expand a group", "description": "Stores whether a group is collapsed, so all your clients show it the same way.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "group", "in": "query", "required": true, "description": "The name.", "schema": { "type": "string" }, "example": "Друзья" }, { "name": "collapsed", "in": "query", "required": true, "description": "Collapsed or not.", "schema": { "type": "boolean" }, "example": "true" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/aim/addTempBuddy": { "get": { "operationId": "addTempBuddy", "tags": [ "buddylist" ], "summary": "Watch presence without adding", "description": "Subscribes this session to presence of people not on your list, until the session ends. Up to 160 people.\n\n- **400** — Empty list or over 160.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": true, "description": "Comma-separated UINs.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/aim/removeTempBuddy": { "get": { "operationId": "removeTempBuddy", "tags": [ "buddylist" ], "summary": "Stop watching", "description": "Undoes addTempBuddy.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": true, "description": "Comma-separated UINs.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/preference/get": { "get": { "operationId": "getPreferences", "tags": [ "preference" ], "summary": "Account preferences", "description": "Server-side preferences: `1` on, `0` off. The same values come as the `preference` event.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "showGroups": 1, "showOffLineBuddies": 1, "acceptOffLineIM": 1, "discloseTyping": 1, "viewIMTimestamps": 1 } } } } } } } } }, "/preference/set": { "get": { "operationId": "setPreferences", "tags": [ "preference" ], "summary": "Change preferences", "description": "Each preference is its own parameter, `1` or `0`. Returns only what changed.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "acceptOffLineIM", "in": "query", "required": false, "description": "Accept offline messages.", "schema": { "type": "string" }, "example": "1" }, { "name": "discloseTyping", "in": "query", "required": false, "description": "Show others that you are typing.", "schema": { "type": "string" }, "example": "1" }, { "name": "showOffLineBuddies", "in": "query", "required": false, "description": "Show offline buddies.", "schema": { "type": "string" }, "example": "1" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "discloseTyping": 1 } } } } } } } } }, "/preference/getPermitDeny": { "get": { "operationId": "getPermitDeny", "tags": [ "preference" ], "summary": "Who can reach you", "description": "The privacy mode and the allow and block lists.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "pdMode": "denySome", "blocks": [ "555555" ] } } } } } } } } }, "/preference/setPermitDeny": { "get": { "operationId": "setPermitDeny", "tags": [ "preference" ], "summary": "Blocking and privacy mode", "description": "Changes the mode and/or adds and removes people from the lists. Lists are comma-separated UINs.\n\n- **400** — Unknown `pdMode`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "pdMode", "in": "query", "required": false, "description": "`permitAll` everyone, `denySome` all but blocked, `permitSome` only allowed, `permitOnList` only buddies, `denyAll` nobody.", "schema": { "type": "string", "enum": [ "permitAll", "denySome", "permitSome", "permitOnList", "denyAll" ] }, "example": "denySome" }, { "name": "pdBlock", "in": "query", "required": false, "description": "Block.", "schema": { "type": "string" }, "example": "555555" }, { "name": "pdBlockRemove", "in": "query", "required": false, "description": "Unblock.", "schema": { "type": "string" } }, { "name": "pdAllow", "in": "query", "required": false, "description": "Allow.", "schema": { "type": "string" } }, { "name": "pdAllowRemove", "in": "query", "required": false, "description": "Remove from allowed.", "schema": { "type": "string" } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "pdMode": "denySome", "blocks": [ "555555" ] } } } } } } } } }, "/memberDir/search": { "get": { "operationId": "memberDirSearch", "tags": [ "directory" ], "summary": "Find people", "description": "`match` is comma-separated `key=value` pairs. `keyword` finds an exact UIN plus keyword matches; `firstName` and `lastName` search names. You never appear in your own results.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "match", "in": "query", "required": true, "description": "What to look for.", "schema": { "type": "string" }, "example": "keyword=987654321" }, { "name": "nToGet", "in": "query", "required": false, "description": "How many (default 100).", "schema": { "type": "integer" }, "example": "20" }, { "name": "nToSkip", "in": "query", "required": false, "description": "How many to skip.", "schema": { "type": "integer" }, "example": "0" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "results": { "nTotal": 1, "nSkipped": 0, "nProfiles": 1, "infoArray": [ { "profile": { "aimId": "987654321", "displayId": "987654321", "firstName": "Василий", "lastName": "Пупкин", "city": "Киев", "country": "UA" } } ] } } } } } } } } } }, "/memberDir/get": { "get": { "operationId": "memberDirGet", "tags": [ "directory" ], "summary": "Directory profile", "description": "Directory profiles (name, city, country) of up to 20 people. Without `t`, your own.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "t", "in": "query", "required": false, "description": "Comma-separated UINs.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "infoArray": [ { "profile": { "aimId": "987654321", "displayId": "987654321", "firstName": "Василий", "lastName": "Пупкин", "city": "Киев", "country": "UA" } } ] } } } } } } } } }, "/memberDir/update": { "get": { "operationId": "memberDirUpdate", "tags": [ "directory" ], "summary": "Update your directory profile", "description": "Each field is its own `set=key=value`. Fields you leave out stay as they are.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "set", "in": "query", "required": true, "description": "A field: `firstName`, `lastName`. Repeatable.", "schema": { "type": "string" }, "example": "firstName=Иван" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": {} } } } } } } } }, "/expressions/get": { "get": { "operationId": "expressionsGet", "tags": [ "expressions" ], "summary": "A user’s buddy icon", "description": "No auth needed. `type=buddyIcon` serves the image itself, ready for ``. Without `type`, JSON with the link.\n\n- **400** — Missing `t`.", "parameters": [ { "name": "t", "in": "query", "required": true, "description": "The UIN.", "schema": { "type": "string" }, "example": "987654321" }, { "name": "type", "in": "query", "required": false, "description": "`buddyIcon` returns the image.", "schema": { "type": "string", "enum": [ "buddyIcon", "bigBuddyIcon" ] } }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "expressions": [ { "type": "bigBuddyIcon", "url": "https://jimm.online/webapi/expressions/get?t=987654321&type=buddyIcon&bartId=…" } ] } } } } } } } } }, "/expressions/upload": { "post": { "operationId": "expressionsUpload", "tags": [ "expressions" ], "summary": "Upload your buddy icon", "description": "The body is the raw image bytes (GIF, JPEG or PNG), not a form. Up to 64 KB. Your contacts get it through a `presence` event.\n\n- **460** — Missing `type`.\n\n- **462** — Empty, over 64 KB, or unknown `type`.", "parameters": [ { "name": "aimsid", "in": "query", "required": true, "description": "Session id from startSession.", "schema": { "type": "string" }, "example": "0123456789abcdef.123456789" }, { "name": "type", "in": "query", "required": true, "description": "Always `buddyIcon`.", "schema": { "type": "string", "enum": [ "buddyIcon" ] }, "example": "buddyIcon" }, { "name": "f", "in": "query", "required": false, "description": "Response format: `json` (default), `xml` or `amf3`. Add `c=name` for JSONP.", "schema": { "type": "string", "enum": [ "json", "xml", "amf3" ] }, "example": "json" } ], "responses": { "200": { "description": "Envelope with statusCode 200 — or, for some failures, another statusCode on HTTP 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "example": { "response": { "statusCode": 200, "statusText": "Ok", "data": { "id": "0001a1b2c3d4e5f6…" } } } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } } }, "components": { "schemas": { "Envelope": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "statusCode", "statusText", "data" ], "properties": { "statusCode": { "type": "integer", "description": "Web API status code; 200 is success." }, "statusDetailCode": { "type": "integer", "description": "Narrows a failure, e.g. 3011 = wrong password under 330." }, "statusText": { "type": "string" }, "requestId": { "type": "string", "description": "Echo of the \"r\" parameter." }, "data": { "description": "The payload; an empty object when there is none." } } } } } } } }