API#

The API lets you work with Watbot bots from your own code: find and create contacts, send them messages, change variables and tags, top up balances, manage lists. For example, a CRM on your website can pass a lead to the bot, and a payment system can award bonuses after a purchase.

The API is available to the account owner on the Pro plan. Each request runs on behalf of the key's owner, with the owner's permissions.

API key#

You get the key in your profile, on the "API" tab — see API key. The key gives full access to the account: keep it on your server and never put it into the code of web pages or mobile apps.

Pass the key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

If you can't set a header, pass the key as the api_token parameter — in the URL or in the request body. The header is safer: URLs with parameters end up in server logs.

The "Regenerate" button in your profile replaces the key, and the old one stops working at once. The key is also reset when you change or reset your password — get a new one afterwards. To check a key, call getMe: it returns the account the key belongs to.

Requests#

All methods live at:

https://watbot.org/api/v1/methodName

• Most methods accept both GET and POST; each method lists which. Call methods that change data with POST.
• POST parameters go as JSON (Content-Type: application/json) or as form fields; GET parameters go in the URL.
• Responses are JSON in UTF-8.

Important

Send the Accept: application/json header with every request. Without it, validation errors come back as a redirect instead of a JSON 422 response, and your code won't be able to handle them.

Example: a bot's contacts.

curl -X POST "https://watbot.org/api/v1/getContacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": 12345}'

The bot ID (bot_id) is the number in the bot's address in the dashboard: /bots/12345/….

Limits#

• Rate — 120 requests per minute per account, all methods combined.
• Above the limit the API responds with 429. The Retry-After header tells you how many seconds to wait; X-RateLimit-Remaining shows how many requests are left in the current minute.

Errors#

A successful response has the code 200 or 201. Errors:

A 422 error lists every field with its reasons in errors:

{
  "message": "The contact id field is required.",
  "errors": {
    "contact_id": ["The contact id field is required."]
  }
}

Error texts may change — in your code, rely on the status code and on the code and errors fields.

Until it's switched off, a deprecated method works as before, but every response carries the Deprecation: true header and a Sunset header with the switch-off date. Check them in your code to move to the replacement in time.