Tags#

These methods show the tags of a bot and a contact, and assign and remove them. For example, after a payment on your website you can give the contact the tag "paid", then check it in a scenario with the Condition block or use it to pick mailing recipients.

A tag is just a string: you do not need to create it in advance. Case matters: "VIP" and "vip" are different tags.

getBotTags#

Returns the bot's "Tag hints" list — tag names that were typed in the account.

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

{
  "data": ["vip", "paid", "newcomer"]
}

Details:

• The hint list is not a complete list of contacts' tags. It contains names entered in the account and new tags set with attachTagToContact (while the list holds fewer than 5000 names). Tags set by scenario blocks are not added to it on their own, and removing a name from the list does not remove the tag from contacts.
• Bot not found or deleted — 404; someone else's bot — 403.

getContactTags#

Returns a contact's tags.

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

{
  "data": ["vip", "paid"]
}

If the contact has no tags, data is an empty array. Contact not found, deleted, or its bot deleted — 404; contact from someone else's bot — 403.

attachTagToContact#

Assigns a tag to a contact.

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

{
  "message": "The contact already has 1000 tags — no more can be added.",
  "error": "The contact already has 1000 tags — no more can be added.",
  "code": "tags_limit",
  "errors": {
    "name": ["The contact already has 1000 tags — no more can be added."]
  }
}

The response is status 204 with no body.

Details:

• If the contact already has the tag, it is not added a second time — the response is the same 204.
• A contact can have at most 1000 tags. Beyond that the method does not set a new tag and responds with 422 and code: "tags_limit".
• A new tag is also added to the bot's hint list — getBotTags returns it.
• Contact not found, deleted, or its bot deleted — 404; contact from someone else's bot — 403.

detachTagFromContact#

Removes a tag from a contact.

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

The response is status 204 with no body. If the contact did not have the tag, the response is the same.

Contact not found, deleted, or its bot deleted — 404; contact from someone else's bot — 403.

General API errors are described under Errors.