NAV
shell php

Introduction

Welcome to the Webtop.com API!

This API is currently under development so please check back for continues updates about new endpoints and functionality.

In our first version of the API we currently only support chat message hooks

Integration Client

In order to get started with our API you need a Webtop.com Pro account tier or higher.

Once you have created your workspace you can navigate to the Admin section and go to the "App integrations" page.

On this page you will see a "Custom integrations" tab where you can create your first Integration Client.

After you have successfully created your first integration client you can now proceed to create a hook for one of your desktops.

Bot account

Each time you create a new Integration Client it will create a bot account that all the hooks will act through.

This means that anytime you perform a request to a hook the resulting data will be done through the bot account and not your own account.

You can have a custom name and image on your bot if you wish to do that.

Rate limiting

All our endpoints are subject to rate limiting. The rate limit will be different for each endpoint depending on what we see fit as usage.

The rate limit can be viewed as response headers when you make a request.

Header Meaning
X-Rate-Limit-Total-Per-Hour How many requests you can make per hour in this context
X-Rate-Limit-Total-Per-Day How many requests you can make per day in this context
X-Rate-Limit-Used How many requests you have used in this context
X-Rate-Limit-Remaining How many requests you have remaining in this context

Hooks

Hooks are a way to easily work with a desktop in your workspace as they do not require any authentication to use once they are created. For this reason be careful not to share the url publically!

Get started by creating a Desktop and make sure it is marked as "Internal".

Now that your internal Desktop is created you can go back to the Integration Client page and navigate to the "Hooks" tab.

Create a new hook and select your newly created Desktop.

All of your hooks will have a unique id and secret that will be used when constructing the request url.

Thats it! You now have a hook that will work with all Hook endpoints

Hook endpoints

Currently we only support creating chat messages with hooks, but look back for more updates in the future!

Post chat message

curl -X POST https://api.webtop.com/v1/hooks/<$id>/<$secret>/message -H "Content-Type: application/json" \
     -d '{"message": "Hello World from Hook API!"}'
$hookId = '35d7bef2-3d7e-11ec-bfa2-42010a200115';
$secret = 'aa84c7c4e1422ba3e0d6ea719c876be30808b4917e498149674f9f2b3bdb08c7';

# any PSR-compliant http request client
$httpClient = HttpClient::create([
    'timeout' => 10,
    'max_duration' => 10,
    'headers' => [
        'Content-Type' => 'application/json'
    ]
]
]);

$response = $httpClient->request('POST', "https://api.webtop.com/v1/hooks/$hookId/$secret/message", [
    'message' => 'Hello World from Hook API!'
])->getContent();

Returns 200 OK header with "ok" as response body if everything went ok

HTTP 200 OK
ok

Returns 401 Forbidden header with json payload if you use a wrong id or secret

{
    "error": "access_denied",
    "error_description": "The resource owner or authorization server denied the request.",
    "message": "The resource owner or authorization server denied the request."
}

Use this hook if you want to post a chat message to the Desktop through the Bot account.

See examples on the right side.

Subject to Rate limiting

HTTP Request

POST https://api.webtop.com/v1/hooks/<$id>/<$secret>/message

Replace <$id> and <$secret> with the Hook ID and Secret.

JSON Parameters

Parameter Required Description
message true The message you want to send

Errors and error codes

The Webtop.com API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- You provided the wrong credentials or access token
403 Forbidden -- Your account does not have access to read or perform actions on the requested resource
404 Not Found -- The resource could not be found.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.