Contact variables#

These methods read, write and delete contact variables — the same ones the bot fills in during a scenario and shows on the contact card. For example, your website can save an order number to a variable, and the bot can insert it into a message as {{ $order_number }} (see Templates for details).

The contact ID (contact_id) is shown in the header of the contact card and in the first column of the contact list.

getContactVariables#

Returns all variables of a contact.

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

{
  "data": [
    {
      "id": 17594321098765,
      "name": "city",
      "value": "Denver",
      "deletable": false,
      "variable": {
        "id": 17594321098765,
        "name": "Denver"
      }
    },
    {
      "id": 17594321112233,
      "name": "order_number",
      "value": "A-1024",
      "deletable": false,
      "variable": {
        "id": 17594321112233,
        "name": "A-1024"
      }
    }
  ]
}

Variables are listed in the order they were created. If there are none, data is an empty array.

setContactVariable#

Writes a value to a contact variable. If there is no variable with this name, it is created; if there is, its value is replaced.

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

{
  "data": {
    "id": 17594321112233,
    "name": "order_number",
    "value": "A-1024",
    "deletable": false,
    "variable": {
      "id": 17594321112233,
      "name": "A-1024"
    }
  }
}

{
  "message": "The contact already has 5000 variables — a new one cannot be added.",
  "error": "The contact already has 5000 variables — a new one cannot be added.",
  "code": "variables_limit",
  "errors": {
    "name": ["The contact already has 5000 variables — a new one cannot be added."]
  }
}

Details:

• You cannot write an empty value: value is required. To clear a variable, delete it with deleteContactVariable.
• When you write to an existing variable, deletable is overwritten too: if the parameter is omitted, it becomes false.
• The name of a new variable is added to the bot's "User variable hints" list, so it appears in the account's suggestions and in the contact export. If the list already holds 5000 names, the new name is not added to it, but the contact's variable is still written.
• A contact can have at most 5000 variables. Beyond that the method does not create a new one and responds with 422 and code: "variables_limit". Writing to an existing variable always works.
• Contact not found, deleted, or its bot deleted — 404; contact from someone else's bot — 403.

deleteContactVariable#

Deletes a contact variable by ID or by name.

If both are passed, name is used; if there is no variable with that name, id is used.

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

The response is status 204 with no body.

Details:

• If the contact has no such variable, the method still responds with 204.
• The name is not removed from the bot's hint list.
• Contact not found, deleted, or its bot deleted — 404; contact from someone else's bot — 403.

General API errors are described under Errors.