Monitor requests to the Bot API v3

Learn how to monitor requests made to the Bot API v3. Monitor a specific request or monitor requests filtered by date range, health state, or origin.

You can monitor the status of requests to Bot API v3 with the following:

Among other data, these calls return a state field indicating one of the following states: PENDING, ERROR, SUCCESS. Both calls return the same request data in the response.

Here's an example response.

{
    "data": {
        "id": "03a913a3-552e-4e2a-8d23-d1e5257474bc",
        "companyKey": "mycompany",
        "externalId": "9876543211234567",
        "networkKey": "facebook",
        "appId": "company-bot",
        "callbackUrl": "https://www.example.com/receive",
        "origin": "BOT",
        "state": "PENDING",
        "payload": ,
        "createdEpochMillis": 1551757370603,
        "completedEpochMillis": 1551757370707,
        "lastUpdatedEpochMillis": 1551757370707
    }
}

Monitoring a specific request

All requests to the Bot API v3 return a requestId:

"requestId": "d3cf183a-4f30-11e9-bc72-cd9609519b63"

Note this requestId in order to monitor the status of the request.

To check the status of a request, pass that requestId to /bots/v3/request/{requestId}.

Your call will look something like this:

curl GET \
https://api.app.lithium.com/bots/v3/request/03a913a3-552e-4e2a-8d23-d1e5257474b \
    -H "Authorization: Bearer [TOKEN]"

The state field of the response indicates the state of the request: PENDING, SUCCESS, or ERROR.

{
    "data": {
        "id": "03a913a3-552e-4e2a-8d23-d1e5257474bc",
        "companyKey": "mycompany",
        "externalId": "9876543211234567",
        "networkKey": "facebook",
        "appId": "company-bot",
        "callbackUrl": "https://www.example.com/receive",
        "origin": "BOT",
        "details": <map of details relevant to the request>,
        "state": "PENDING",
        "payload": <json payload given to or taken from bot>,
        "createdEpochMillis": 1551757370603,
        "completedEpochMillis": 1551757370707,
        "lastUpdatedEpochMillis": 1551757370707
    }
}

Monitor requests by date range, state, and origin

Make a GET request to /bots/v3/request/appId/{appId} to retrieve and monitor requests for a bot filtering by a date range, the request state (PENDING, ERROR, SUCCESS), and the origin of the request (Khoros or the bot). The call retrieves all request records according to the given path and query parameters.

You may one or more query parameters to filter your call.

Query ParameterDescription
fromOptional. A string of the form indicating how far in the past to look for recent request records. For example: “30m”, “2h”, "3d” representing “30 minutes”, “2 hours”, or “3 days”, respectively.

Defaults to 1 day.

31 days is the maximum
stateOptional. A string indicating the state of the requests to return.

No default: if unspecified, all records from the period are returned.

Currently, only ERROR, PENDING, or SUCCESS are recognized.

You may specify this parameter multiple times, as in:
/bots/v3/request/appId/mybot?from=6h&state=PENDING&state=ERROR
originOptional. A string indicating that the query should return only request records of the specified origin.

Possible values are KHOROS or BOT

Khoros-originated records are those requests the bot framework made to your bot.

Bot-originated records are those requests your bot made to the bot framework.

Your call will look something like this:

curl GET \
"https://api.app.lithium.com/bots/v3/request/appId/mybot?from=12h" \
    -H "Authorization: Bearer [TOKEN]"

A success response looks something like this.

{
    "data": [
    {
        "id": "5f153108725b404b9aca71a4a5e17cb4",
        "companyKey": "myco",
        "externalId": "987654321234567890",
        "networkKey": "facebook",
        "appId": "myco-bot",
        "callbackUrl": "https://www.example.com/receive",
        "origin": "BOT",
        "state": "PENDING",
        "createdEpochMillis": 1551757840916,
        "completedEpochMillis": 1551757841000,
        "lastUpdatedEpochMillis": 1551757841000,
            "payload": "{\"coordinate\":{\"companyKey\":\"myco\",\"networkKey\":\"facebook\",\"externalId\":\"987654321234567890\",\"messageId\":\"superSpecialMessageId\",\"botId\":\"myco-bot\",\"scope\":\"PRIVATE\"},\"text\":\"I have a question that I need help with.\",\"author\":{\"id\":\"superSpecialAuthorId\",\"fullName\":\"Anonymous Coyote 2380\",\"properties\":{}},\"owner\":{\"type\":\"BOT\",\"appId\":\"myco-bot\"},\"publishedTS\":1555336064223,\"receivedTS\":1555336066071,\"properties\":{},\"type\":\"message\"}"
    },
    {
        "id": "c3e3c2570130410eadf7a04881dfbfe9",
        "companyKey": "myco",
        "externalId": "987654321234567890",
        "networkKey": "facebook",
        "appId": "myco-bot",
        "callbackUrl": "https://www.example.com/receive",
        "origin": "KHOROS",
        "state": "ERROR",
        "createdEpochMillis": 1551758199555,
        "completedEpochMillis": 1551758200801,
        "lastUpdatedEpochMillis": 1551758200804,
        "payload": "{... the json blob that Khoros sent to your bot ...}"
    }
    ]
}

Did this page help you?