Работа с инструментами 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: человек создаёт новый ключ (см. Подключённые программы и ключи доступа).

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

Три инструмента бизнеса не требуют: 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 — продукт ответил не так, как ждали, или не ответил вовсе. Это не приговор запросу: повторите позже.

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

Бизнес платит за работу деньгами в долларах (см. Низкий баланс и блокировки). Статус 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 (см. Поиск по знаниям).