Contact accounts

These methods work with contact accounts — an internal balance in the bot: bonuses, points, a deposit. These are the same accounts that the Top up a contact's account and Debit a contact's account blocks work with and that are shown on the "Accounts" tab of the contact card. For example, a payment system can credit bonuses to the contact after a purchase on your website, and the bot can show the balance with the getBalance function.

A contact has a separate account for each currency. API operations appear in the account journal as "Deposit via API" and "Debit via API".

Warning

Contact accounts are the bot's internal balances (bonuses, points, deposit), not bank accounts: the platform doesn't transfer money through them and isn't a payment service. Keep a record of the operations you send through the API in your own system — you can use it to reconcile balances.

Important

Amounts are sent and returned in the currency's minor units — cents — as an integer. 15000 on a USD account means $150. For currencies without a fractional part, such as JPY, the unit is the whole yen. A single top-up or debit is at most 10¹⁴ minor units (a trillion dollars for USD); more returns 422.

getContactAccounts

Returns all accounts of a contact.

GETPOSThttps://watbot.org/api/v1/getContactAccounts

Parameter	Type	Required	Description
`contact_id`	integer	yes	Contact ID

Request

curl -G "https://watbot.org/api/v1/getContactAccounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "contact_id=678"

Response 200

{
  "data": [
    {
      "id": 4521,
      "currency": "USD",
      "amount": 15000,
      "amount_note": "150 USD",
      "created_at": "2026-09-14T10:22:05+00:00",
      "updated_at": "2026-10-01T18:40:12+00:00",
      "blocked_at": null
    }
  ]
}

Field	Description
`id`	Account ID — pass it to the other methods as `account_id`
`currency`	ISO 4217 currency code
`amount`	Balance in the currency's minor units
`amount_note`	Balance in major units with the currency code, for display
`created_at`, `updated_at`	When the account was opened and last changed
`blocked_at`	When the account was blocked; `null` — not blocked. A blocked account cannot be debited

Accounts are listed in the order they were opened.

addContactAccount

Opens an account in a currency for the contact. The same method is also available as createContactAccount.

POSThttps://watbot.org/api/v1/addContactAccount

Parameter	Type	Required	Description
`contact_id`	integer	yes	Contact ID
`currency`	string	yes	ISO 4217 currency code in capital letters: `USD`, `EUR`, `GBP`

Request

curl -X POST "https://watbot.org/api/v1/addContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 678, "currency": "USD"}'

Response 201

{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 0,
    "amount_note": "0 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:00:00+00:00",
    "blocked_at": null
  }
}

Response 422

{
  "message": "Account with the currency already exists",
  "code": "currency_exists",
  "errors": {
    "currency": [
      "Account with the currency already exists"
    ]
  }
}

Details:

If the contact already has an account in this currency — 422 with an error in the currency field.
Scenario blocks do not need the account in advance: the Top up a contact's account block opens it itself. The API top-up methods do need it, since they work by account_id.

deleteContactAccount

Deletes a contact's account.

POSThttps://watbot.org/api/v1/deleteContactAccount

Parameter	Type	Required	Description
`account_id`	integer	yes	Account ID

Request

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

Response 422

{
  "message": "You can not delete the account with a balance of 150 USD",
  "code": "account_not_empty",
  "errors": {
    "account_id": [
      "You can not delete the account with a balance of 150 USD"
    ]
  }
}

The response is status 204 with no body.

Only an empty account can be deleted. If there is money on it — 422 with an error in the account_id field; debit the remaining balance first.

addFundsToContactAccount

Tops up an account.

POSThttps://watbot.org/api/v1/addFundsToContactAccount

Parameter	Type	Required	Description
`account_id`	integer	yes	Account ID
`amount`	integer	yes	Amount in the currency's minor units, from 1 to 100,000,000,000,000 (10¹⁴)
`description`	string	yes	What the deposit is for, up to 255 characters. Goes into the account journal

Request

curl -X POST "https://watbot.org/api/v1/addFundsToContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 15000, "description": "Bonus for order A-1024"}'

Response 200

{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 15000,
    "amount_note": "150 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:05:41+00:00",
    "blocked_at": null
  }
}

A blocked account can still be topped up.

withdrawFundsFromContactAccount

Debits an account.

POSThttps://watbot.org/api/v1/withdrawFundsFromContactAccount

Parameter	Type	Required	Description
`account_id`	integer	yes	Account ID
`amount`	integer	yes	Amount in the currency's minor units, from 1 to 100,000,000,000,000 (10¹⁴)
`description`	string	yes	What the debit is for, up to 255 characters. Goes into the account journal

Request

curl -X POST "https://watbot.org/api/v1/withdrawFundsFromContactAccount" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"account_id": 4521, "amount": 5000, "description": "Delivery fee"}'

Response 200

{
  "data": {
    "id": 4521,
    "currency": "USD",
    "amount": 10000,
    "amount_note": "100 USD",
    "created_at": "2026-10-03T12:00:00+00:00",
    "updated_at": "2026-10-03T12:07:15+00:00",
    "blocked_at": null
  }
}

Response 422

{
  "message": "Insufficient funds. Current balance 100 USD",
  "code": "insufficient_funds",
  "errors": {
    "account_id": [
      "Insufficient funds. Current balance 100 USD"
    ]
  }
}

A debit never takes the account below zero, even with simultaneous requests. If the debit is not possible, the method changes nothing and responds with 422 and an error in the account_id field:

`code`	Reason
`account_blocked`	The account is blocked — unblock it on the contact card
`insufficient_funds`	The account holds less than `amount`; the text shows the current balance

The block is checked first, then the balance.

Account errors

No contact or account with that ID, the contact is deleted, or its bot is deleted — 404.
Contact or account from someone else's bot — 403.
Errors specific to these methods are 422 with message, code and errors fields. The error text is in the request language (the Accept-Language header), so check code in your code:

`code`	Method	Reason
`currency_exists`	`addContactAccount`	An account in this currency already exists
`account_not_empty`	`deleteContactAccount`	There is money left on the account
`account_blocked`	`withdrawFundsFromContactAccount`	The account is blocked
`insufficient_funds`	`withdrawFundsFromContactAccount`	Not enough money on the account

General API errors are described under Errors.

Contact accounts#

getContactAccounts#

addContactAccount#

deleteContactAccount#

addFundsToContactAccount#

withdrawFundsFromContactAccount#

Account errors#

Contact accounts

getContactAccounts

addContactAccount

deleteContactAccount

addFundsToContactAccount

withdrawFundsFromContactAccount

Account errors