Clients tools
On this page
- talemo_add_contact_point
- talemo_categorize_contacts
- talemo_create_contact
- talemo_create_contact_category
- talemo_find_contacts
- talemo_get_contact
- talemo_get_contact_history
- talemo_list_contact_categories
- talemo_remove_contact_category
- talemo_remove_contact_point
- talemo_set_primary_contact
- talemo_turn_off_contact_notices
- talemo_turn_on_contact_notices
- talemo_update_contact
- talemo_update_contact_category
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_add_contact_point
Add a way to reach a contact
Add a way to reach a contact: phone, email, WhatsApp, Telegram or Instagram. A number without + needs its country (contact.country_required) — ask the person. One that already belongs to another contact of the business is refused with contact.taken; one the contact already has is returned as it is.
Guide: clients/contact-points.
- Changes data
- The same call twice gives the same result
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
address | string | required | The number, email or @name as the person said it. |
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. |
channel | string | required | phone, email, whatsapp, telegram or instagram. |
country | string | optional | ISO 3166-1 alpha-2 country of a number without + or 00, like RU or DE. If you do not know it, ask the person. |
dry_run | boolean | optional | True — add nothing and answer the way to reach as it would be. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Phone, email and messengers of a contact
talemo_categorize_contacts
Move contacts to a category
Move several contacts to one category at once, all or nothing. Returns how many changed their category; those already in it do not count. When: the person asks to move contacts to a category. How: parties — contact IDs; category — an ID from talemo_list_contact_categories. Next: say how many changed; a refusal changes none. It changes a lot at once: call it with dry_run first, show the person what changes and make the real call only after they say yes.
Guide: clients/contact-categories.
- 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. |
category | string | required | Category ID to move them to: talemo_list_contact_categories lists them. |
dry_run | boolean | optional | True — change nothing and answer how many contacts would change their category. |
parties | array of string | required | Contact IDs, 1 to 500: in a conversation, party.party_id of talemo_get_conversation is the client. Staff: talemo_find_contacts finds the other contacts. |
Described in: Contact categories, Ignore, Spam and the client's "stop"
talemo_create_contact
Add a contact
Create a contact with its category and the ways to reach it. A number without + needs its country: status 400, code contact.country_required — ask the person. A way to reach that already belongs to another contact of the business is refused with status 409, code contact.taken; find that contact with talemo_find_contacts by the digits instead of creating a second one.
Guide: clients/contact-card.
- 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. |
category | string | required | Category ID of the contact: talemo_list_contact_categories lists them; for a client it is the category with system client. |
dry_run | boolean | optional | True — add nothing and answer the contact as it would be. |
email | array of string | optional | Email addresses. |
family_name | string | optional | Family name, 1 to 120 characters. |
messengers | array of object | optional | WhatsApp, Telegram and Instagram. |
messengers[].address | string | required | A number for WhatsApp and Telegram, or @name for Telegram and Instagram. |
messengers[].channel | string | required | whatsapp, telegram or instagram. |
messengers[].country | string | optional | ISO 3166-1 alpha-2 country of a number without + or 00. |
name | string | required | First name as the business calls the person, 1 to 120 characters. |
note | string | optional | What is worth knowing about the person, up to 2000 characters. |
phone | array of object | optional | Phone numbers. |
phone[].address | string | required | The number as the person said it: +49 176 2041 1380, or a local number like 8 916 204-18-21 together with country. |
phone[].country | string | optional | ISO 3166-1 alpha-2 country of a number without + or 00, like RU or DE. If you do not know it, ask the person: the time zone of the branch does not tell. |
Described in: Contact card (client card)
talemo_create_contact_category
Add a contact category
Add a contact category of the business's own, at the end of the list. A name another category uses is refused with record.duplicate.
Guide: clients/contact-categories.
- 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 category as it would be. |
name | string | required | Name of the category, 1 to 60 characters, not used by another category of the business. |
Described in: Contact categories
talemo_find_contacts
Find contacts
Find the contacts of a business — clients, suppliers, people who wrote and are not sorted yet: by the start of a first or family name, by three or more digits of a number, or by the start of an email or @name, in one category or in all. Each contact has its category and the ways to reach it that the role may see. Pass next as after for more.
Guide: clients/contact-card.
- Reads only, changes nothing
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
after | string | optional | Continue after this contact: next of the previous answer. |
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. |
category | string | optional | Category ID to look in one category: talemo_list_contact_categories lists them. Left out — every category. |
limit | integer | optional | How many contacts, 1 to 100; 50 when left out. |
q | string | optional | What to look for: the start of a first or family name, three or more digits of a number anywhere in it, or the start of an email or @name. Left out — every contact. |
Described in: A client in Instagram and confirmations in WhatsApp, Contact card (client card)
talemo_get_contact
See a contact
Show one contact: its name, category, note, language, opt_out (set when the client or the team turned off the reminders, the confirmations and the cancellation notices of the whole card) and the ways to reach it — for each, whether it is the main one, where the reminders about a visit go, and since when the client has confirmed it by writing from it. Fields the role closes are missing.
Guide: clients/contact-card.
- 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. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Contact card (client card), Note and hidden fields, Phone, email and messengers of a contact, Turning off reminders, confirmations and cancellation notices
talemo_get_contact_history
See the history of a contact
Show what happened to a contact, newest first: who did it — a person, the assistant at a person's request, a program on a person's behalf, a channel (actor = channel, no person in by, channel_kind names it: the contact wrote first in WhatsApp, Instagram or Messenger), or the online admin (actor = participant, no person in by; approved_by is the person who approved its action, without a name if they have left the team, and empty if nobody approved it) — and when: created, fields changed, moved between categories, ways to reach added, removed or changed, confirmed by the client writing from them or made the main one. Values are not in the history; the contact shows them. Pass next as before for older entries.
Guide: clients/contact-history.
- Reads only, changes nothing
Parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
before | string | optional | Entries older than this one: next of the previous answer. |
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. |
limit | integer | optional | How many entries, 1 to 100; 20 when left out. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Contact history
talemo_list_contact_categories
See contact categories
List the contact categories of a business in their order. count says how many contacts each holds, as many as the role sees — all of them, or only its own — and is missing for a role that may not see contacts. The system ones — client, unsorted, spam — hold the behaviour of the product and cannot be removed; a kit adds its own, the business adds and names its own. name is empty for a category that keeps its standard name. When: before you move contacts to a category, to take its ID. How: no arguments. Next: category of talemo_categorize_contacts takes an ID from here.
Guide: clients/contact-categories.
- 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. |
Described in: Contact categories, Ignore, Spam and the client's "stop", What the kit installs
talemo_remove_contact_category
Remove a contact category
Remove a contact category: its contacts move to move_to in the same step, and each keeps a history line. A system category is refused with status 409, code party_category.system. With dry_run nothing changes and the answer tells how many contacts would move: moved is there only for a role that sees all contacts. A role that sees only its own contacts, or none, gets no moved, and the category may hold contacts it cannot see: all of them move, so name move_to anyway. It changes a lot at once: call it with dry_run first, show the person what changes and make the real call only after they say yes.
Guide: clients/contact-categories.
- 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. |
category_id | string | required | Category ID: talemo_list_contact_categories lists them. |
dry_run | boolean | optional | True — change nothing and tell how many contacts would move. |
move_to | string | optional | Category ID where the contacts of the removed category move. Needed when it holds contacts. |
Described in: Contact categories
talemo_remove_contact_point
Remove a way to reach a contact
Remove a way to reach a contact. The contact's history keeps a line that it was removed. Returns the contact as it is now.
Guide: clients/contact-points.
- Changes data
- May overwrite or remove existing 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. |
contact_id | string | required | ID of the way to reach the contact: talemo_get_contact lists them. |
dry_run | boolean | optional | True — change nothing and answer the contact as it would be. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Phone, email and messengers of a contact
talemo_set_primary_contact
Set the main way to reach a contact
Make one way to reach a contact the main one: the address where the client gets the reminders about a visit. Only a way the client has confirmed by writing from it can be main; another is refused with status 409 and code contact.unconfirmed. The way that was main stops being main. The one already main is returned as it is. The contact's history keeps a line. Returns the contact as it is now.
Guide: clients/contact-points.
- 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. |
contact_id | string | required | ID of the way to reach the contact: talemo_get_contact lists them. |
dry_run | boolean | optional | True — change nothing and answer the contact as it would be. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Phone, email and messengers of a contact
talemo_turn_off_contact_notices
Turn off reminders for a contact
Stop the reminders about a visit, the booking confirmations and the cancellation notices that Talemo sends to a contact, because the client asked not to get them, for example on the phone. The mark is put on the way you name, and it holds for the whole card: nothing automatic goes to any of its ways, in any channel, not even a confirmation or a cancellation notice in an open chat window, and what already stands in the queue of a channel is taken out. The client can also stop them by writing STOP: then the card already shows opt_out with source client_word, and the call returns the contact as it is. Returns the contact as it is now: the card shows opt_out with source person, and the way shows its own opt_out. The contact's history keeps a line. talemo_turn_on_contact_notices is the way back.
Guide: clients/reminders-opt-out.
- 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. |
contact_id | string | required | ID of the way to reach the contact: talemo_get_contact lists them. |
dry_run | boolean | optional | True — change nothing and answer the contact as it would be. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Turning off reminders, confirmations and cancellation notices
talemo_turn_on_contact_notices
Turn reminders back on for a contact
Send the reminders about a visit, the booking confirmations and the cancellation notices to a contact again. Use it only when the client asked to get them back: it is the one action that undoes STOP or an earlier talemo_turn_off_contact_notices. It takes off every opt-out of the whole card, whichever way you name. The contact's history keeps who did it and when. A card that has no opt-out is returned as it is. Returns the contact as it is now.
Guide: clients/reminders-opt-out.
- 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. |
contact_id | string | required | ID of the way to reach the contact: talemo_get_contact lists them. |
dry_run | boolean | optional | True — change nothing and answer the contact as it would be. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: A client in Instagram and confirmations in WhatsApp, Turning off reminders, confirmations and cancellation notices
talemo_update_contact
Change a contact
Change the first name, family name, note or language of a contact, or move it to another category. The language is one the business serves, like ru or en; the client's reminders go in it. Fields left out stay as they are. A field the role closes is refused with role.field_forbidden.
Guide: clients/contact-card.
- 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. |
category | string | optional | Category ID to move the contact to. Left out — stays. |
dry_run | boolean | optional | True — change nothing and answer the contact as it would be. |
family_name | string | optional | New family name; an empty string removes it. Left out — stays. |
language | string | optional | Language of the client, like ru or en: one the business serves; the reminders about a visit go in it. An empty string removes it. Left out — stays. |
name | string | optional | New first name, 1 to 120 characters. Left out — stays as it is. |
note | string | optional | New note, signed with the person's name; an empty string removes it. Left out — stays. |
party_id | string | required | Contact ID: talemo_find_contacts finds them. |
Described in: Contact card (client card), Note and hidden fields
talemo_update_contact_category
Rename or move a contact category
Rename a contact category or move it in the list. A system category can be renamed but keeps its place.
Guide: clients/contact-categories.
- 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. |
category_id | string | required | Category ID: talemo_list_contact_categories lists them. |
dry_run | boolean | optional | True — change nothing and answer the category as it would be. |
name | string | optional | New name, 1 to 60 characters; an empty string gives a system or kit category its standard name back. Left out — stays. |
position | integer | optional | New place among the kit and own categories: smaller is higher. A system category has no place. Left out — stays. |
Described in: Contact categories