---
title: Работа с инструментами Talemo
summary: Для какого бизнеса вызов, как показать изменение до того, как его сделать, как выглядит отказ и какие отказы — простые ответы; инструменты без бизнеса и как читать это руководство.
tools: [talemo_ready, talemo_list_businesses, talemo_get_zone_currency, talemo_find_guide_topics, talemo_get_guide_topic]
related: [../account/connected-programs-and-keys, ../account/team-and-roles, ../kits/industry-kits, ../money/low-balance-stages, ../knowledge/knowledge-search]
search: [MCP сервер Talemo, API Talemo для ИИ-агентов, как работать с инструментами Talemo, подключить Claude к Talemo, подключить ChatGPT к Talemo, проверка изменения до записи (dry_run), коды отказов инструментов, ошибка «не хватает денег на балансе», отказ, auth.required, role.forbidden, kit.required, billing.credits_exhausted, billing.blocked]
---

# Работа с инструментами Talemo

Talemo — слой записей сервисного бизнеса, а его инструменты ходят в тот же API
продукта, что веб и мобильное приложение. Всё, что продукт требует, — права роли,
правила филиала, проверка, что запись не пересекается с другой, — действует и для
инструмента. Инструмент — не способ обойти отказ.

## Для какого бизнеса вызов

Инструмент, который работает с данными бизнеса, принимает `business_id`.

- **Ключ бизнеса на компьютере** (Claude Desktop и другие программы) действует от
  имени человека, который его создал, и только в одном бизнесе. Этот бизнес
  называет `talemo_list_businesses`, его ID идёт в `business_id`.
- **Подключение Claude или ChatGPT** действует с правами человека, который его
  подключил, в тех бизнесах, которые он выбрал при подключении.
  `talemo_list_businesses` называет эти бизнесы; ID одного из них идёт в
  `business_id`. Выбор человек меняет, подключив Talemo заново.
- Бизнес не из списка отклоняется с `door.business_forbidden`. Нет ключа, он
  отозван или истёк — отказ `auth.required`: человек создаёт новый ключ (см.
  [Подключённые программы и ключи доступа](../account/connected-programs-and-keys.md)).

`talemo_list_businesses` показывает и открытые филиалы бизнеса, пояс каждого
филиала и `vertical` бизнеса. От отрасли зависит, как бизнес называет мастеров,
места и аппараты, поэтому человеку называйте их так, как называет его отрасль (см.
[Отраслевые наборы](../kits/industry-kits.md)).

Три инструмента бизнеса не требуют: `talemo_ready` отвечает, работают ли Talemo и
его база, `talemo_list_businesses` называет бизнесы, а `talemo_get_zone_currency`
называет обычную валюту пояса — спросить о ней человека, а не поставить самому.
Два инструмента этого руководства бизнеса тоже не требуют.

## Показать изменение, прежде чем его сделать

Каждый инструмент, который что-то меняет, принимает `dry_run`. С ним ничего не
меняется, а в ответе — то, чем стало бы изменение, или отказ, который оно бы
получило. Покажите человеку показ и делайте настоящий вызов, когда он согласится.

Инструмент, который меняет много сразу, говорит об этом в своём описании. Его
настоящий вызов нельзя делать, пока человек не увидел его `dry_run` и не сказал «да».

## Отказ — это ответ

Отказанный вызов приходит ошибкой инструмента с `code`, `status`, `params` и `hint` —
почему отказано и как исправить. Большая часть отказов — законные ответы, а не сбои:
продукт говорит, что позволяет состояние бизнеса. Скажите человеку и измените план;
тот же вызов не повторяйте.

- **Статус 409** — состояние не позволяет вызов: время уже занято (`slot.overlap`),
  у ресурса есть записи впереди (`resource.has_bookings`), способ связи принадлежит
  другому контакту (`contact.taken`). Что менять, называют код и `params`.
- **`role.forbidden`** — у роли человека нет на это права; `params.capability`
  называет право. Скажите человеку: инструментом это не изменить.
- **`role.field_forbidden`** — поле карточки закрыто для роли. Закрытых полей в
  ответах нет, а присланное закрытое поле отклоняется.
- **`kit.required`** — инструмент относится к отраслевому набору, которого в этом
  бизнесе нет; `params.kit` называет набор. Инструментов такого набора в списке
  бизнеса нет.
- **`not_found`** — такой записи нет, либо роль видит только свои записи, а эта не её.
- **`request.body_invalid`** — неверный аргумент; `params.field` называет его.
- **`auth.required`** — подключению это делать не разрешено. Где Talemo оставляет
  изменение за человеком (знания, языки обслуживания, права онлайн-администратора),
  это значит «человек делает это в Talemo», и подключение не сломано.
- **`client.…` и статус 0** — продукт ответил не так, как ждали, или не ответил
  вовсе. Это не приговор запросу: повторите позже.

## Когда баланс кончается

Бизнес платит за работу деньгами в долларах (см. [Низкий баланс и блокировки](../money/low-balance-stages.md)).
Статус 402 с `billing.blocked` — жёсткая блокировка, и его даёт любой инструмент
бизнеса: до пополнения человеком на сайте Talemo из инструментов бизнеса не
работает ничего, кроме `talemo_get_billing`, а `params.deletesAt` говорит, когда
бизнес уйдёт в архив. `talemo_ready`, `talemo_list_businesses`,
`talemo_get_zone_currency` и оба инструмента руководства работают и тогда.
Статус 402 с `billing.credits_exhausted` даёт не любой инструмент, а только
операция, которая тратит деньги на ИИ: он значит, что баланс дошёл до запаса, ИИ
в бизнесе останавливается до пополнения, а инструменты без ИИ работают. Ни то ни
другое не сбой. Инструмент не умеет платить, поэтому скажите человеку.

## Как читать это руководство

`talemo_find_guide_topics` ищет темы руководства: в `query` передают слова вопроса
или имя инструмента, в `module` — папку, чтобы перечислить её темы, а без
аргументов получают оглавление. `talemo_get_guide_topic` читает тему целиком по её
id, например `booking/visits`.

Если в этом разговоре вы ещё не работали в модуле, прочтите его тему до действия.
Описание каждого инструмента кончается его темой: `Guide: папка/слаг.`. Те же темы
открыты на сайте talemo.app/docs.

Руководство говорит, как устроен Talemo. То, что бизнес сам говорит клиентам, —
цены, которые он называет, правила, которые он держит, его голос, — это его знания, и
их ищут `talemo_find_knowledge` (см. [Поиск по знаниям](../knowledge/knowledge-search.md)).