Working with the tools of Talemo

Talemo is the record layer of a service business, and its tools go through the same product API as the web and the mobile app. Whatever the product enforces — rights of a role, rules of a branch, the check that a booking does not overlap — applies to a tool as well. A tool is never a way round a refusal.

Which business a call is for

A tool that works on the data of a business takes business_id.

• A business key on a computer (Claude Desktop and other programs) acts on behalf of the person who created it, in one business only. talemo_list_businesses names that business, and its ID goes in business_id.
• A connection of Claude or ChatGPT acts with the rights of the person who connected it, in the businesses they chose when connecting. talemo_list_businesses names those businesses; the ID of one of them goes in business_id. The person changes the choice by connecting Talemo again.
• A business that is not on the list is refused with door.business_forbidden. A missing, revoked or expired key is refused with auth.required: the person creates a new key (see Connected programs and access keys).

talemo_list_businesses also shows each business with its open branches, the time zone of every branch and the vertical of the business. The industry decides what the business calls its masters, places and devices, so say these words to the person as their industry does (see Industry kits).

Three tools need no business: talemo_ready says whether Talemo and its database are answering, talemo_list_businesses names the businesses, and talemo_get_zone_currency names the usual currency of a time zone — to ask the person about, never to set on its own. The two tools of this guide need none either.

Showing a change before making it

Every tool that changes something takes dry_run. With it nothing changes, and the answer is what the change would be — or the refusal it would get. Show the person the preview, and make the real call after they agree.

A tool that changes a lot at once says so in its description. Never make its real call before the person has seen its dry_run and said yes.

A refusal is an answer

A refused call comes back as a tool error with code, status, params and hint — why it was refused and how to fix it. Most refusals are legitimate answers, not failures: the product says what the state of the business allows. Tell the person, and change the plan; do not retry the same call.

• Status 409 — the state forbids the call: a time already taken (slot.overlap), a resource with bookings ahead (resource.has_bookings), a way to reach that belongs to another contact (contact.taken). The code and params name what to change.
• role.forbidden — the role of the person has no right for this; params.capability names it. Tell the person; it is not something a tool can change.
• role.field_forbidden — a field of a card is closed to the role. Closed fields are missing from the answers, and sending one is refused.
• kit.required — the tool belongs to an industry kit that is not installed in this business; params.kit names the kit. The tools of such a kit are not in the list for it.
• not_found — there is no such record, or the role sees only its own records and this one is not its.
• request.body_invalid — an argument is wrong; params.field names it.
• auth.required — the connection is not allowed to do this. Where Talemo reserves a change for a person (knowledge, service languages, rights of the online admin), it means "the person does it in Talemo", and the connection is not broken.
• client.… and status 0 — the product did not answer as expected, or did not answer at all. This is not a verdict on the request: try again later.

When the balance runs out

A business pays for its work with money in dollars (see Low balance and blocks). Status 402 with billing.blocked means the hard block, and any tool of a business can give it: until a person tops the business up on the website of Talemo, nothing of the tools of a business works but talemo_get_billing, and params.deletesAt says when the business goes to the archive. talemo_ready, talemo_list_businesses, talemo_get_zone_currency and both tools of the guide work even then. Status 402 with billing.credits_exhausted is given not by any tool but only by an operation that spends money on AI: it means the balance is down to the reserve, AI stops in the business until a top-up, and the tools without AI keep working. Neither is a failure. A tool cannot pay, so tell the person.

Reading this guide

talemo_find_guide_topics finds topics of the guide: pass query with the words of a question or the name of a tool, module to list one folder, or nothing for the contents. talemo_get_guide_topic reads one topic whole by its id, like booking/visits.

Read the topic of a module before acting in it if you have not worked in it during this conversation. Every tool description ends with its topic as Guide: folder/slug. The same topics are public at talemo.app/docs.

The guide tells how Talemo works. What a business itself says to its clients — prices it names, rules it keeps, its voice — is its knowledge, and it is found with talemo_find_knowledge (see Searching the knowledge).