Docs / RICOH Cloud API

Show Category

Messaging API

Messaging API adds Messaging functionality to your app. And we also offer management tools that can be used directly by developers and administrators of your application.

Contents

Functions

Messaging API has three functions; Instant Messaging ,Roster and Presence.

  • Messaging Service supports basic Bidirectional-streams Over Synchronous HTTP (BOSH) functionality.(XEP-0124)

Quick Start

This section is designed to show you how to get started with Messaging Service. Note that you need a RICOH Account for Step 1. To create one, see Get Started for detailed instructions. Please also refer to Text Chat Sample in Samples. Using Text Chat Sample, you can try functionalities for instant messaging, roster and presensce.

Step 1: Create an API Client

Create an API client for Messaging API at RICOH Developer Connection Management Console. You need to register the redirect_uri to be used for Authorization Code Grant. See Get Started for detailed instructions. After you successfully finish the procedure, you can check your Client ID and Client Secret at Dashboard.

Step 2: Obtain XMPP Credentials

Obtain XMPP credentials by using your server application to authenticate your end user’s XMPP requests. XMPP credentials is the End User Identifier (sub) and Access Token obtained as a result of Authorization Code Grant.

Implement Authorization Code Grant in Your Server Application

By referring to Authorization Code Grant, you will implement end user authentication in your server application. When you incorporate Authorization Code Grant into your implementation, End User will be able to log in to your app with a RICOH Account. You use Client ID and Client Secret obtained in Step 1. At the end of the Authorization Code Grant procedure, you obtain a response with Access Token (access_token) and ID Token(id_token) like the following example:

{
  "id_token": "eyJ0eXAiOiJKV1Q.iLCJhbGci.OiJSUzI1Ni",
  "access_token": "eyJ0eXAiOiJK.8sDrK37ELI.YAAOBSg",
  "token_type": "Bearer",
  "expired_at": 1479364030
}

You should validate the ID token as described in Authorization Code Grant.

Note: We strongly recommend that server applications support TLS to ensure secure communication between server applications and browsers.

Extract End User Identifier

Decode the ID token to extract end user’s identifier. The ID token is represented as a JSON Web Token (JWT). The identifier is stored as the sub field of the ID Token payload. To manage end users or to utilize Management Tools, you should store the end user identifier in your application.

Send XMPP Credentials to Your Application

Access Token and end user Please safely pass the identifier to the application. If the server application is compliant with TLS, it can be safely passed as a response to HTTPS request. After Authorization Code Grant’s Token request, the server application returns a response to the browser to redirect it to the WebRTC application. To pass it at that redirect, set the Access Token and end user identifier to the query parameter of the redirect URL. In this way, the WebRTC application can obtain TURN Credentials from query parameters.

Step 3: Try Messaging API

The following example is an example using strophe.js.

login to the server

const conn = new Strope.Connection('https://xmpp.api.ricoh/v1/http-bind/');
conn.connect("<sub in ID Token>","<Access Token>");

send an instant message to the recipient

conn.send($msg({ to: "<sub in recipient's ID Token>@xmpp.api.ricoh"}).c('body').t('<the text user wants to send>').up());

Subscribe to the recipient’s presence

conn.sendIQ($iq({ type: 'set'}).c('query', {xmlns: 'jabber:iq:roster'}).c('item', { jid: "<sub in recipient's ID Token>@xmpp.api.ricoh", name: "<recipient's name>"}));
conn.send($pres({ to: "<sub in recipient's ID Token>@xmpp.api.ricoh", type: "subscribe"}));

Approve subscription

conn.sendIQ($iq({ type: 'set'}).c('query', {xmlns: 'jabber:iq:roster'}).c('item', { jid: "<sub in recipient's ID Token>@xmpp.api.ricoh", name: "<recipient's name>"}));
conn.send($pres({ to: "<sub in recipient's ID Token>@xmpp.api.ricoh", type: "subscribed"}));

Get the roster

conn.sendIQ($iq({ type: 'get'}).c('query', {xmlns: 'jabber:iq:roster'});

Remove subscription to the recipient’s presence

conn.sendIQ($iq({ type: 'set'}).c('query', {xmlns: 'jabber:iq:roster'}).c('item', { jid: "<sub in recipient's ID Token>@xmpp.api.ricoh", subscription: "remove"}));
conn.send($pres({ to: "<sub in recipient's ID Token>@xmpp.api.ricoh", type: "unsubscribe"}));

Management Tools

There are the functions for application developers and administrators. You can get records such as end users using XMPP in your app. In order to use functions for application developers and administrators, it is necessary to perform Client authentication by Client Credentials Grant. You need to use the same Client ID and Client Secret as used for end user authentication. For details on client authentication see Client Credentials Grant. In the functions for application developers and administrators, end user is expressed as sub (it is the same value as end user identifier obtained from ID token shown in Step 2 of Quick Start). Therefore, in order to make full use of the functions for application developers and administrators, we recommend using sub to store and manage information related to your end users.

Check Usage

Using the REST API, you can get records that end users used XMPP in your app. By specifying the client ID and duration, you can get all usage records that your end user did during that period. Regardless of the start and end time, if the end user is using that period, it will be included in the result. Usage records can obtain usage start and end times, sub etc. Below is a request and response example.

GET /v1/messages?from=2017-05-30T13%3A02%3A05Z&to=2017-06-30T13%3A02%3A05Z HTTP/1.1
Authorization: Bearer <Access Token>
Host: xmpp.api.ricoh

{
  "from": "2017-05-30T13:02:05Z",
  "to":"2017-06-30T13:02:05Z",
  "messages":[
    {
      "sent_at":"2017-06-01T00:00:00Z",
      "type":"chat",
      "sub":"user01",
      "sender":"user1@xmpp.api.ricoh",
      "receiver":"user2@xmpp.api.ricoh",
      "size":1024,
      "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"
}

Please refer to the API Reference for a detailed explanation of each parameter and the value obtained by the response.

Samples

Specifications

  • XEP-0124 RFC-3920, RFC-6120 XMPP: Core RFC-3921, RFC-6121 XMPP: Instant Messaging and Presence RFC-6122 XMPP: Address Format

See Also