Docs / RICOH Cloud API Reference

Show Category

Messaging API

Messaging API enables your application to send and receive messages.

Messaging XMPP API

Support only BOSH(Bidirectional-streams Over Synchronous HTTP).

Open

Connect ‘https://xmpp.api.ricoh/v1/http-bind’ and open BOSH connection. The login user name is <sub in ID Token>@xmpp.api.ricoh. The password is Access Token.

SASL mechanism ‘PLAIN’ is supported.

<body rid='248578874' xmlns='http://jabber.org/protocol/httpbind' to='xmpp.api.ricoh' xml:lang='en' wait='60' hold='1' content='text/xml; charset=utf-8' ver='1.6' xmpp:version='1.0' xmlns:xmpp='urn:xmpp:xbosh'/>

Instant Message

User can send an instant message to recipient by sending ‘message stanza’ with ‘type’ attribute as ‘chat’. The maximum length of stanza you can send is 4096 bytes.

Send

<message to='dcba@xmpp.api.ricoh' type='chat' xmlns='jabber:client'>
  <body>message for dcba</body>
</message>

Receive

<message from='abcd@xmpp.api.ricoh' to='dcba@xmpp.api.ricoh' type='chat' xmlns='jabber:client'>
  <body>message for dcba</body>
</message>

Presence

User can send an presence to recipient by sending ‘presence stanza’. ‘chat’,’away’,’dnd’ and ‘xa’ are supported for ‘type’ attribute.

<presence xmlns='jabber:client' type='chat'/>

Subscribe to the recipient’s presence

User can specify target jid by sending ‘iq stanza’ with ‘type’ attribute as ‘set’. User can send an subscribe request by sending ‘presence stanza’ with ‘type’ attribute as ‘subscribe’. The maximum size of a roster is 32. And the maximum length of name you can set is 64.

<iq type='set' xmlns='jabber:client' id='afaaa5e8-83b9-4107-944f-8d9efc84d482:sendIQ'>
  <query xmlns='jabber:iq:roster'>
    <item jid='dcba@xmpp.api.ricoh' name='dcba@xmpp.api.ricoh'/>
  </query>
</iq>
<presence to='dcba@xmpp.api.ricoh' type='subscribe' xmlns='jabber:client'/>

Approve subscription

User can specify target jid by sending ‘iq stanza’ with ‘type’ attribute as ‘set’. User can send an approve subscription response by sending ‘presence stanza’ with ‘type’ attribute as ‘subscribed’.

<iq type='set' xmlns='jabber:client' id='eec2b849-9f9a-46f6-8ac9-24ca3917a42f:sendIQ'>
  <query xmlns='jabber:iq:roster'>
    <item jid='dcba@xmpp.api.ricoh' name='dcba@xmpp.api.ricoh'/>
  </query>
</iq>
<presence to='dcba@xmpp.api.ricoh' type='subscribed' xmlns='jabber:client'/>

Get the roster

You can get a roster by sending ‘iq stanza’ with ‘type’ attribute as ‘get’.

Request

<iq type='get' xmlns='jabber:client' id='311819b3-f520-4819-95c1-8ee6d62929a3:sendIQ'>
  <query xmlns='jabber:iq:roster'/>
</iq>

Response

<iq type='set' xmlns='jabber:client' id='3bdfd9c5-be7a-43ac-b8c7-10dca63700b7:sendIQ'
 from='abcd@xmpp.api.ricoh' to='dcba@xmpp.api.ricoh'>
  <query xmlns='jabber:iq:roster'>
    <item name='dcba@xmpp.api.ricoh' jid='dcba@xmpp.api.ricoh' subscription='both'/>
  </query>
</iq>

Remove subscription to the recipient’s presence

You can specify target jid by sending ‘iq stanza’ with ‘type’ attribute as ‘set’. You can send an unsubscribe request by sending ‘presence stanza’ with ‘type’ attribute as ‘unsubscribe’.

<iq type='set' xmlns='jabber:client' id='3bdfd9c5-be7a-43ac-b8c7-10dca63700b7:sendIQ'>
  <query xmlns='jabber:iq:roster'>
    <item jid='dcba@xmpp.api.ricoh' subscription='remove'/>
  </query>
</iq>
<presence to='dcba@xmpp.api.ricoh' type='unsubscribe' xmlns='jabber:client'/>

Messaging REST API

This document describes the following endpoints which Messaging API supports:

Method Description
GET /messages Fetch information about messages

Note: The default encoding is UTF-8.

Date formats

Messaging API accepts dates formatted in the ISO-8601 standard in UTC (no local timezone offset).

YYYY-MM-DDTHH:MM:SSZ

GET /messages

This API fetches and lists information about message created by your End Users.

Request

curl --request GET 'https://xmpp.api.ricoh/v1/messages?from=2016-09-01T00%3A00%3A00Z&to=2017-09-30T23%3A59%3A59Z' /
     --header 'Authorization: Bearer <Access Token>'
URL Structure
https://xmpp.api.ricoh/v1/messages
Headers
Header Description
Authorization Required. Authorization Header
Set your Access Token as a Bearer token.
Query Parameters
Field Description
from Required. The start time of the search target period.
Limit search results to messages whose end time exceeds this time.
You can not specify a time after the time specified by ‘to’.
to Required. The end time of the search target period.
Limit search results to messages whose start time is less than this time. The upper limit is UTC time of the previous day 00:00:00.
If a time that exceeds the upper limit value is specified, it is rounded to the upper limit value.
page Optional. The page number.
If an invalid value is specified, the default value of 1 is used.
pageSize Optional. The number of messages per page.
If an invalid value is specified, the default value of 10 is used.
The maximum value is 100.

Response

{
  "from": "2017-05-30T13:02:05Z",
  "to":"2017-06-30T13:02:05Z",
  "messages":[
    {
      "sent_at":"2017-06-01T00:00:00Z",
      "type":"chat",
      "sub":"testuser01",
      "sender":"testuser01@xmpp.api.ricoh",
      "receiver":"testuser02@xmpp.api.ricoh",
      "size":1024,
      "client_id":"D947DB58-B552-43FC-9FB9-8BB183FB5D13",
      "user_plan":"xmpp_free"
    }
  ],
  "total":2,
  "nextPage":"https://xmpp.api.ricoh/v1/messages?page=2&pageSize=1&from=2017-05-30T13%3A02%3A05Z&to=2017-06-30T13%3A02%3A05Z"
}
Headers
Header Description
Content-Type application/json; charset=utf-8
Body
Field Type Description
from string The start time of the search target period.
to string The end time of the search target period.
messages array of objects(Message) List of messages.
total integer Total number of search results.
nextPage string The URL for requesting the next page and null if the next page does not exist.

Object(Message)

Field Type Description
message_id string The message identifier.
sent_at string The time the message was sent.
sub string The identifier of the sender.
sender string The jid of the sender.
receiver string The jid of the receiver.
size integer The message length (in bytes).
user_plan string The plan name for the message.
Status Codes
Code Reason
200 OK
400 Bad Request.
401 Unauthorized. Invalid or expired Access Token.
405 Method not allowed.
500 Internal server error.