Skip to content

Business Bot Platform REST API

The Business Bot Platform API is a RESTful API and provides programmatic access to entities of the Business Bot Platform and lets you easily integrate the Business Bot Platform with 3rd party tools. The API supports JSON for requests and responses. The response content type is requested via the HTTP Accept header (application/json). All resources are accessible via https and are located at https://my.bbp.local/bbp/rest/api/1.0/ for public cloud and https://<TenantId>.bbp.local/bbp/rest/api/1.0/ for private cloud.

Authentication

The REST API accepts authentication using Tenant Id, API Id and API Key. By default, the client must authenticate to access all resources. The Tenant Id corresponds to the organization id, which corresponds to the subdomain of the bbp.local URL (for example, if your Business Bot platform URL is mycompany.bbp.local, the organization Id would be mycompany). If you do not specify the Tenant Id, the authentication will fail.

Exception Handling (Errors)

The Business Bot Platform uses HTTP status code in the response to report the success or failure of an API request. Codes in the 1xx range are intended for informational purposes. Codes in 2xx range show success, codes in 3xx range are reserved for redirections, codes in 4xx range show client errors (for example a missing parameter), and codes in 5xx range indicate errors on the server side. In case of an error, the response contains the following information (e.g., {\"code\":402,\"description\":\"Unknown source user\",\"status\":\"false\"}):

Attribute Description
code The corresponsing HTTP status code
description A human readable description of the error
status General success status of the request

The following overview shows the most important error codes:

Code Description
1xx - Informational
2xx - Success
200 OK
3xx - Redirection
4xx - Client Error
401 Unauthorized
402 Unknown source user
403 Unknown target user
405 Method not allowed
410 Unknown system type and system release
450 API user or API key invalid
451 API user inactive
452 API user has no license
453 API user license is expired
454 API user has exceeded the total number of messages per month
455 Queue name does not exists
456 System identifier does not exists
457 API user has limited license but requires enterprise license
5xx - Server Error
500 Internal processing error
503 The server is currently unavailable because of maintenance

API Versioning

We will release a new version of the API when we make backwards-incompatible changes. We consider the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.

API Resources

Syntax of the URL:

https://<Tenant Id>.bbp.local/bbp/rest/api/<API Version>/<Tenant Id>:<API Id>:<API Key>/<System Integration Identifier>/<Resource>

Example URL: https://jmb.bbp.local/bbp/rest/api/1.0/jmb:u-19df358:357f215/ENOVIA-001/getUpdates

Resource: getUpdates

This resource request is sent from a client to the Business Bot platform to retrieve the latest system events (from the queue). The system events are stored on a queue which is associated to a dedicated system integration and bot.

HTTP Methode Content Type Resource Description
POST application/json /getUpdates Retrieving messages events

Request Content:

1
{"limit":100,"offset":1,"timeout":20}

Response Content (Example with empty result set):

1
{"status":true, "code":200, "result":[]}

Response Content (Example with result set):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
    "status": true,
    "code": 200,
    "result": [{
        "updateId": 326,
        "message": {
            "reply": false,
            "messageId": 0,
            "from": {
                "id": 0,
                "firstName": "firstName",
                "lastName": "lastName",
                "userName": "john"
            },
            "to": {
                "id": 0,
                "firstName": "firstName",
                "lastName": "lastName",
                "userName": "NO_USER"
            },
            "date": 0,
            "meta": {
                "id": 0,
                "systemType": "WebUI",
                "systemRelease": "1.0",
                "eventType": "SearchRequest",
                "eventName": "Object",
                "objectId": null,
                "refObjectId": null
            },
            "text": "",
            "audio": null,
            "document": null,
            "photo": null,
            "video": null,
            "location": null,
            "replyToMessage": null,
            "voice": null,
            "data": {
                "filter": {
                    "objectType": "Issue",
                    "objectName": "*",
                    "objectRevision": "*",
                    "objectId": null,
                    "limit": 5,
                    "searchString": null,
                    "orderBy": "DESC",
                    "tsBegin": null,
                    "tsEnd": null,
                    "owner": null,
                    "view": "issuelist"
                },
                "result": ""
            }
        }
    }]
}

Resource: sendUpdate

This resource request is sent by a client to the Business Bot platform to send a message to a mobile user.

HTTP Methode Content Type Resource Description
POST application/json /sendUpdate Sending a message

Request Content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
    "message": {
        "to": {
            "lastName": "lastName",
            "userName": "erika",
            "firstName": "firstName"
        },
        "data": {
            "result": "[{\"type\":\"Issue\",\"name\":\"ISS-0000001\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.31712.43999\"},{\"type\":\"Issue\",\"name\":\"ISS-0000002\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.11568.63047\"}]",
            "filter": {
                "limit": 5,
                "orderBy": "DESC",
                "objectType": "Issue"
            }
        },
        "from": {
            "lastName": "lastName",
            "userName": "john",
            "firstName": "firstName"
        },
        "meta": {
            "systemType": "ENOVIA",
            "eventName": "Object",
            "eventType": "SearchResult",
            "systemRelease": "R2015x"
        }
    },
    "updateId": "1234"
}

Response Content (Example data):

1
{"code":200,"description":"Ok","status":"true"}

