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.

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

Errors and error codes

The Webtop.com API uses the following error codes: