How to update a chat via API: status, tags, assignee, fields

Modifying a chat via API is the same as editing a client card in the app: changing the status, assignee, tags, and fields. Everything is done with a single PATCH request, in which you pass only what y

Updated November 2, 20264 min

Modifying a chat via API is the same as editing a client card in the app: changing the status, assignee, tags, and fields. Everything is done with a single PATCH request, in which you pass only what you are changing.

In this article, you will learn how to change the status, assign a responsible person, add or remove a tag, fill in a field, create a new tag, and delete a chat.

Requirements

API key with Space controller role or higher. Creating tags and deleting chats can be done by Space manager or higher — API Key Permissions: Which Role to Assign.

Chat ID — How to get chats and messages via API.

How the chat modification request is structured

Chat is modified by the PATCH /chats/v1/{chat_id} request. Space controller role or higher is required.

PATCH

https://api.chatterfy.ai/public-api/chats/v1/{chat_id}

Modify chat

In the body, pass only the fields you are changing. The rest will remain as is. The response will contain the chat with the changes.

Field	What it changes
`status`	Chat status
`assign_id`	Assignee
`tags`	Tags: which ones to add and which to remove
`custom_fields`	Field values

An empty body {} will be rejected by the API, returning a no_fields error.

Change chat status

The chat status is changed by the status field in PATCH /chats/v1/{chat_id}. For example, this is how a chat is transferred to an agent:

curl -X PATCH 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"status": "manual"}'

Value	Status in the app	What it means
`ai`	Auto	AI conducts the dialogue automatically
`manual`	Manual	Dialogue is being handled manually by an operator
`blocked`	Blocked	Chat blocked by CRM
`stopped`	Stopped	The bot no longer writes to this dialogue

You can also pass start and ignore. Details on each status are in the article Chat Status — conversation statuses.

Assign a person responsible for the chat

The person responsible for the chat is set by the assign_id field in PATCH /chats/v1/{chat_id} — this is the ID of the Space member where the bot is located.

Find the employee ID

Request the members of the Space where the bot is located:

curl -X POST 'https://api.chatterfy.ai/public-api/spaces/v1/ID_SPACE/members/search' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Take the id of the required person from the accounts list.

Assign them to the chat

{
  "assign_id": "ID_СОТРУДНИКА",
  "status": "manual"
}

You can only assign a member of this bot's Space. Otherwise, the API will return an unknown_assignee error.

Add or remove a tag in the chat

Chat tags are passed by ID, not by name, in tags.assign and tags.remove of the PATCH /chats/v1/{chat_id} request. First, get the list of bot tags:

curl 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/tags' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Then, in tags.assign, list the tags you want to add, and in tags.remove, list the ones you want to remove. Other chat tags will remain unchanged.

{
  "tags": {
    "assign": ["ID_ТЕГА_ОПЛАТИЛ"],
    "remove": ["ID_ТЕГА_ДУМАЕТ"]
  }
}

The API will not accept a tag from another bot and will return an unknown_tag error.

Create or delete a bot tag

If the required tag does not exist yet, create it using a POST /bots/v1/{bot_id}/tags request. You need the Space manager role or higher.

curl -X POST 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/tags' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Оплатил", "color": "#2E7D32"}'

name — up to 64 characters, color — an optional color in #RRGGBB format. The response will contain the id of the new tag.

Delete a tag: DELETE /bots/v1/{bot_id}/tags/{tag_id}. The tag will be removed from the bot and from all chats where it was applied.

Fill in custom chat fields

Custom chat fields are passed in custom_fields by field ID. Get the list of bot fields:

curl 'https://api.chatterfy.ai/public-api/bots/v1/ID_БОТА/custom-fields' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Each field has an id, a key, and a name. In custom_fields, use the field id as the key, not the key:

{
  "custom_fields": {
    "ID_ПОЛЯ_ГОРОД": "Москва",
    "ID_ПОЛЯ_БЮДЖЕТ": "50000"
  }
}

Key is the field ID, not the key

If you use the field key as the key (e.g., city), the API will return an unknown_custom_field error. Values are passed as strings, even numbers.

What fields are and how to create them in the application is described in the article Custom Fields — custom fields.

Change status, tags, and fields in a single request

Status, assignee, tags, and fields can be passed in a single PATCH /chats/v1/{chat_id} request:

{
  "status": "manual",
  "assign_id": "ID_СОТРУДНИКА",
  "tags": { "assign": ["ID_ТЕГА"] },
  "custom_fields": { "ID_ПОЛЯ": "Москва" }
}

The API checks all IDs first, and if even one is invalid, it changes nothing.

Delete a chat via API

Delete a chat using the DELETE /chats/v1/{chat_id} request:

curl -X DELETE 'https://api.chatterfy.ai/public-api/chats/v1/ID_ЧАТА' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Deletion cannot be undone

The chat is deleted along with the entire conversation history. You need the Space manager role or higher.

FAQ

How to get chats and messages via API

Chats and messages via the API are read in two requests: first the list of bot chats, then the messages of the specific chat. This is the same as opening the bot in the application and tapping on a co

Chat filters in the API

Chat filters are conditions used by the API to select chats: for example, 'unread', 'with the tag Paid', or 'came from Google'. The same filter works in search, counting, exporting, and event subscrip

Tags — tags for segmentation

The Bot Settings → Tags section is for tags used to label leads. They are similar in concept to , but much more flexible: a single lead can have multiple tags at the same time. Use tags for everything

Custom Fields — custom fields

Custom Fields (Bot Settings → Custom Fields) — a section for creating additional fields in the customer card. Standard fields already exist in Chatterfy: name, username, status, and Telegram ID. But o

Was this article helpful?

How to update a chat via API: status, tags, assignee, fields

Requirements

How the chat modification request is structured

Change chat status

Assign a person responsible for the chat

Find the employee ID

Assign them to the chat

Add or remove a tag in the chat

Create or delete a bot tag

Fill in custom chat fields

Change status, tags, and fields in a single request

Delete a chat via API

FAQ

Why does the API return 403 even though chats can be read?

Can I pass a tag by name?

How do I remove a chat owner?

How do I change many chats at once?

Why does the chat still appear old in the list after changes?

Related