На данный момент MESSAGING не выдается новым приложениям
Протокол XMPP является основным протоколом для использования приложениями, которые ориентированы на обмен сообщениями между пользователями социальной сети “Одноклассники”. Примерами таких приложений являются Mail.Ru Agent и ICQ, которые используют этот протокол для общения с сервером Одноклассников.
Поддерживаемые расширения
Сервер XMPP Одноклассников старается поддерживать популярные расширения протокола XMPP, поддерживая совместимость с такими программами, как Gajim, Psi и другими. Разумеется, эти приложения не могут использовать ту функциональность, которая уникальна для сервера Одноклассников, однако могут общаться с пользователями, использующими как рекомендованные клиенты, так и любые другие, использующие протокол XMPP. Общение с теми пользователями, которые находятся на сайте, также происходит прозрачным образом.
Краткий список расширений, которые целиком или частично поддерживаются сервером Одноклассников:
XEP-0012: Last Activity
XEP-0030: Service Discovery
XEP-0033: Extended Stanza Addressing (ограниченное использование для MUC)
XEP-0045: Multi-User Chat (за исключением создания новых комнат)
XEP-0048: Bookmarks (ограниченное использование для MUC)
XEP-0049: Private XML Storage (ограниченное использование для MUC)
XEP-0054: vcard-temp (в данный момент read-only)
XEP-0055: Jabber Search
XEP-0153: vCard-Based Avatars
XEP-0199: XMPP Ping
XEP-0203: Delayed Delivery
XEP-0071: XHTML-IM (временно отключено)
XEP-0231: Bits of Binary (временно отключено, будет использоваться для поддержки смайликов)
Обратите внимание, что часть функционала может быть отключена из-за технических работ на сервере. Приложение должно адекватно реагировать на это, используя информацию из расширения XEP-0030.
Соединение с сервером
Для соединения с сервером используется адрес “xmpp.odnoklassniki.ru” и порт 5222. После соединения не забывайте провести TLS handshake (опционально, но крайне желательно).
После включения поддержки BOSH для соединения также будут доступны порты 80 и 443.
Процедура авторизации
Использование ID и пароля (не рекомендуется)
Клиент может использовать стандартную SASL PLAIN (RFC 3920) схему авторизации, указывая в качестве имени пользователя свой ID в Одноклассниках и свой пароль на сайте. Данная схема не рекомендуется к использованию, но оставлена для поддержки тех приложений, которые не могут использовать OAuth процедуру авторизации.
Так как данный метод не поддерживает ввод CAPTCHA, то он может быть недоступен сразу для большого числа IP-адресов и большого числа ID пользователей, если с использованием этих IP-адресов или ID пользователей происходят массовые некорректные действия (рассылка спама, ошибочные попытки авторизации и т.д.).
Использование OAuth-авторизации
Для использования данного метода приложение должно быть зарегистрировано на одноклассниках как внешнее, т.е. иметь возможность авторизовывать пользователей по протоколу OAuth. Кроме того, приложение должно иметь право MESSAGING, которое можно получить по запросу в службу поддержки.
Для авторизации используется метод “X-ODKL-API-SESSION-KEY”.
В качестве application id идёт числовой идентификатор приложения, session_key — токен, полученный во время OAuth-авторизации пользователя. Обратите внимание, что данные передаются без Base64-кодировки.
Если произошла ошибка, то ответ сервера соответствует стандарту:
Коды ошибок (названия элементов внутри станзы failure):
malformed-request
неправильный формат JSON
отсутствуют необходимые свойства (application_key / session_key)
temporary-auth-failure
временная ошибка (недоступна база данных, например)
неверный ключ приложения или сессии
account-disabled
пользователь не найден, либо заблокирован
not-authorized
приложению не разрешена операция MESSAGING
Отличия от стандарта
Сервер Одноклассников не является сервисом прозрачной пересылки сообщений между клиентами. Его можно рассматривать скорее как некий интерфейс доступа к базе контактов, сообщений и сервисов. Сообщения прозрачным образом пересылаются между множеством клиентов XMPP, пользователей онлайн-версии сайта и мобильных пользователей. Как следствие, имеют место следующие отличия от стандартов XMPP:
Сервер не возвращает идентификатор ресурса для контактов. Всё общение происходит с т.н. bare jid. Указание resource чаще всего будет игнорироваться (сообщение попадёт в базу и будет передано всем контактам).
Сервис MUC Одноклассников не отключает пользователей от комнаты после дисконнекта. Пользователь остаётся в комнате (в режиме offline) до явного выхода из неё. По этой причине сервер передаёт текущий список комнат в ответе расширения bookmarks вместе со флагом автосоединения.
Сервис MUC Одноклассников не позволяет пользователям иметь свои имена в комнатах. Для совместимости с протоколом XMPP каждому назначается имя, состоящее из имени, фамилии и уникального суффикса.
В сервисе MUC нельзя создавать новые комнаты стандартными средствами XMPP, так как необходимо сразу указывать приглашённых участников. Команду создания чата смотрите ниже.
Особенности взаимодействия с сервисом сообщений
После соединения с сервером клиенту приходят все непрочитанные сообщения. Контролировать эту политику можно указанием дополнительной опции send-unread-chat-messages в первой станзе presence:
После выхода (дисконнекта, обрыва соединения) все непрочитанные сообщения будут помечены как прочитанные (в частности для того, чтобы не посылать ещё раз непрочитанные при новом соединении). Отключить эту политику можно опцией mark-chat-messages-read-on-exit:
Расширения протокола
Включение timestamp’ов для получаемых сообщений
Указание дополнительного feature “http://www.odnoklassniki.ru/timestamp” клиентом позволяет серверу начать передавать в сообщениях дополнительное поле с timestamp’ом всех сообщений (а не только из offline storage):
Дополнительные команды для взаимодействия с сервисом
Следующие команды доступны для приложений, авторизованных через OAuth:
Получение списка дискуссий
Команда возвращает список недавних дискуссий пользователя:
Создание новой комнаты мультичата
При создании чата передаётся список приглашённых участников. Тема является опциональным аргументом.
Важно: создание чата конкретным соединением с помощью данной команды не означает автоматическое вступление в конференцию для данного соединения и начала приёма сообщений. Кроме IQ-ответа клиенту придёт приглашение в чат (от самого себя), которое он должен принять.
Получение истории переписки
Возвращает историю переписки с конкретным участником или в комнате чата.
Поддержка статусов прочитанности
Сервер может уведомлять клиента о факте чтения сообщений клиентом (если клиент это поддерживает – вызовами mark-as-read, если это XMPP, или скроллингом, если получатель читает сообщение с экрана). Для этого клиент должен подписаться на события о прочитанности сообщений. При этом клиента будут уведомлять и о факте чтения сообщения получателем, и о факте чтения сообщения, если сам пользователь прочитал его с другого устройства.
В качестве conversation может выступать JID MUC чат-группы. В этом случае будут приходить только уведомления о прочитанности сообщений текущим пользователем (с других устройств).