Documentation

Nimbuzz Terms of Use

Nimbuzz Chat buddy - An introduction

Why only use Nimbuzz to chat with people while the concept of Instant Messaging allows you to do much more than just that?
Imagine having a chat buddy that a user can talk to and that will actually respond? Or what about a chat buddy that allows you to send and receive messages through Twitter? You don't even need your separate Twitter software anymore!
The Nimbuzz Chat Buddy API's allows developers to create Buddies that interact with users and allowing users to do a lot more on with messaging.

About this manual

This manual is intended for developers that want to learn to how to use the Nimbuzz Chat buddy API.
The given examples in this manual are simplified to make them as clear as possible.
The real API calls will contain additional HTTP headers and may contain encrypted usernames.

Requirements

To build a Nimbuzz Chat buddy the developer needs to:

  • master any suitable programming language to build the buddy in,
  • be familiar with HTTP, REST and XML, and
  • have a server that is connected to the internet to host the buddy.

Building a buddy

Your buddy needs to be added to the Nimbuzz platform before you can start developing. See Appendix A: Required chat buddy properties for publishing

The Nimbuzz Buddy API is communicating over a RESTful interface and uses xml stanzas, somewhat similar to XMPP to structure the data.
This makes developing a buddy quite easy. When the buddy needs to tell something to a user it sends an HTTP request to the Buddy API. When the Buddy API (on behalf of a user) needs to tell something to the buddy it sends an HTTP request to the buddy's Callback Interfaces.
There are 3 types of Callback Interfaces that the buddy needs to implement.

  • Subscription created
  • Subscription removed
  • Message received

Let's get started by explaining these Callback Interfaces so your buddy can be reached and responds to incoming requests.

Callback Interfaces are required for the Buddy API to be able to initiate contact with the Buddy. This means the buddy has to be able to receive and parse incoming HTTP calls.

Every HTTP request always has a URI, the part that indicates what resources is being requested. All calls to the Callback Interface have a URI too which defines the type of request the server is doing.

Let's look at an example

PUT /iceman/users/varun HTTP/1.1

The structure of the URI is: buddy_name/action/parameter
Buddy name and action are always present. The parameter value is optional

1. Subscription created

Before a user and a buddy can communicate the buddy needs to be added to the user's contact list.
The following example HTTP calls are performed when a user named "varun" adds a buddy named "iceman"

API -> Buddy

PUT /iceman/users/varun HTTP/1.1

Notice that this is an HTTP call without a body. Also in the context of this document irrelevant headers have been left out. An HTTP 200 OK status has to be returned from the buddy.

Buddy -> API

HTTP/1.1 200 OK
Content-Length: 0

Alternatively, the buddy can reply with a welcome message. In case a message is included, the mime-type must be set to application/xml.

Buddy -> API

HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0"?>
<message from='iceman' to='varun'>
<body>Hi varun, very nice to meet you!</body>
</message>

A buddy cannot decide to add a user by itself. The subscription request has to be initiated by the user from either N-World or his client.

2. Subscription removed

When the user removes the buddy from his/her contact list the following call will arrive at the buddy.

API -> Buddy

DELETE /iceman/users/varun HTTP/1.1

The Buddy has to respond with a 200 OK. The relationship between the buddy and the user will have been terminated whether the buddy agrees or not.

Buddy -> API

HTTP/1.1 200 OK
Content-Length:0

Alternatively, a response can contain a farewell message. Again, the mime-type must be set to application/xml.

Buddy -> API

HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0"?>
<message from='iceman' to='varun'>
<body>Hi varun, very nice to meet you!</body>
</message>

At this point the relation between the user and the buddy has been broken. If desired, the buddy should delete stored information associated with that user.

3. Message received

Whenever a message is received for a buddy, the buddy will be notified about this through an HTTP post.

Example

API -> Buddy

POST /iceman/message HTTP/1.1 Content-Type: application/xml <?xml version="1.0"?>
<message from='varun' to='iceman'>
<body>Can you tell me a joke?</body>
</message>

The buddy should respond with a 200 OK. Optionally, the buddy may return a message in the response body in which case the mime-type MUST be set to application/xml.

Buddy -> API

HTTP/1.1 200 OK Content-Type: application/xml
<?xml version="1.0"?>
<message from='iceman' to='varun'>
<body>I see you changed your status.</body> </message>

Appendix A: Required Buddy Properties for Publishing

  • Name – The full name of the buddy, e.g. Iceman the Chatbuddy.
  • Category – The type of buddy, e.g. News
  • Description – A textual description of the buddy.
  • Callback URL – The URL of the buddy owner used to post events to. Note that the URL MUST end with a slash, e.g. http://www.mydomain.com/buddy/
  • Status – Indicates the presence status of the buddy. Can be one of online, offline, away or dnd
  • Status text – Personal message that will be included in the presence of the buddy

Buddies are managed by Nimbuzz. Please send the above information to your contact within Nimbuzz.

Appendix B: HTTP Response Codes

The following Response Codes are defined for the Buddy API.

HTTP Response Code Description
200 The operation was completed successfully
400 Either mime-type is NOT application/xml, or the body is invalid (i.e. malformed XML, unknown tag)
403

Invoked from unauthorized IP address
500 Internal server error - any other error triggered by the Nimbuzz server

Read Sample Code
Go to Top