Online admin tools
On this page
Most tools take business_id: the business the call is for. talemo_list_businesses names the businesses this connection works in. A tool that changes something also takes dry_run; with it nothing changes, and the answer shows what the change would be, or the refusal it would get.
talemo_create_conversation_field
Add a conversation field
Add a conversation field to the business, at the end of the list unless a place is named. An option label goes on a button in every channel: longer than 20 characters in some language is refused with request.body_invalid and params.max. A translation goes only to a language the business serves, other than the first. A key another field holds, removed ones too, is refused with record.duplicate.
Guide: admin-online/conversation-fields.
- Changes data
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
dry_run | boolean | optional | True — add nothing and answer the field as it would be. |
hint | string | optional | A note for the team and the online admin, 1 to 60 characters: "in euros", "who recommended". |
key | string | optional | Key of the field: latin letters, digits and _, from a letter, up to 40 characters; it never changes. Left out — it comes from the label. |
kind | string | required | choice — one option; list — several; number; yes_no; text — up to 200 characters. |
label | string | required | Label in the first language the business serves, 1 to 60 characters. |
label_tr | object with string values | optional | Translations of the label by language the business serves, the whole map: {"en": "Best time"}. |
options | array of object | optional | Options: 2 to 50 for choice and list, two for yes_no (yes, then no), none for number and text. |
options[].key | string | optional | Key of the option: latin letters, digits and _, from a letter, up to 40 characters. Left out — a new option, its key comes from the label; a key the field has — the same option with a new label. A yes_no field has yes and no. |
options[].label | string | required | Label in the first language the business serves: it goes on a button in every channel, so 20 characters at most. |
options[].label_tr | object with string values | optional | Translations of the label by language the business serves, the whole map: {"en": "Evening"}. |
position | integer | optional | Place in the list: smaller is higher. Left out — at the end. |
Described in: Conversation fields ("What we write down")
talemo_get_conversation_script
See the script of the online admin
Show the conversation script of the online admin for the whole business or a branch: the steps it asks a client in order — each with its question in the first language of service, its translations and the field its answer is written into, whose options are the buttons of the step — and the rules it keeps. A branch without its own script follows the script of the business (inherited). version is what talemo_set_conversation_script takes as base_version.
Guide: admin-online/conversation-script.
- Reads only, changes nothing
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
branch_id | string | optional | Branch ID; omitted — the script of the whole business. |
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
Described in: Conversation script (chat steps), Explaining the online admin to a salon owner, Online admin script of a branch, What the kit installs
talemo_list_conversation_fields
See conversation fields
List the conversation fields of a business — what it writes down about a conversation: the key, the kind (choice, list, number, yes_no, text), the label in the first language the business serves and its translations — stale when the label changed after — the options, the note, and in how many conversations the field is filled. The languages the business serves come along, the first is the one labels are written in. The online admin sets the fields by the steps of the conversation script; a person can correct them. When: before you set a field, to take its key, kind and options. How: retired adds the removed fields. Next: talemo_set_conversation_fields takes the key and a value of the kind.
Guide: admin-online/conversation-fields.
- Reads only, changes nothing
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
retired | boolean | optional | True — the removed fields too, after the live ones. |
Described in: Conversation field values, Conversation fields ("What we write down"), Explaining the online admin to a salon owner, How the online admin leads a conversation by the script, Removing and restoring a field, What the kit installs
talemo_remove_conversation_field
Remove a conversation field
Remove a conversation field: no new values, the ones set stay, but it leaves the list, the filters and the export. A field a step of the conversation script asks for is refused with status 409, code conversation_field.in_script and params.step (from 1), params.branch_id for a script of a branch. talemo_restore_conversation_field returns it. Ask the person before removing.
Guide: admin-online/remove-and-restore-fields.
- Changes data
- May overwrite or remove existing data
- The same call twice gives the same result
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
dry_run | boolean | optional | True — change nothing and answer the field as it would be. |
field_id | string | required | Field ID: talemo_list_conversation_fields lists them. |
Described in: Removing and restoring a field
talemo_restore_conversation_field
Bring a conversation field back
Return a removed conversation field with its values, to its old place.
Guide: admin-online/remove-and-restore-fields.
- Changes data
- The same call twice gives the same result
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
dry_run | boolean | optional | True — change nothing and answer the field as it would be. |
field_id | string | required | Field ID: talemo_list_conversation_fields lists them. |
Described in: Removing and restoring a field
talemo_set_conversation_fields
Fill in the fields of a conversation
Set or correct the conversation fields of one conversation by key: talemo_list_conversation_fields names the fields and their options. The same value changes nothing. When: the client told something that a field asks for; never to guess, never to fill a field for its own sake. How: values — the key of the field and a value of its kind, from talemo_list_conversation_fields. Next: leave a field a person set (conversation.field_by_person) and say nothing about it to the client. A value that does not fit the field is refused with conversation_field.value_invalid, a removed field with conversation_field.retired, an unknown key with record.reference_missing — params.field names it. A value a person set or cleared is the person's: the online admin does not change it, and its whole call is refused with conversation.field_by_person. Only a person clears a value.
Guide: admin-online/field-values.
- Changes data
- May overwrite or remove existing data
- The same call twice gives the same result
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
conversation_id | string | required | Conversation ID: talemo_list_conversations finds them. |
dry_run | boolean | optional | True — change nothing and answer the values as they would be. |
values | object | required | Field key → value by its kind: the key of an option for choice, a list of option keys for list, a number, true or false for yes_no, a text up to 200 characters; null clears the value. Fields left out stay. |
Described in: Conversation field values, How the online admin leads a conversation by the script
talemo_set_conversation_script
Set the script of the online admin
Set the whole conversation script of the online admin for the whole business or a branch; without body a branch goes back to the script of the business. It takes effect from the next reply of the online admin, in conversations already going too. If the script changed since base_version, the call is refused with status 409 and code conversation_script.version_conflict — read it again. A step asking a field the business does not have is refused with status 422 and code conversation_script.field_missing. While the quick questions of a channel are on, the first step of the script is what every client sees in the salon's own Instagram or Messenger, so the change reaches Meta within a minute — show it with dry_run first; the Talemo assistant asks the person then. Only a role for the whole business may set it.
Guide: admin-online/conversation-script.
- Changes data
- May overwrite or remove existing data
- The same call twice gives the same result
- Reaches outside Talemo
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
base_version | string | optional | The version you started from — version of talemo_get_conversation_script; omitted when there was no script. |
body | object | optional | The whole script: steps in order and rules. Omitted — the branch goes back to the script of the business; the script of the business is not removed this way. |
body.rules | array of object | optional | Rules the online admin keeps, at most 20. |
body.rules[].text | string | required | The rule in words, up to 500 characters. |
body.rules[].then | string | optional | handoff — the online admin hands the conversation to a person and stops; omitted — just a rule. |
body.steps | array of object | required | Steps in the order the online admin asks them, at most 20. |
body.steps[].field | string | optional | Key of the field the answer is written into; its options are the buttons of the step. Omitted — a step without a field. |
body.steps[].key | string | optional | Key of an existing step to keep it; omitted for a new step. |
body.steps[].question | string | required | What to ask, in the first language of service: an instruction to the online admin, not a ready reply; up to 500 characters. |
body.steps[].question_tr | object with object values | optional | Translations of the question by language of service other than the first: a translation in the client's language goes word for word. |
branch_id | string | optional | Branch ID; omitted — the script of the whole business. |
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
dry_run | boolean | optional | True — change nothing and answer what would happen. |
Described in: Conversation script (chat steps), Languages and translations of script texts, Online admin script of a branch
talemo_update_conversation_field
Change a conversation field
Change a conversation field: its labels, kind, options, note or place; the key never changes. Translations and options are sent whole. A field that already holds values keeps its kind, and an option chosen in some conversation stays: status 409, code conversation_field.has_values with params.count and params.option. A removed field is refused with conversation_field.retired — return it first. A translation left as it was goes stale when the label changes. While the quick questions of a channel are on, the options of the field the first step of the script asks are what every client sees in the salon's own Instagram or Messenger, so the change reaches Meta within a minute — show it with dry_run first; the Talemo assistant asks the person then.
Guide: admin-online/conversation-fields.
- Changes data
- May overwrite or remove existing data
- The same call twice gives the same result
- Reaches outside Talemo
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
business_id | string | required | Business ID: one of the businesses this connection may work in — talemo_list_businesses names them. Another business is refused with door.business_forbidden. |
dry_run | boolean | optional | True — change nothing and answer the field as it would be. |
field_id | string | required | Field ID: talemo_list_conversation_fields lists them. |
hint | string | optional | New note; an empty string removes it. Left out — stays. |
kind | string | optional | New kind; a field that already holds values keeps its kind. Left out — stays. |
label | string | optional | New label in the first language the business serves. Left out — stays. |
label_tr | object with string values | optional | Translations of the label, the whole map. Left out — stay. |
options | array of object | optional | Options, the whole list: one with a key of the field stays that option, one without a key is new, one left out goes — unless chosen in some conversation. Left out — stay. |
options[].key | string | optional | Key of the option: latin letters, digits and _, from a letter, up to 40 characters. Left out — a new option, its key comes from the label; a key the field has — the same option with a new label. A yes_no field has yes and no. |
options[].label | string | required | Label in the first language the business serves: it goes on a button in every channel, so 20 characters at most. |
options[].label_tr | object with string values | optional | Translations of the label by language the business serves, the whole map: {"en": "Evening"}. |
position | integer | optional | New place in the list: smaller is higher. Left out — stays. |
Described in: Conversation fields ("What we write down"), Languages and translations of script texts