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. |