API Error Handling

HTTP Status 500: No Content To Map To Object Due To End Of Input

If you receive the following error, an empty POST request was sent to the Business Bot platform.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
HTTP Status 500 - org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input

type Exception report

message org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input

description The server encountered an internal error that prevented it from fulfilling this request.

exception

javax.servlet.ServletException: org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input
    org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487)
    org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
    org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input
    org.glassfish.jersey.servlet.internal.ResponseWriter.rethrow(ResponseWriter.java:278)
    org.glassfish.jersey.servlet.internal.ResponseWriter.failure(ResponseWriter.java:260)
    org.glassfish.jersey.server.ServerRuntime$Responder.process(ServerRuntime.java:509)
    org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:334)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
    org.glassfish.jersey.internal.Errors.process(Errors.java:315)
    org.glassfish.jersey.internal.Errors.process(Errors.java:297)
    org.glassfish.jersey.internal.Errors.process(Errors.java:267)
    org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
    org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
    org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
    org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
    org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
    org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

java.io.EOFException: No content to map to Object due to end of input
    org.codehaus.jackson.map.ObjectMapper._initForReading(ObjectMapper.java:2766)
    org.codehaus.jackson.map.ObjectMapper._readValue(ObjectMapper.java:2682)
    org.codehaus.jackson.map.ObjectMapper.readValue(ObjectMapper.java:1308)
    org.codehaus.jackson.jaxrs.JacksonJsonProvider.readFrom(JacksonJsonProvider.java:419)
    org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.invokeReadFrom(ReaderInterceptorExecutor.java:256)
    org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.aroundReadFrom(ReaderInterceptorExecutor.java:235)
    org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155)
    org.glassfish.jersey.server.internal.MappableExceptionWrapperInterceptor.aroundReadFrom(MappableExceptionWrapperInterceptor.java:74)
    org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155)
    org.glassfish.jersey.message.internal.MessageBodyFactory.readFrom(MessageBodyFactory.java:1085)
    org.glassfish.jersey.message.internal.InboundMessageContext.readEntity(InboundMessageContext.java:874)
    org.glassfish.jersey.server.ContainerRequest.readEntity(ContainerRequest.java:271)
    org.glassfish.jersey.server.internal.inject.EntityParamValueFactoryProvider$EntityValueFactory.provide(EntityParamValueFactoryProvider.java:96)
    org.glassfish.jersey.server.spi.internal.ParamValueFactoryWithSource.provide(ParamValueFactoryWithSource.java:71)
    org.glassfish.jersey.server.spi.internal.ParameterValueHelper.getParameterValues(ParameterValueHelper.java:94)
    org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$AbstractMethodParamInvoker.getParamValues(JavaResourceMethodDispatcherProvider.java:127)
    org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160)
    org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102)
    org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
    org.glassfish.jersey.internal.Errors.process(Errors.java:315)
    org.glassfish.jersey.internal.Errors.process(Errors.java:297)
    org.glassfish.jersey.internal.Errors.process(Errors.java:267)
    org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
    org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
    org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
    org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
    org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
    org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

note The full stack trace of the root cause is available in the Apache Tomcat/8.0.38 logs.
Apache Tomcat/8.0.38

HTTP Status 415: Unsupported Media Type

If you receive the following error, the content type expected by the Business Bot Platform does not match application/json.

1
2
3
4
5
6
7
8
HTTP Status 415 - Unsupported Media Type

type Status report

message Unsupported Media Type

description The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
Apache Tomcat/8.0.38

HTTP Status 500: org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]

If you receive the following error, the request content is incorrect, in this example the JSON content is invalid.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
HTTP Status 500 - org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]

type Exception report

message org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]

description The server encountered an internal error that prevented it from fulfilling this request.

exception

javax.servlet.ServletException: org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]
    org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487)
    org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
    org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

root cause

org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]
    org.json.JSONTokener.syntaxError(JSONTokener.java:433)
    org.json.JSONObject.<init>(JSONObject.java:232)
    org.json.JSONObject.<init>(JSONObject.java:324)
    de.citunius.bbp.adk.services.WebService.isValidRawMessage(WebService.java:348)
    de.citunius.bbp.adk.services.WebService.sendMessageRequest(WebService.java:391)
    sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
    sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
    java.lang.reflect.Method.invoke(Unknown Source)
    org.glassfish.jersey.server.model.internal.ResourceMethodInvocationHandlerFactory$1.invoke(ResourceMethodInvocationHandlerFactory.java:81)
    org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher$1.run(AbstractJavaResourceMethodDispatcher.java:144)
    org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.invoke(AbstractJavaResourceMethodDispatcher.java:161)
    org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160)
    org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347)
    org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102)
    org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:271)
    org.glassfish.jersey.internal.Errors$1.call(Errors.java:267)
    org.glassfish.jersey.internal.Errors.process(Errors.java:315)
    org.glassfish.jersey.internal.Errors.process(Errors.java:297)
    org.glassfish.jersey.internal.Errors.process(Errors.java:267)
    org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317)
    org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305)
    org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154)
    org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471)
    org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336)
    org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223)
    org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)

note The full stack trace of the root cause is available in the Apache Tomcat/8.0.38 logs.
Apache Tomcat/8.0.38